feat: project stub for python order utilities

An empty project, with respect to functionality, but one configured with
a test framework, linters, CI integration, etc.

https://app.asana.com/0/836857747873847/839549782781239/f

15 files changed, 364 insertions, 1 deletions

diff --git a/.circleci/config.yml b/.circleci/config.yml
index 3c87e1ff2..876b861d3 100644
--- a/.circleci/config.yml
+++ b/.circleci/config.yml
@@ -162,6 +162,90 @@ jobs:
           key: coverage-web3-wrapper-{{ .Environment.CIRCLE_SHA1 }}
           paths:
             - ~/repo/packages/web3-wrapper/coverage/lcov.info
+  test-python:
+    working_directory: ~/repo
+    docker:
+      - image: circleci/python
+    steps:
+      - checkout
+      - run: sudo chown -R circleci:circleci /usr/local/bin
+      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.7/site-packages
+      - restore_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+      - run:
+          command: |
+            cd python-packages/order_utils
+            python -m ensurepip
+            python -m pip install -e .[dev]
+      - save_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+          paths:
+            - "/usr/local/bin"
+            - "/usr/local/lib/python3.7/site-packages"
+            - ".eggs"
+            - ".mypy_cache"
+            - ".pytest_cache"
+            - ".tox"
+      - run:
+          command: |
+            cd python-packages/order_utils
+            coverage run setup.py test
+      - save_cache:
+          key: coverage-python-order-utils-{{ .Environment.CIRCLE_SHA1 }}
+          paths:
+            - ~/repo/python-packages/order_utils/.coverage
+  test-rest-python:
+    working_directory: ~/repo
+    docker:
+      - image: circleci/python
+    steps:
+      - checkout
+      - run: sudo chown -R circleci:circleci /usr/local/bin
+      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.7/site-packages
+      - restore_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+      - run:
+          command: |
+            cd python-packages/order_utils
+            python -m ensurepip
+            python -m pip install -e .[dev]
+      - save_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+          paths:
+            - "/usr/local/bin"
+            - "/usr/local/lib/python3.7/site-packages"
+            - ".eggs"
+            - ".mypy_cache"
+            - ".pytest_cache"
+            - ".tox"
+      - run:
+          command: |
+            cd python-packages/order_utils
+            tox
+  static-tests-python:
+    working_directory: ~/repo
+    docker:
+      - image: circleci/python
+    steps:
+      - checkout
+      - run: sudo chown -R circleci:circleci /usr/local/bin
+      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.7/site-packages
+      - restore_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+      - run:
+          command: |
+            cd python-packages/order_utils
+            python -m ensurepip
+            python -m pip install -e .[dev]
+      - save_cache:
+          key: deps9-{{ .Branch }}-{{ .Environment.CIRCLE_SHA1 }}
+          paths:
+            - "/usr/local/bin"
+            - "/usr/local/lib/python3.7/site-packages"
+      - run:
+          command: |
+            cd python-packages/order_utils
+            python setup.py lint
   static-tests:
     working_directory: ~/repo
     docker:
@@ -233,6 +317,9 @@ jobs:
       - restore_cache:
           keys:
             - coverage-contracts-{{ .Environment.CIRCLE_SHA1 }}
+      - restore_cache:
+          keys:
+            - coverage-python-order-utils-{{ .Environment.CIRCLE_SHA1 }}
       - run: yarn report_coverage
 workflows:
   version: 2
@@ -263,3 +350,8 @@ workflows:
       - submit-coverage:
           requires:
             - test-rest
