Python doc polish (#1757)

* Exercise doctests as a test not as a linter

* Add a contract artifact doctest, and exercise it

* Clean up linter issues

* Change asset data decoding output type

Previously, it was a TypedDict, but that was causing problems.  Sphinx
seems to be broken, such that none of the fields of the class were being
rendered into the doc.

Thinking on it further, I decided that a NamedTuple makes more sense
here anyways, since tuples are immutable and this output value isn't
something someone should ever build or modify.  And, NamedTuple is
getting its fields properly rendered by Sphinx.

* Add type annotations to JSON schemas docs

* Add doc publish metadata file for middlewares pkg

* Improve documentation

Note that none of the changes to .py files impact functionality in any
way, because the changes are restricted to "docstrings", which to the
Python interpreter are simply no-op statements.

However, one caveat to that is that much of these docstring changes DO
affect the functionality of automated test runs, because all of the code
examples (blocks beginning with `>>> `) are "doctests", which are
exercised via the test framework.

The index.rst files are the top-level templates for generating the
documentation, and the "automodule"/"autoclass"/etc statements pull in
the docstrings from the source code.

* correct package name in doc URL

* Move sra_client module into zero_ex namespace

* Add functions to encode asset data to bytes

* Fix: SRA client was deserializing orders weirdly

The generated code was transforming the order structure, from the camel
case field name format in the spec, into the snake case field name
format expected by Python convention.  With this problem in place, the
only way to take an order from a relayer and send it to a contract (for
fill, cancel, etc) was to manually transform the field names, one by
one, into a new structure.

* Fix problem with Web3/JSON order conversion utils

* doctest: maker, trade ZRX for WETH, not vice versa

* Remove redundant test

* Construct order in native Python, not JSON

Then convert it to JSON before sending it to the relayer.

* doctest: simplify asset units

* Add doctests for filling and cancelling

* Minor doctetst copy edits; whitespace

* Rename function, and add optional parameter

* Tweak docstrings on JSON conversion functions.

* Demo asset data decoding to view asset pairs

* Demo selecting an order from the order book

And have taker take it.

* Rename variable

* Abstract ganache from examples

Doing that exposed excessive use of the verbose
NETWORK_TO_ADDRESSES[NetworkId.Ganache] construct, so simplified that,
which ripped into eliminating other temporary variables that had been
used to hold specific contract addresses.

Also cleaned up some misplaced import statements.

* Add missing SRA client doc publication metadata

* Ran prettier on new SRA client doc pub metadata

* Remove local env customizations in doc metadata

* Eliminate temporary variable

* Rename variable

* Show `pip install` in every package's doc

* Doc NetorkID & pagination params as int, not float

* Clean up unmatched parenthesis in docs

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

@@ -1,29 +1,60 @@
-"""Addresses at which the 0x smart contracts have been deployed."""
+"""Addresses at which the 0x smart contracts have been deployed.
+
+Setup
+-----
+
+Install the package with pip::
+
+    pip install 0x-contract-addresses
+
+"""
 
 from enum import Enum
 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 +129,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

@@ -1,4 +1,12 @@
-"""0x smart contract compilation artifacts."""
+"""0x smart contract compilation artifacts.
+
+Setup
+-----
+
+Install the package with pip::
+
+    pip install 0x-contract-artifacts
+"""
 
 import json
 from typing import Dict
@@ -31,5 +39,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: