Metadata-Version: 2.1
Name: eth-ape
Version: 0.5.7
Summary: Ape Ethereum Framework
Home-page: https://github.com/ApeWorX/ape
Author: ApeWorX Ltd.
Author-email: admin@apeworx.io
License: Apache-2.0
Keywords: ethereum
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Requires-Python: >=3.8,<3.11
Description-Content-Type: text/markdown
Requires-Dist: click (<9,>=8.1.3)
Requires-Dist: ijson (<4,>=3.1.4)
Requires-Dist: importlib-metadata
Requires-Dist: ipython (<9,>=8.5.0)
Requires-Dist: packaging (<21,>=20.9)
Requires-Dist: pandas (<2,>=1.3.0)
Requires-Dist: pluggy (<2,>=1.0.0)
Requires-Dist: pydantic (<2,>=1.9.2)
Requires-Dist: PyGithub (<2,>=1.54)
Requires-Dist: pytest (<8.0,>=6.0)
Requires-Dist: python-dateutil (<3,>=2.8.2)
Requires-Dist: pyyaml (<7,>=6.0)
Requires-Dist: requests (<3,>=2.28.1)
Requires-Dist: rich (<13,>=12.5.1)
Requires-Dist: SQLAlchemy (>=1.4.35)
Requires-Dist: tqdm (<5.0,>=4.62.3)
Requires-Dist: traitlets (>=5.3.0)
Requires-Dist: watchdog (<3.0,>=2.1.9)
Requires-Dist: eth-abi (<4,>=3.0.1)
Requires-Dist: eth-account (<0.8,>=0.7)
Requires-Dist: eth-typing (<4,>=3.1)
Requires-Dist: eth-utils (<3,>=2.0.0)
Requires-Dist: hexbytes (<1,>=0.2.3)
Requires-Dist: py-geth (<4,>=3.8.0)
Requires-Dist: web3[tester] (==6.0.0b7)
Requires-Dist: eip712 (<0.2,>=0.1.4)
Requires-Dist: ethpm-types (<0.4,>=0.3.12)
Requires-Dist: evm-trace (>=0.1.0a12)
Requires-Dist: backports.cached-property ; python_version < "3.8"
Provides-Extra: dev
Requires-Dist: pytest-xdist ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Requires-Dist: pytest-mock ; extra == 'dev'
Requires-Dist: hypothesis (<7.0,>=6.2.0) ; extra == 'dev'
Requires-Dist: hypothesis-jsonschema (==0.19.0) ; extra == 'dev'
Requires-Dist: black (<23,>=22.10.0) ; extra == 'dev'
Requires-Dist: mypy (>=0.991) ; extra == 'dev'
Requires-Dist: types-PyYAML ; extra == 'dev'
Requires-Dist: types-requests ; extra == 'dev'
Requires-Dist: types-setuptools ; extra == 'dev'
Requires-Dist: pandas-stubs (==1.2.0.62) ; extra == 'dev'
Requires-Dist: types-SQLAlchemy (>=1.4.49) ; extra == 'dev'
Requires-Dist: flake8 (<6,>=5.0.4) ; extra == 'dev'
Requires-Dist: flake8-breakpoint (<2,>=1.1.0) ; extra == 'dev'
Requires-Dist: flake8-print (<5,>=4.0.0) ; extra == 'dev'
Requires-Dist: isort (<6,>=5.10.1) ; extra == 'dev'
Requires-Dist: myst-parser (<0.18,>=0.17.0) ; extra == 'dev'
Requires-Dist: sphinx-click (<4.0,>=3.1.0) ; extra == 'dev'
Requires-Dist: Sphinx (<5.0,>=4.4.0) ; extra == 'dev'
Requires-Dist: sphinx-rtd-theme (<2,>=1.0.0) ; extra == 'dev'
Requires-Dist: sphinxcontrib-napoleon (>=0.7) ; extra == 'dev'
Requires-Dist: setuptools ; extra == 'dev'
Requires-Dist: wheel ; extra == 'dev'
Requires-Dist: twine (==3.8.0) ; extra == 'dev'
Requires-Dist: commitizen (<2.20,>=2.19) ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: pytest-watch ; extra == 'dev'
Requires-Dist: ipdb ; extra == 'dev'
Provides-Extra: doc
Requires-Dist: myst-parser (<0.18,>=0.17.0) ; extra == 'doc'
Requires-Dist: sphinx-click (<4.0,>=3.1.0) ; extra == 'doc'
Requires-Dist: Sphinx (<5.0,>=4.4.0) ; extra == 'doc'
Requires-Dist: sphinx-rtd-theme (<2,>=1.0.0) ; extra == 'doc'
Requires-Dist: sphinxcontrib-napoleon (>=0.7) ; extra == 'doc'
Provides-Extra: lint
Requires-Dist: black (<23,>=22.10.0) ; extra == 'lint'
Requires-Dist: mypy (>=0.991) ; extra == 'lint'
Requires-Dist: types-PyYAML ; extra == 'lint'
Requires-Dist: types-requests ; extra == 'lint'
Requires-Dist: types-setuptools ; extra == 'lint'
Requires-Dist: pandas-stubs (==1.2.0.62) ; extra == 'lint'
Requires-Dist: types-SQLAlchemy (>=1.4.49) ; extra == 'lint'
Requires-Dist: flake8 (<6,>=5.0.4) ; extra == 'lint'
Requires-Dist: flake8-breakpoint (<2,>=1.1.0) ; extra == 'lint'
Requires-Dist: flake8-print (<5,>=4.0.0) ; extra == 'lint'
Requires-Dist: isort (<6,>=5.10.1) ; extra == 'lint'
Provides-Extra: recommended-plugins
Requires-Dist: ape-alchemy ; extra == 'recommended-plugins'
Requires-Dist: ape-ens ; extra == 'recommended-plugins'
Requires-Dist: ape-etherscan ; extra == 'recommended-plugins'
Requires-Dist: ape-foundry ; extra == 'recommended-plugins'
Requires-Dist: ape-hardhat ; extra == 'recommended-plugins'
Requires-Dist: ape-infura ; extra == 'recommended-plugins'
Requires-Dist: ape-ledger ; extra == 'recommended-plugins'
Requires-Dist: ape-solidity ; extra == 'recommended-plugins'
Requires-Dist: ape-template ; extra == 'recommended-plugins'
Requires-Dist: ape-tokens ; extra == 'recommended-plugins'
Requires-Dist: ape-trezor ; extra == 'recommended-plugins'
Requires-Dist: ape-vyper ; extra == 'recommended-plugins'
Provides-Extra: release
Requires-Dist: setuptools ; extra == 'release'
Requires-Dist: wheel ; extra == 'release'
Requires-Dist: twine (==3.8.0) ; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-xdist ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: pytest-mock ; extra == 'test'
Requires-Dist: hypothesis (<7.0,>=6.2.0) ; extra == 'test'
Requires-Dist: hypothesis-jsonschema (==0.19.0) ; extra == 'test'