+            - test-python
+      - test-python
+      - static-tests-python
+      # skip python tox run for now, as we don't yet have multiple test environments to support.
+      #- test-rest-python
diff --git a/.gitignore b/.gitignore
index 1ae1b412d..6143dedb0 100644
--- a/.gitignore
+++ b/.gitignore
@@ -109,3 +109,12 @@ packages/sol-compiler/solc_bin/
 
 # Monorepo scripts
 packages/*/scripts/
+
+# python stuff
+.eggs
+.mypy_cache
+.tox
+python-packages/*/build
+__pycache__
+python-packages/*/src/*.egg-info
+python-packages/*/.coverage
diff --git a/package.json b/package.json
index 920afaf29..e6ae0ebde 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
         "ganache": "ganache-cli -p 8545 --networkId 50 -m \"${npm_package_config_mnemonic}\"",
         "prettier": "prettier --write '**/*.{ts,tsx,json,md}' --config .prettierrc",
         "prettier:ci": "prettier --list-different '**/*.{ts,tsx,json,md}' --config .prettierrc",
-        "report_coverage": "lcov-result-merger 'packages/*/coverage/lcov.info' | coveralls",
+        "report_coverage": "lcov-result-merger './{packages/*/coverage/lcov.info,python-packages/*/.coverage}' | coveralls",
         "test:installation": "node ./packages/monorepo-scripts/lib/test_installation.js",
         "test:installation:local": "IS_LOCAL_PUBLISH=true node ./packages/monorepo-scripts/lib/test_installation.js",
         "test:publish:circleci:comment": "HACK(albrow) We need an automated way to login to npm and echo+sleep piped to stdin was the only way I could find to do it.",
