Update documentation

latest/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: a6979b6fe4120fff952b9ba8b89c1f7e
+config: 7b0b3357b99c4528766b97b0574e191e
 tags: 645f666f9bcd5a90fca523b33c5a78b7

latest/_sources/userguides/dependencies.md.txt

@@ -59,9 +59,20 @@ Bypass the original failing attempt by including a `v` in your dependency config
 
 **By knowing if the release is from the version API or only available via tag, and whether the version is v-prefixed or not, you save Ape some time and complexity when installing dependencies.**
 
-### Python
+### PyPI
 
-You can use dependencies to PyPI by using the `python:` keyed dependency type.
+You can use dependencies from [PyPI](https://pypi.org/) by using the `pypi:` key.
+
+```yaml
+dependencies:
+   - pypi: snekmate
+     config_override:
+       contracts_folder: src
+```
+
+When using the `pypi:` key, dependencies are downloaded and extracted from PyPI using an HTTP requests library.
+
+You can also specify the `python:` key for already-installed dependencies:
 
 ```yaml
 dependencies:
@@ -70,6 +81,14 @@ dependencies:
        contracts_folder: .
 ```
 
+Using `python:` requires the package to be installed in your `sys.path` (site-packages) folder, generally via `pip` or some other tool.
+The `contracts_folder` override, in this case, is often needed because the site-package does not have the root source-folder included.
+Additionally, `python:` specified dependencies may also be lacking project-configuration files, such as the `ape-config.yaml`.
+Compilers such as `vyper` encourage users to use `pip` to publish and install smart-contract dependencies (other vyper files), but some features in Ape may be limited if the dependency is not also specified in your config somewhere.
+
+If wanting to use a dependency from `PyPI`, we recommend using the `pypi:` key instead of the `python:` key.
+However, the `python:` key works great if you already used `pip` to install the dependency, especially if the dependency is not available on `PyPI`.
+
 ### Local
 
 You can use already-downloaded projects as dependencies by referencing them as local dependencies.

latest/commands/networks.html

@@ -297,7 +297,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Permalink to this hea
 <dd><p>Filter the results by network</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>holesky-fork | local | mainnet | mainnet-fork | sepolia-fork | sepolia | holesky</p>
+<dd class="field-odd"><p>local | sepolia-fork | holesky | mainnet-fork | sepolia | holesky-fork | mainnet</p>
 </dd>
 </dl>
 </dd></dl>
@@ -308,7 +308,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Permalink to this hea
 <dd><p>Filter the results by provider</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>test | node</p>
+<dd class="field-odd"><p>node | test</p>
 </dd>
 </dl>
 </dd></dl>

latest/genindex.html

@@ -2633,6 +2633,8 @@ <h2 id="E">E</h2>
       <li><a href="methoddocs/plugins.html#ape.plugins.network.ExplorerPlugin.explorers">explorers() (ape.plugins.network.ExplorerPlugin method)</a>
 </li>
       <li><a href="methoddocs/utils.html#ape.utils.ExtraAttributesMixin">ExtraAttributesMixin (class in ape.utils)</a>
+</li>
+      <li><a href="methoddocs/utils.html#ape.utils.extract_archive">extract_archive() (in module ape.utils)</a>
 </li>
       <li><a href="methoddocs/api.html#ape.api.projects.ApeProject.extract_config">extract_config() (ape.api.projects.ApeProject method)</a>
 
@@ -3986,6 +3988,8 @@ <h2 id="P">P</h2>
         <li><a href="methoddocs/api.html#ape.api.networks.NetworkAPI.publish_contract">(ape.api.networks.NetworkAPI method)</a>
 </li>
       </ul></li>
+      <li><a href="methoddocs/ape_pm.html#ape_pm.PythonDependency.pypi">pypi (ape_pm.PythonDependency attribute)</a>
+</li>
       <li>
     PYTEST_ARGS
 

latest/methoddocs/ape_pm.html

@@ -271,6 +271,7 @@
 <li class="toctree-l2"><a class="reference internal" href="#ape_pm.PythonDependency"><code class="docutils literal notranslate"><span class="pre">PythonDependency</span></code></a><ul>
 <li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.fetch"><code class="docutils literal notranslate"><span class="pre">PythonDependency.fetch()</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.package_id"><code class="docutils literal notranslate"><span class="pre">PythonDependency.package_id</span></code></a></li>
+<li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.pypi"><code class="docutils literal notranslate"><span class="pre">PythonDependency.pypi</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.python"><code class="docutils literal notranslate"><span class="pre">PythonDependency.python</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.uri"><code class="docutils literal notranslate"><span class="pre">PythonDependency.uri</span></code></a></li>
 <li class="toctree-l3"><a class="reference internal" href="#ape_pm.PythonDependency.version"><code class="docutils literal notranslate"><span class="pre">PythonDependency.version</span></code></a></li>
@@ -662,8 +663,8 @@
 
 <dl class="py class">
 <dt class="sig sig-object py" id="ape_pm.PythonDependency">
-<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">ape_pm.</span></span><span class="sig-name descname"><span class="pre">PythonDependency</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config_override</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">python</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">version</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#ape_pm.PythonDependency" title="Permalink to this definition"></a></dt>
-<dd><p>A dependency installed from Python, such as files published to PyPI.</p>
+<em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">ape_pm.</span></span><span class="sig-name descname"><span class="pre">PythonDependency</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">config_override</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">dict</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">python</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pypi</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">version</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></span><span class="w"> </span><span class="o"><span class="pre">=</span></span><span class="w"> </span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#ape_pm.PythonDependency" title="Permalink to this definition"></a></dt>
+<dd><p>A dependency installed from Python tooling, such as <cite>pip</cite>.</p>
 <dl class="py method">
 <dt class="sig sig-object py" id="ape_pm.PythonDependency.fetch">
 <span class="sig-name descname"><span class="pre">fetch</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">destination</span></span><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="n"><span class="pre">Path</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#ape_pm.PythonDependency.fetch" title="Permalink to this definition"></a></dt>
@@ -684,10 +685,20 @@
 Example: <code class="docutils literal notranslate"><span class="pre">OpenZeppelin/openzepplin-contracts</span></code>.</p>
 </dd></dl>
 
+<dl class="py attribute">
+<dt class="sig sig-object py" id="ape_pm.PythonDependency.pypi">
+<span class="sig-name descname"><span class="pre">pypi</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#ape_pm.PythonDependency.pypi" title="Permalink to this definition"></a></dt>
+<dd><p>The <code class="docutils literal notranslate"><span class="pre">pypi</span></code> reference, such as <code class="docutils literal notranslate"><span class="pre">&quot;snekmate&quot;</span></code>. Cannot use with
+<code class="docutils literal notranslate"><span class="pre">python:</span></code>. When set, downloads the dependency from <code class="docutils literal notranslate"><span class="pre">pypi</span></code>
+using HTTP directly (not <code class="docutils literal notranslate"><span class="pre">pip</span></code>).</p>
+</dd></dl>
+
 <dl class="py attribute">
 <dt class="sig sig-object py" id="ape_pm.PythonDependency.python">
-<span class="sig-name descname"><span class="pre">python</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span></em><a class="headerlink" href="#ape_pm.PythonDependency.python" title="Permalink to this definition"></a></dt>
-<dd><p>The Python site-package name.</p>
+<span class="sig-name descname"><span class="pre">python</span></span><em class="property"><span class="p"><span class="pre">:</span></span><span class="w"> </span><span class="pre">str</span><span class="w"> </span><span class="p"><span class="pre">|</span></span><span class="w"> </span><span class="pre">None</span></em><a class="headerlink" href="#ape_pm.PythonDependency.python" title="Permalink to this definition"></a></dt>
+<dd><p>The Python site-package name, such as <code class="docutils literal notranslate"><span class="pre">&quot;snekmate&quot;</span></code>. Cannot use
+with <code class="docutils literal notranslate"><span class="pre">pypi:</span></code>. Requires the dependency to have been installed
+either via <code class="docutils literal notranslate"><span class="pre">pip</span></code> or something alike.</p>
 </dd></dl>
 
 <dl class="py property">