# Quick Start

## Prerequisite

In the latest release, Ape requires:

- Linux or macOS
- Python 3.8 or later

**Windows**:

1.  Install Windows Subsystem Linux
    [(WSL)](https://docs.microsoft.com/en-us/windows/wsl/install)
2.  Choose Ubuntu 20.04 OR Any other Linux Distribution with Python
    3.8 or later

Check your python command by entering:

```bash
python3 --version
```

## Installation

There are 3 ways to install ape: `pipx`, `pip`, or `Docker`.

### via `pipx`

Install `pipx` via their [installation instructions](https://pypa.github.io/pipx/)

Then install `ape` via

```bash
pipx install eth-ape
```

To install Ape and a list of common, recommended plugins at the same time, do:

```bash
pipx install eth-ape'[recommended-plugins]'
```

### via `pip`

**Suggestion**: Create a virtual environment using `virtualenv` or `venv.`

You may skip creating a virtual environment if you know you don\'t require one for your use case.

- [virtualenv](https://pypi.org/project/virtualenv/)
- [venv](https://docs.python.org/3/library/venv.html)

**NOTE**: For MacOS users, we advise installing in a virtual environment to avoid interfering with OS-level site packages.

### virtualenv via `homebrew`

* (MacOS Option) Install via homebrew [brew](https://formulae.brew.sh/formula/virtualenv)

First, create your virtual environment folder:

```bash
python3 -m venv <path/to/new/env>
```

Then, activate your virtual environment:

```bash
source <venv_folder>/bin/activate
```

You should see `(name_of_venv) DESKTOP_NAME:~/path:$`.

To deactivate the virtual environment, do:

```bash
deactivate
```

Now that you have Python installed in your virtual environment, install the `eth-ape` Python package:
You can install the latest release via [pip](https://pypi.org/project/pip/):

```bash
pip install -U pip
pip install eth-ape
```

To install Ape and a list of common, recommended plugins at the same time, do:

```bash
pip install eth-ape'[recommended-plugins]'
```

### via `docker`

Please visit our [Dockerhub](https://hub.docker.com/repository/docker/apeworx/ape) for more details on using Ape with Docker.

```bash
docker run \
--volume $HOME/.ape:/root/.ape \
--volume $HOME/.vvm:/root/.vvm \
--volume $HOME/.solcx:/root/.solcx \
--volume $PWD:/root/project \
--workdir /root/project \
apeworx/ape compile
```

**Docker Uninstall Process:** You will need to remove files generated by docker

```bash
sudo rm -rf **\~/.solcx**
sudo rm -rf **\~/.vvm**
```

## Environment Variables:

Some plugins require environment variables to connect to their external systems, such project IDs or API keys.
Follow instructions from individual plugin documentations, such as:

* [ape-alchemy](https://github.com/ApeWorX/ape-alchemy/blob/main/README.md#quick-usage)
* [ape-infura](https://github.com/ApeWorX/ape-infura#readme)

Generally, set environment variables by doing the following:

```bash
# Used by the `ape-infura` plugin
export WEB3_INFURA_PROJECT_ID=<YOUR_INFURA_PROJECT_ID>
# Used by the `ape-alchemy` plugin
export WEB3_ALCHEMY_API_KEY=<YOUR_ALCHEMY_KEY>
```

Place these in environment files, such as your `.bashrc` or `.zshrc`.

## Quick Usage

Use `-h` to list all the commands:

```bash
ape -h
```

### Projects

When using Ape, you generally will work with a project.
To quickly get started using ape, generate a project using the `ape init` command:

```bash
ape init
```

For more in-depth information about smart-contract projects using the Ape framework, see the [projects guide](https://docs.apeworx.io/ape/stable/userguides/projects.html).

### Accounts

In Ape, you will need accounts to make transactions.
You can import or generate accounts using the core `accounts` plugin:

```bash
ape accounts import acc0   # Will prompt for a private key
ape accounts generate acc1
```

List all your accounts with the `list` command.

```bash
ape accounts list
```

Learn more about accounts in Ape by following the [accounts guide](https://docs.apeworx.io/ape/stable/userguides/accounts.html).

### Plugins

Add any plugins you may need, such as `vyper`.

```bash
ape plugins list -a
ape plugins install vyper
ape plugins list -a
```

**NOTE**: If a plugin does not originate from the [ApeWorX GitHub organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing 3rd-party plugins.
Install 3rd party plugins at your own risk.
Additionally, plugins that come bundled with `ape` in the core installation cannot be removed and are part of the `ape` core software.

Learn more about installing plugins from following [this guide](https://docs.apeworx.io/ape/stable/userguides/installing_plugins.html).
Learn more about developing your own plugins from [this guide](https://docs.apeworx.io/ape/stable/userguides/projects.html).

### Compiling

You can compile contracts within the `contracts/` directory of your project.
The `--size` option will display you the size of the contract.

```bash
ape compile --size
```

Learn more about compiling in Ape by following the [compile guide](https://docs.apeworx.io/ape/stable/userguides/compile.html).

### Testing

Use Ape to test your smart-contract projects.
Provide the same arguments to `pytest` as you would to the `ape test` command.

For example:

```bash
ape test -k test_only_one_thing
```

Visit the [testing guide](https://docs.apeworx.io/ape/stable/userguides/testing.html) to learn more about testing using Ape.

### Console

Ape provides an `IPython` interactive console with useful pre-defined locals to interact with your project.
To interact with a deployed contract in a local environment, start by opening the console:

```bash
ape console --network ethereum:mainnet:infura
```

Visit [Ape Console](https://docs.apeworx.io/ape/stable/commands/console.html) to learn how to use Ape Console.

### Scripts

If you want to run specific files in a `scripts/` directory, you can do it using the `ape run` command.

```bash
# This command will run a file named deploy in the scripts/ directory
$ ape run deploy
```

Learn more about scripting using Ape by following the [scripting guide](https://docs.apeworx.io/ape/stable/userguides/scripts.html).

### Logging

To enable debug logging, run your command with the `--verbosity` flag using `DEBUG` as the value:

```bash
ape --verbosity DEBUG run
```

### Networks

You can work with registered networks, providers, and blockchain ecosystems (like Ethereum):

```python
from ape import networks
with networks.ethereum.mainnet.use_provider("infura"):
    ...  # Work with the infura provider here
```

To learn more about networks in Ape, see [this guide](https://docs.apeworx.io/ape/stable/commands/networks.html). 