diff --git a/python-packages/order_utils/package.json b/python-packages/order_utils/package.json
new file mode 100644
index 000000000..125ca71e0
--- /dev/null
+++ b/python-packages/order_utils/package.json
@@ -0,0 +1,17 @@
+{
+    "comment": "this file exists as an entry point to building this project, specifically for humans that are familiar with yarn and already have it installed.  this file is not used in any automation or CI.",
+    "scripts": {
+        "install": "pip install -e .[dev]",
+        "build": "python setup.py build && yarn build:docs",
+        "build:docs": "python setup.py build_sphinx && sphinx-apidoc -o build/docs/api src",
+        "test:comment": "test in local environment. to test in all environments, use test:all",
+        "test": "python setup.py test",
+        "test:all": "tox",
+        "test:coverage": "coverage run setup.py test && coveralls",
+        "lint": "python setup.py lint",
+        "clean": "python setup.py clean"
+    },
+    "dependencies:comment": "managed in setup.py",
+    "devDependencies:comment": "managed in setup.py",
+    "license": "Apache-2.0"
+}
diff --git a/python-packages/order_utils/setup.py b/python-packages/order_utils/setup.py
new file mode 100644
index 000000000..4d5d69de1
--- /dev/null
+++ b/python-packages/order_utils/setup.py
@@ -0,0 +1,127 @@
+"""setuptools module for order_utils package."""
+
+import subprocess  # nosec
+from shutil import rmtree
+from os import path, remove, walk
+
+from distutils.command.clean import clean  # type: ignore
+from setuptools import setup  # type: ignore
+import setuptools.command.build_py  # type: ignore
+from setuptools.command.test import test as TestCommand  # type: ignore
+
+
+class TestCommandExtension(TestCommand):
+    """Run pytest tests."""
+
+    def run_tests(self):
+        """Invoke pytest."""
+        import pytest  # type: ignore
+
+        pytest.main()
+
+
+# pylint: disable=too-many-ancestors
+class LintCommand(setuptools.command.build_py.build_py):
+    """Custom setuptools command class for running linters."""
+
+    def run(self):
+        """Run linter shell commands."""
+        lint_commands = [
+            # formatter:
+            "black --line-length 79 --check --diff src test setup.py".split(),
+            # style guide checker (formerly pep8):
+            "pycodestyle src test setup.py".split(),
+            # docstring style checker:
+            "pydocstyle src test setup.py".split(),
+            # static type checker:
+            "mypy src setup.py".split(),
+            # security issue checker:
+            "bandit -r src ./setup.py".split(),
+            # general linter:
+            "pylint src test setup.py".split(),
+            # pylint takes relatively long to run, so it runs last, to enable
+            # fast failures.
+        ]
+        for lint_command in lint_commands:
+            print(
+                "Running lint command `", " ".join(lint_command).strip(), "`"
+            )
+            subprocess.check_call(lint_command)  # nosec
+
+
+class CleanCommandExtension(clean):
+    """Custom command to do custom cleanup."""
+
+    def run(self):
+        """Run the regular clean, followed by our custom commands."""
+        super().run()
+        rmtree("build", ignore_errors=True)
+        rmtree(".mypy_cache", ignore_errors=True)
+        rmtree(".tox", ignore_errors=True)
+        rmtree(".pytest_cache", ignore_errors=True)
+        rmtree("src/order_utils.egg-info", ignore_errors=True)
+        # delete all .pyc files
+        for root, _, files in walk("."):
+            for file in files:
+                if file[-4:] == ".pyc":
+                    remove(path.join(root, file))
+
+
+setup(
+    name="order_utils",
+    version="1.0.0",
+    description="Order utilities for 0x applications",
+    author="F. Eugene Aumson",
+    cmdclass={
+        "clean": CleanCommandExtension,
+        "lint": LintCommand,
+        "test": TestCommandExtension,
+    },
+    include_package_data=True,
+    install_requires=["web3"],
+    extras_require={
+        "dev": [
+            "bandit",
+            "black",
+            "coverage",
+            "coveralls",
+            "mypy",
+            "pycodestyle",
+            "pydocstyle",
+            "pylint",
+            "pytest",
+            "sphinx",
+            "tox",
+        ]
+    },
+    python_requires=">=3.6, <4",
+    package_data={"zero_ex.order_utils": ["py.typed"]},
+    package_dir={"": "src"},
+    license="Apache 2.0",
+    keywords=(
+        "ethereum cryptocurrency 0x decentralized blockchain dex exchange"
+    ),
+    packages=["zero_ex.order_utils"],
+    classifiers=[
+        "Development Status :: 1 - Planning",
+        "Intended Audience :: Developers",
+        "Intended Audience :: Financial and Insurance Industry",
+        "License :: OSI Approved :: Apache Software License",
+        "Natural Language :: English",
+        "Operating System :: OS Independent",
+        "Programming Language :: Python",
+        "Programming Language :: Python :: 3 :: Only",
+        "Programming Language :: Python :: 3.6",
+        "Programming Language :: Python :: 3.7",
+        "Topic :: Office/Business :: Financial",
+        "Topic :: Software Development :: Libraries",
+        "Topic :: Utilities",
+    ],
+    zip_safe=False,
+    command_options={
+        "build_sphinx": {
+            "source_dir": ("setup.py", "src"),
+            "build_dir": ("setup.py", "build/docs"),
+        }
+    },
+)
diff --git a/python-packages/order_utils/src/conf.py b/python-packages/order_utils/src/conf.py
new file mode 100644
index 000000000..f3f15967c
--- /dev/null
+++ b/python-packages/order_utils/src/conf.py
@@ -0,0 +1,50 @@
+"""Configuration file for the Sphinx documentation builder."""
+
+# Reference: http://www.sphinx-doc.org/en/master/config
+
+# pylint: disable=invalid-name
+# because these variables are not named in upper case, as globals should be.
+
+project = "order_utils.py"
+# pylint: disable=redefined-builtin
+copyright = "2018, ZeroEx, Intl."
+author = "F. Eugene Aumson"
+version = ""  # The short X.Y version
+release = ""  # The full version, including alpha/beta/rc tags
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
+]
+
+templates_path = ["doc_templates"]
+
+source_suffix = ".rst"
+# eg: source_suffix = [".rst", ".md"]
+
+master_doc = "index"  # The master toctree document.
+
+language = None
+
+exclude_patterns = []  # type: ignore
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = None
+
+html_theme = "alabaster"
+
+html_static_path = ["doc_static"]
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = "order_utilspydoc"
+
+# -- Extension configuration:
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {"https://docs.python.org/": None}
diff --git a/python-packages/order_utils/src/index.rst b/python-packages/order_utils/src/index.rst
new file mode 100644
index 000000000..cbc4c8409
--- /dev/null
+++ b/python-packages/order_utils/src/index.rst
@@ -0,0 +1,22 @@
+.. source for the sphinx-generated build/docs/web/index.html
+
+order_utils.py
+==============
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+.. automodule:: zero_ex.order_utils
+   :members:
+
+.. automodule:: zero_ex.order_utils.signature_utils
+   :members:
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
diff --git a/python-packages/order_utils/src/zero_ex/__init__.py b/python-packages/order_utils/src/zero_ex/__init__.py
new file mode 100644
index 000000000..c3ed1562a
--- /dev/null
+++ b/python-packages/order_utils/src/zero_ex/__init__.py
@@ -0,0 +1 @@
+"""0x Python API."""
diff --git a/python-packages/order_utils/src/zero_ex/order_utils/__init__.py b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py
new file mode 100644
index 000000000..f014af0f6
--- /dev/null
+++ b/python-packages/order_utils/src/zero_ex/order_utils/__init__.py
@@ -0,0 +1 @@
+"""Order utilities for 0x applications."""
diff --git a/python-packages/order_utils/src/zero_ex/order_utils/signature_utils.py b/python-packages/order_utils/src/zero_ex/order_utils/signature_utils.py
new file mode 100644
index 000000000..7f4697106
--- /dev/null
+++ b/python-packages/order_utils/src/zero_ex/order_utils/signature_utils.py
@@ -0,0 +1,13 @@
+"""Signature utilities."""
+
+
+def ec_sign_order_hash():
+    """Signs an orderHash.
+
+    Returns its elliptic curve signature and signature type.  This method
+    currently supports TestRPC, Geth, and Parity above and below v1.6.6.
+
+    >>> ec_sign_order_hash()
+    'stub return value'
+    """
+    return "stub return value"
diff --git a/python-packages/order_utils/src/zero_ex/py.typed b/python-packages/order_utils/src/zero_ex/py.typed
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/python-packages/order_utils/src/zero_ex/py.typed
diff --git a/python-packages/order_utils/test/__init__.py b/python-packages/order_utils/test/__init__.py
new file mode 100644
index 000000000..ec5b114aa
--- /dev/null
+++ b/python-packages/order_utils/test/__init__.py
@@ -0,0 +1 @@
+"""Tests of zero_x.order_utils."""
diff --git a/python-packages/order_utils/test/test_doctest.py b/python-packages/order_utils/test/test_doctest.py
new file mode 100644
index 000000000..a0e61f84a
--- /dev/null
+++ b/python-packages/order_utils/test/test_doctest.py
@@ -0,0 +1,10 @@
+"""Exercise doctests for order_utils module."""
+
+from doctest import testmod
+from zero_ex.order_utils import signature_utils
+
+
+def test_doctest():
+    """Invoke doctest on the module."""
+    (failure_count, _) = testmod(signature_utils)
+    assert failure_count == 0
diff --git a/python-packages/order_utils/test/test_signature_utils.py b/python-packages/order_utils/test/test_signature_utils.py
new file mode 100644
index 000000000..7e830f9f8
--- /dev/null
+++ b/python-packages/order_utils/test/test_signature_utils.py
@@ -0,0 +1,8 @@
+"""Tests of 0x.order_utils.signature_utils.*."""
+
+from zero_ex.order_utils.signature_utils import ec_sign_order_hash
+
+
+def test_ec_sign_order_hash():
+    """Test the signing of order hashes."""
+    assert ec_sign_order_hash() == "stub return value"
diff --git a/python-packages/order_utils/tox.ini b/python-packages/order_utils/tox.ini
new file mode 100644
index 000000000..1cce32b5f
--- /dev/null
+++ b/python-packages/order_utils/tox.ini
@@ -0,0 +1,12 @@
+# tox (https://tox.readthedocs.io/) is a tool for running tests
+# in multiple virtualenvs. This configuration file will run the
+# test suite on all supported python versions. To use it, "pip install tox"
+# and then run "tox" from this directory.
+
+[tox]
+envlist = py37
+
+[testenv]
+commands =
+    pip install -e .[dev]
+    python setup.py test