Merge pull request #338 from pcattori/instance-and-dataset

Instance and dataset

CHANGELOG.md

@@ -2,26 +2,34 @@
   **NEW FEATURES**
   - BETA: New attributes package!
     - `tc.attribute` module
-      - `tc.Attribute` class
+      - `tc.Attribute` type
       - functions: `from_resource_id`, `to_json`, `create`, `update`, `delete`
     - `tc.attribute_type` module
       - `tc.AttributeType` for type annotations
       - Primitive Types: `BOOLEAN`, `DOUBLE`, `INT`, `LONG`, `STRING`
       - Complex Types: `Array`, `Map`, `Record`
-      - Type aliases: `DEFAULT`, `GEOSPATIAL`
       - functions: `from_json`, `to_json`
     - `tc.subattribute` module
-      - `tc.SubAttribute` class
+      - `tc.SubAttribute` type
       - functions: `from_json`, `to_json`
+    - `tc.attributes.type_alias` module
+      - `tc.attributes.type_alias.DEFAULT` type
+      - `tc.attributes.type_alias.GEOSPATIAL` type
   - BETA: New datasets package!
     - `tc.dataset` module
-      - functions: `_attributes`
+      - `tc.Dataset` type
+      - functions: `from_resource_id`, `attributes`
+  - BETA: New `tc.instance` module!
+    - `tc.Instance` type
+    - functions: `tc.instance.from_auth`
   - BETA: New supporting modules!
     - `tc.auth` module
-      - `tc.UsernamePasswordAuth` class
-    - `tc.session` function
+      - `tc.UsernamePasswordAuth` type
+    - `tc.session` module
+      - `tc.Session` type
+      - functions: `tc.session.from_auth`
     - `tc.url` module
-      - `tc.URL` class
+      - `tc.URL` type
 
   **BUG FIXES**
   - Links from our docs to the `requests` docs were outdated. Links have been updated to point to the new `requests` docs URL.

docs/beta.md

@@ -0,0 +1,12 @@
+# BETA
+
+  **WARNING**: Do not rely on BETA features in production workflows.
+  Support from Tamr may be limited.
+
+## Reference
+
+  * [Attributes](beta/attributes)
+  * [Auth](beta/auth)
+  * [Dataset](beta/datasets)
+  * [Instance](beta/instance)
+  * [Session](beta/session)

docs/beta/attributes.md

@@ -0,0 +1,5 @@
+# Attributes
+
+  * [Attribute](/beta/attributes/attribute)
+  * [Attribute Type](/beta/attributes/attribute_type)
+  * [SubAttribute](/beta/attributes/subattribute)

docs/beta/attributes/attribute.rst

@@ -0,0 +1,22 @@
+Attribute
+=========
+
+.. autoclass:: tamr_client.Attribute
+
+.. autofunction:: tamr_client.attribute.from_resource_id
+.. autofunction:: tamr_client.attribute.to_json
+.. autofunction:: tamr_client.attribute.create
+.. autofunction:: tamr_client.attribute.update
+.. autofunction:: tamr_client.attribute.delete
+
+Exceptions
+----------
+
+.. autoclass:: tamr_client.ReservedAttributeName
+  :no-inherited-members:
+
+.. autoclass:: tamr_client.AttributeExists
+  :no-inherited-members:
+
+.. autoclass:: tamr_client.AttributeNotFound
+  :no-inherited-members:

docs/beta/attributes/attribute_type.rst

@@ -0,0 +1,38 @@
+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
+
+.. NOTE(pcattori): Manually write docs for complex attribute types
+   Complex types recursively reference other attribute types or subattributes
+   sphinx_autodoc_typehints cannot properly parse types recursively
+
+.. class:: tamr_client.attribute_type.Array(inner_type)
+
+   :param inner_type:
+   :type inner_type: :class:`~tamr_client.AttributeType`
+
+.. class:: tamr_client.attribute_type.Map(inner_type)
+
+   :param inner_type:
+   :type inner_type: :class:`~tamr_client.AttributeType`
+
+.. class:: tamr_client.attribute_type.Record(attributes)
+
+  :param attributes:
+  :type attributes: :class:`~typing.Tuple` [:class:`~tamr_client.SubAttribute`]
+
+.. autofunction:: tamr_client.attribute_type.from_json
+.. autofunction:: tamr_client.attribute_type.to_json
+
+Type aliases
+------------
+
+.. autodata:: tamr_client.attributes.type_alias.DEFAULT
+.. autodata:: tamr_client.attributes.type_alias.GEOSPATIAL

docs/beta/attributes/subattribute.rst

@@ -0,0 +1,16 @@
+SubAttribute
+============
+
+.. class:: tamr_client.SubAttribute(name, type, is_nullable, description=None)
+
+  :param name:
+  :type name: :class:`str`
+  :param type:
+  :type type: :class:`~tamr_client.AttributeType`
+  :param is_nullable:
+  :type is_nullable: :class:`bool`
+  :param description:
+  :type description: :class:`~typing.Optional` [:class:`str`]
+
+.. autofunction:: tamr_client.subattribute.from_json
+.. autofunction:: tamr_client.subattribute.to_json

docs/beta/auth.rst

