Python doc polish

python-packages/contract_addresses/setup.py

@@ -10,6 +10,7 @@
 from distutils.command.clean import clean
 import distutils.command.build_py
 from setuptools import find_packages, setup
+from setuptools.command.test import test as TestCommand
 
 
 class LintCommand(distutils.command.build_py.build_py):
@@ -30,8 +31,6 @@ def run(self):
             "mypy src setup.py".split(),
             # security issue checker:
             "bandit -r src ./setup.py".split(),
-            # run doctests:
-            "pytest --doctest-modules".split(),
             # general linter:
             "pylint src setup.py".split(),
             # pylint takes relatively long to run, so it runs last, to enable
@@ -103,6 +102,16 @@ def run(self):
         subprocess.check_call("discharge deploy".split())  # nosec
 
 
+class TestCommandExtension(TestCommand):
+    """Run pytest tests."""
+
+    def run_tests(self):
+        """Invoke pytest."""
+        import pytest
+
+        exit(pytest.main(["--doctest-modules"]))
+
+
 with open("README.md", "r") as file_handle:
     README_MD = file_handle.read()
 
@@ -122,6 +131,7 @@ def run(self):
     cmdclass={
         "clean": CleanCommandExtension,
         "lint": LintCommand,
+        "test": TestCommandExtension,
         "test_publish": TestPublishCommand,
         "publish": PublishCommand,
         "publish_docs": PublishDocsCommand,

python-packages/contract_addresses/src/index.rst

@@ -7,15 +7,20 @@ Python zero_ex.contract_addresses
    :maxdepth: 2
    :caption: Contents:
 
-.. autoclass:: zero_ex.contract_addresses.NetworkId
+.. automodule:: zero_ex.contract_addresses
+   :no-members:
 
-   See source for enum members.
+.. autoclass:: zero_ex.contract_addresses.NetworkId
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 .. autoclass:: zero_ex.contract_addresses.ContractAddresses
    :members:
+   :show-inheritance:
 
 .. autodata:: zero_ex.contract_addresses.NETWORK_TO_ADDRESSES
-   :annotation:
+   :annotation: : Dict[NetworkId, ContractAddresses]
 
 Indices and tables
 ==================

python-packages/contract_addresses/src/zero_ex/contract_addresses/__init__.py

@@ -4,26 +4,48 @@
 from typing import Dict, NamedTuple
 
 
-class ContractAddresses(NamedTuple):  # noqa
+class ContractAddresses(NamedTuple):
     """An abstract record listing all the contracts that have addresses."""
 
     erc20_proxy: str
+    """Address of the ERC20Proxy contract."""
+
     erc721_proxy: str
+    """Address of the ERC20Proxy contract."""
+
     zrx_token: str
+    """Address of the ZRX token contract."""
+
     ether_token: str
+    """Address of the WETH token contract."""
+
     exchange: str
+    """Address of the Exchange contract."""
+
     asset_proxy_owner: str
+    """Address of the AssetProxyOwner contract."""
+
     forwarder: str
+    """Address of the Forwarder contract."""
+
     order_validator: str
+    """Address of the OrderValidator contract."""
+
     coordinator_registry: str
+    """Address of the CoordinatorRegistry contract."""
+
     coordinator: str
+    """Address of the Coordinator contract."""
 
 
 class NetworkId(Enum):
     """Network names correlated to their network identification numbers.
 
     >>> NetworkId.MAINNET
     <NetworkId.MAINNET: 1>
+
+    >>> NetworkId.MAINNET.value
+    1
     """
 
     MAINNET = 1
@@ -98,7 +120,7 @@ class NetworkId(Enum):
 """A mapping from instances of NetworkId to instances of ContractAddresses.
 
 Addresses under NetworkId.Ganache are from our Ganache snapshot generated from
-migrations.
+npm package @0x/migrations.
 
 >>> NETWORK_TO_ADDRESSES[NetworkId.MAINNET].exchange
 0x4f833a24e1f95d70f028921e27040ca56e09ab0b

python-packages/contract_artifacts/setup.py

@@ -10,6 +10,7 @@
 from distutils.command.clean import clean
 import distutils.command.build_py
 from setuptools import find_packages, setup
+from setuptools.command.test import test as TestCommand
 
 
 class LintCommand(distutils.command.build_py.build_py):
@@ -110,6 +111,16 @@ def run(self):
         subprocess.check_call("discharge deploy".split())  # nosec
 
 
+class TestCommandExtension(TestCommand):
+    """Run pytest tests."""
+
+    def run_tests(self):
+        """Invoke pytest."""
+        import pytest
+
+        exit(pytest.main(["--doctest-modules"]))
+
+
 with open("README.md", "r") as file_handle:
     README_MD = file_handle.read()
 
@@ -129,6 +140,7 @@ def run(self):
     cmdclass={
         "clean": CleanCommandExtension,
         "lint": LintCommand,
+        "test": TestCommandExtension,
         "test_publish": TestPublishCommand,
         "publish": PublishCommand,
         "publish_docs": PublishDocsCommand,

python-packages/contract_artifacts/src/zero_ex/contract_artifacts/__init__.py

@@ -31,5 +31,21 @@ def contract_name_to_abi(cls, contract_name: str) -> Dict:
 
 
 def abi_by_name(contract_name: str) -> Dict:
-    """Return the ABI for the named contract."""
+    """Return the ABI for the named contract.
+
+    Contract names must correspond to files in the package's `artifacts`:code:
+    directory, without the `.json`:code: suffix.
+
+        >>> from pprint import pprint
+        >>> pprint(abi_by_name("IValidator"))
+        [{'constant': True,
+          'inputs': [{'name': 'hash', 'type': 'bytes32'},
+                     {'name': 'signerAddress', 'type': 'address'},
+                     {'name': 'signature', 'type': 'bytes'}],
+          'name': 'isValidSignature',
+          'outputs': [{'name': 'isValid', 'type': 'bool'}],
+          'payable': False,
+          'stateMutability': 'view',
+          'type': 'function'}]
+    """
     return _ArtifactCache.contract_name_to_abi(contract_name)

python-packages/contract_wrappers/.pylintrc

@@ -1,4 +1,6 @@
 [MESSAGES CONTROL]
-disable=C0330,line-too-long,fixme,too-few-public-methods,too-many-ancestors,too-many-arguments
+disable=C0330,line-too-long,fixme,too-few-public-methods,too-many-ancestors
 # C0330 is "bad hanging indent". we use indents per `black`.
-min-similarity-lines=10
+
+[SIMILARITIES]
+min-similarity-lines=6

python-packages/contract_wrappers/src/index.rst

@@ -1,33 +1,32 @@
 Python zero_ex.contract_wrappers
-================================================
+================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
 .. automodule:: zero_ex.contract_wrappers
    :members:
-   :inherited-members:
 
 
 zero_ex.contract_wrappers.Exchange
-----------------------------------
+==================================
 
 .. autoclass:: zero_ex.contract_wrappers.Exchange
    :members:
-   :inherited-members:
+   :special-members:
 
 
 zero_ex.contract_wrappers.ERC20Token
--------------------------------------
+====================================
 
 .. autoclass:: zero_ex.contract_wrappers.ERC20Token
    :members:
-   :inherited-members:
+   :special-members:
 
 
 zero_ex.contract_wrappers.TxParams
-----------------------------------
+==================================
 
 .. autoclass:: zero_ex.contract_wrappers.TxParams
    :members: