Merge pull request #398 from pcattori/types-package

Introduce the _types package

.flake8

@@ -8,6 +8,11 @@ max-complexity = 18
 select = B,C,E,F,I,W,T4,B9
 exclude = build,.venv,*.egg-info
 
+per-file-ignores =
+    tamr_client/__init__.py:E402,F401,I100,I202
+    tamr_client/_types/__init__.py:F401
+    tamr_client/attribute/__init__.py:F401
+
 # flake8-import-order plugin
 import-order-style = google
 application-import-names = tamr_client, tamr_unify_client, tests

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.linting.pylintEnabled": false,
+    "python.linting.flake8Enabled": true,
+    "python.linting.enabled": true,
+    "python.formatting.provider": "black",
+    "editor.formatOnSave": true
+}

docs/beta.md

@@ -5,7 +5,7 @@
 
 ## Reference
 
-  * [Attributes](beta/attributes)
+  * [Attribute](beta/attribute)
   * [Auth](beta/auth)
   * [Dataset](beta/dataset)
   * [Instance](beta/instance)

docs/beta/attribute.md

@@ -0,0 +1,5 @@
+# Attribute
+
+  * [Attribute](/beta/attribute/attribute)
+  * [Attribute Type](/beta/attribute/type)
+  * [SubAttribute](/beta/attribute/sub)

docs/beta/attributes/attribute.rst → docs/beta/attribute/attribute.rst

@@ -13,11 +13,11 @@ Attribute
 Exceptions
 ----------
 
-.. autoclass:: tamr_client.ReservedAttributeName
+.. autoclass:: tamr_client.attribute.AlreadyExists
   :no-inherited-members:
 
-.. autoclass:: tamr_client.AttributeExists
+.. autoclass:: tamr_client.attribute.NotFound
   :no-inherited-members:
 
-.. autoclass:: tamr_client.AttributeNotFound
+.. autoclass:: tamr_client.attribute.ReservedName
   :no-inherited-members:

docs/beta/attributes/subattribute.rst → docs/beta/attribute/sub.rst

@@ -1,6 +1,11 @@
 SubAttribute
 ============
 
+.. NOTE(pcattori):
+   `SubAttribute` has a recursive dependency on `AttributeType`.
+   `sphinx_autodoc_typehint` cannot handle recursive dependencies,
+   so reference docs are written manually
+
 .. class:: tamr_client.SubAttribute(name, type, is_nullable, description=None)
 
   :param name:
@@ -12,5 +17,5 @@ SubAttribute
   :param description:
   :type description: :class:`~typing.Optional` [:class:`str`]
 
-.. autofunction:: tamr_client.subattribute.from_json
-.. autofunction:: tamr_client.subattribute.to_json
+.. autofunction:: tamr_client.attribute.sub.from_json
+.. autofunction:: tamr_client.attribute.sub.to_json

docs/beta/attribute/type.rst

@@ -0,0 +1,40 @@
+AttributeType
+=============
+
+See https://docs.tamr.com/reference#attribute-types
+
+.. autodata:: tamr_client.attribute.type.BOOLEAN
+.. autodata:: tamr_client.attribute.type.DOUBLE
+.. autodata:: tamr_client.attribute.type.INT
+.. autodata:: tamr_client.attribute.type.LONG
+.. autodata:: tamr_client.attribute.type.STRING
+
+.. autodata:: tamr_client.attribute.type.DEFAULT
+.. autodata:: tamr_client.attribute.type.GEOSPATIAL
+
+
+.. NOTE(pcattori):
+   `Array` has a recursive dependency on `AttributeType`.
+   `sphinx_autodoc_typehint` cannot handle recursive dependencies,
+   so reference docs are written manually
+
+.. class:: tamr_client.attribute.type.Array(inner_type)
+
+   :param inner_type:
+   :type inner_type: :class:`~tamr_client.AttributeType`
+
+.. NOTE(pcattori):
+   `Map` has a recursive dependency on `AttributeType`.
+   `sphinx_autodoc_typehint` cannot handle recursive dependencies,
+   so reference docs are written manually
+
+.. class:: tamr_client.attribute.type.Map(inner_type)
+
+   :param inner_type:
+   :type inner_type: :class:`~tamr_client.AttributeType`
+
+
+.. autoclass:: tamr_client.attribute.type.Record
+
+.. autofunction:: tamr_client.attribute.type.from_json
+.. autofunction:: tamr_client.attribute.type.to_json

docs/conf.py

@@ -54,7 +54,7 @@
     "sphinx.ext.viewcode",
     "sphinx.ext.autosectionlabel",
 ]
-autodoc_default_flags = ["inherited-members", "members"]
+autodoc_default_options = {"inherited-members": True, "members": True}
 autodoc_member_order = "bysource"
 autosectionlabel_prefix_document = True
 intersphinx_mapping = {

docs/contributor-guide/style-guide.md

@@ -8,6 +8,7 @@ Code should generally conform to the [PEP8 style guidelines](https://www.python.
 
 ### Structure
 * Classes with methods should be avoided in favor of simple [dataclasses](https://docs.python.org/3/library/dataclasses.html) and functions
+* Types (i.e. `dataclass`es) should be within the `_types` package. Separating types and functions into different packages helps keep type resolution simple so that all of our tools (`mypy`, `sphinx`, `pytest`) run correctly.
 
 ### Google-style docstrings
 All functions and class definitions should use [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) and be annotated with [type hints](https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html#type-annotations).

docs/requirements.txt

@@ -1,4 +1,5 @@
 # TODO(pcattori) Delete this file once RTD fully supports poetry
+pandas==1.0.5
 recommonmark==0.6.0
 sphinx_rtd_theme==0.4.3
 sphinx-autodoc-typehints==1.8.0

noxfile.py

@@ -56,5 +56,5 @@ def docs(session):
         "docs",
         "docs/_build",
         "-W",
-        env={"TAMR_CLIENT_BETA": "1"},
+        env={"TAMR_CLIENT_BETA": "1", "TAMR_CLIENT_DOCS": "1"},
     )

pyproject.toml

@@ -31,7 +31,6 @@ python = "^3.6.1"
 requests = "^2.22"
 simplejson = "^3.16"
 dataclasses = "^0.6.0"
-pandas = "^1.0.3"
 
 [tool.poetry.dev-dependencies]
 Sphinx = "^2.1"
@@ -46,6 +45,7 @@ sphinx-autodoc-typehints = "^1.8"
 pytest = "^5.3.2"
 mypy = "^0.770"
 nox = "^2020.5.24"
+pandas = "^1.0.5"
 
 [build-system]
 requires = ["poetry>=1.0"]