@@ -0,0 +1,4 @@
+Auth
+====
+
+.. autoclass:: tamr_client.UsernamePasswordAuth

docs/beta/datasets.md

@@ -0,0 +1,3 @@
+# Datasets
+
+  * [Dataset](/beta/datasets/dataset)

docs/beta/datasets/dataset.rst

@@ -0,0 +1,13 @@
+Dataset
+=======
+
+.. autoclass:: tamr_client.Dataset
+
+.. autofunction:: tamr_client.dataset.from_resource_id
+.. autofunction:: tamr_client.dataset.attributes
+
+Exceptions
+----------
+
+.. autoclass:: tamr_client.DatasetNotFound
+  :no-inherited-members:

docs/beta/instance.rst

@@ -0,0 +1,6 @@
+Instance
+========
+
+.. autoclass:: tamr_client.Instance
+
+.. autofunction:: tamr_client.instance.origin

docs/beta/session.rst

@@ -0,0 +1,8 @@
+Session
+=======
+
+The :class:`~tamr_client.Session` type is an alias for :class:`requests.Session`.
+
+For more information, see the official :class:`requests.Session` docs.
+
+.. autofunction:: tamr_client.session.from_auth

docs/index.md

@@ -44,3 +44,7 @@ assert op.succeeded()
 ## Reference
 
   * [Reference](reference)
+
+## BETA
+
+  * [BETA](beta)

docs/reference.md

@@ -9,11 +9,3 @@
   * [Mastering](reference/mastering)
   * [Operations](reference/operation)
   * [Projects](reference/project)
-
-## BETA
-
-  **WARNING**: Do not rely on BETA features in production workflows.
-  Tamr will not offer support for BETA features.
-
-  * [Attributes](reference/beta/attributes)
-  * [Datasets](reference/beta/datasets)

tamr_client/__init__.py

@@ -1,18 +1,53 @@
 # flake8: noqa
 
+############
+# BETA start
+############
+
+import os
+import sys
+
+beta_flag = "TAMR_CLIENT_BETA"
+beta_enabled = "1"
+beta = os.environ.get(beta_flag)
+
+if beta != beta_enabled:
+    msg = (
+        f"ERROR: 'tamr_client' package is in BETA, but you do not have the '{beta_flag}' environment variable set to '1'."
+        "\n\nHINT: Use 'tamr_unify_client' package instead for non-BETA features"
+        f"\nHINT: Set environment variable '{beta_flag}=1' to opt-in to BETA features."
+        "\n\nWARNING: Do not rely on BETA features in production workflows."
+        " Support from Tamr may be limited."
+    )
+    print(msg)
+    sys.exit(1)
+
+##########
+# BETA end
+##########
+
 import logging
 
 # utilities
+import tamr_client.response as response
+
+# instance
+from tamr_client.instance import Instance
+import tamr_client.instance as instance
+
+# url
 from tamr_client.url import URL
 import tamr_client.url as url
 
-import tamr_client.response as response
+# auth
 from tamr_client.auth import UsernamePasswordAuth
+
+# session
 from tamr_client.session import Session
 import tamr_client.session as session
 
 # datasets
-from tamr_client.datasets.dataset import Dataset
+from tamr_client.datasets.dataset import Dataset, DatasetNotFound
 import tamr_client.datasets.dataset as dataset
 
 # attributes
@@ -22,12 +57,14 @@
 from tamr_client.attributes.attribute_type import AttributeType
 import tamr_client.attributes.attribute_type as attribute_type
 
-import tamr_client.attributes.type_alias as attribute_type_alias
+import tamr_client.attributes.type_alias
 
-from tamr_client.attributes.attribute import Attribute
-from tamr_client.attributes.attribute import ReservedAttributeName
-from tamr_client.attributes.attribute import AttributeExists
-from tamr_client.attributes.attribute import AttributeNotFound
+from tamr_client.attributes.attribute import (
+    Attribute,
+    ReservedAttributeName,
+    AttributeExists,
+    AttributeNotFound,
+)
 import tamr_client.attributes.attribute as attribute
 
 # https://docs.python-guide.org/writing/logging/#logging-in-a-library

tamr_client/attributes/attribute.py

@@ -1,3 +1,6 @@
+"""
+See https://docs.tamr.com/reference/attribute-types
+"""
 from copy import deepcopy
 from dataclasses import dataclass, field, replace
 from typing import Optional
@@ -146,7 +149,7 @@ def create(
     *,
     name: str,
     is_nullable: bool,
-    type: tc.attribute_type.AttributeType = tc.attribute_type_alias.DEFAULT,
+    type: tc.attribute_type.AttributeType = tc.attributes.type_alias.DEFAULT,
     description: Optional[str] = None,
 ) -> Attribute:
     """Create an attribute
@@ -189,7 +192,7 @@ def _create(
     *,
     name: str,
     is_nullable: bool,
-    type: tc.attribute_type.AttributeType = tc.attribute_type_alias.DEFAULT,
+    type: tc.attribute_type.AttributeType = tc.attributes.type_alias.DEFAULT,
     description: Optional[str] = None,
 ) -> Attribute:
     """Same as `tc.attribute.create`, but does not check for reserved attribute