datamaker-py 0.9.0__tar.gz → 0.11.0__tar.gz

datamaker_py-0.11.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: datamaker-py
+Version: 0.11.0
+Summary: The official Python library for the Automators DataMaker API.
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.32.3
+Dynamic: license-file
+
+# DataMaker
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)
+
+The official Python library for the Automators DataMaker API.
+
+## Installation
+
+You can install the package using pip:
+
+```sh
+pip install datamaker-py
+```
+
+## Quick start
+
+Basic example:
+
+```python
+from datamaker import DataMaker, Template
+
+# Create an instance of DataMaker
+datamaker = DataMaker()
+
+
+def main():
+    # Define the template
+    template = Template(
+        name="basic template",
+        quantity=2,
+        fields=[
+            {"name": "first_name", "type": "First Name"},
+            {"name": "last_name", "type": "Last Name"},
+            {
+                "name": "email",
+                "type": "Derived",
+                "options": {"value": "{{first_name}}.{{last_name}}@automators.com"},
+            },
+        ],
+    )
+
+    # Generate data using the template
+    result = datamaker.generate(template)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()
+
+```
+
+## Push a set into Tosca Cloud
+
+`push_tosca_dataset` creates or replaces a native Tosca Cloud data set from a saved
+set, an input set version, a dataset or inline rows. A Tosca test step reads it with
+`{TDM[<data set>][<subset>][<column>]}`.
+
+```python
+from datamaker import DataMaker, ToscaDatasetSchemaChangedError
+
+dm = DataMaker()
+
+try:
+    result = dm.push_tosca_dataset(
+        integration_id,
+        name="Orders",
+        input_set_id="is_123",        # or set_id=..., dataset_id=..., rows=[...]
+        on_existing="overwrite",      # "fail" (default) | "overwrite" | "new"
+    )
+    print(result.dataset_id, result.rows_count, result.outcome, result.example)
+except ToscaDatasetSchemaChangedError as e:
+    # The rows dropped a column the data set has. Pass on_schema_change="recreate"
+    # to delete and recreate it instead.
+    print("removed:", e.removed_columns, "added:", e.added_columns)
+```
+
+An input set gets one Tosca subset per test case by default; `subsets_by` picks another
+column or turns it off with `False`. `get_tosca_datasets(integration_id)` lists what a
+space already holds.
+
+## Autocomplete Types
+
+This SDK automatically generates TypeScript autocomplete definitions for use in the [datamaker application](https://github.com/automators/datamaker). 
+
+The artifact is generated automatically on every push to the `main` branch and can be fetched from:
+
+```
+https://raw.githubusercontent.com/automators/datamaker-py/main/artifacts/autocomplete-types.ts
+```
+
+See [`artifacts/README.md`](artifacts/README.md) for more details.
+
+## Development & Contibutions
+
+See the [contributing.md](/CONTRIBUTING.md) guide for details on how to contribute to this project.
+
+## Types
+
+Response types are **generated** from the API's OpenAPI document, not hand-written:
+
+```
+spec/openapi.json  ->  src/datamaker/generated/schema.py  ->  src/datamaker/types.py
+```
+
+Import from `datamaker.types`, which resolves each spec schema name to the class
+that really matches it:
+
+```python
+from datamaker.types import Project, Plan, Template
+
+projects: list[Project] = dm.get_projects()
+```
+
+They are `TypedDict`s, so nothing changes at runtime — methods still return the
+plain dicts `response.json()` produces, and `project["name"]` works exactly as
+before. The types are checker-only.
+
+To regenerate after the API changes:
+
+```bash
+python scripts/generate_schema.py
+```
+
+CI runs `python scripts/generate_schema.py --check` and fails if the committed
+types drift from the spec.
+
+Three schemas cannot currently be generated (`SetDetail`, `PackInstallListItem`,
+`SchemaGraphNavigation`): they are composed with `allOf`, which the generator
+merges away rather than emitting as a named class. Methods returning those keep
+`Dict`. The generator script lists them explicitly and fails if the set grows.

datamaker_py-0.11.0/README.md

@@ -0,0 +1,132 @@
+# DataMaker
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/charliermarsh/ruff/main/assets/badge/v1.json)](https://github.com/charliermarsh/ruff)
+
+The official Python library for the Automators DataMaker API.
+
+## Installation
+
+You can install the package using pip:
+
+```sh
+pip install datamaker-py
+```
+
+## Quick start
+
+Basic example:
+
+```python
+from datamaker import DataMaker, Template
+
+# Create an instance of DataMaker
+datamaker = DataMaker()
+
+
+def main():
+    # Define the template
+    template = Template(
+        name="basic template",
+        quantity=2,
+        fields=[
+            {"name": "first_name", "type": "First Name"},
+            {"name": "last_name", "type": "Last Name"},
+            {
+                "name": "email",
+                "type": "Derived",
+                "options": {"value": "{{first_name}}.{{last_name}}@automators.com"},
+            },
+        ],
+    )
+
+    # Generate data using the template
+    result = datamaker.generate(template)
+    print(result)
+
+
+if __name__ == "__main__":
+    main()
+
+```
+
+## Push a set into Tosca Cloud
+
+`push_tosca_dataset` creates or replaces a native Tosca Cloud data set from a saved
+set, an input set version, a dataset or inline rows. A Tosca test step reads it with
+`{TDM[<data set>][<subset>][<column>]}`.
+
+```python
+from datamaker import DataMaker, ToscaDatasetSchemaChangedError
+
+dm = DataMaker()
+
+try:
+    result = dm.push_tosca_dataset(
+        integration_id,
+        name="Orders",
+        input_set_id="is_123",        # or set_id=..., dataset_id=..., rows=[...]
+        on_existing="overwrite",      # "fail" (default) | "overwrite" | "new"
+    )
+    print(result.dataset_id, result.rows_count, result.outcome, result.example)
+except ToscaDatasetSchemaChangedError as e:
+    # The rows dropped a column the data set has. Pass on_schema_change="recreate"
+    # to delete and recreate it instead.
+    print("removed:", e.removed_columns, "added:", e.added_columns)
+```
+
+An input set gets one Tosca subset per test case by default; `subsets_by` picks another
+column or turns it off with `False`. `get_tosca_datasets(integration_id)` lists what a
+space already holds.
+
+## Autocomplete Types
+
+This SDK automatically generates TypeScript autocomplete definitions for use in the [datamaker application](https://github.com/automators/datamaker). 
+
+The artifact is generated automatically on every push to the `main` branch and can be fetched from:
+
+```
+https://raw.githubusercontent.com/automators/datamaker-py/main/artifacts/autocomplete-types.ts
+```
+
+See [`artifacts/README.md`](artifacts/README.md) for more details.
+
+## Development & Contibutions
+
+See the [contributing.md](/CONTRIBUTING.md) guide for details on how to contribute to this project.
+
+## Types
+
+Response types are **generated** from the API's OpenAPI document, not hand-written:
+
+```
+spec/openapi.json  ->  src/datamaker/generated/schema.py  ->  src/datamaker/types.py
+```
+
+Import from `datamaker.types`, which resolves each spec schema name to the class
+that really matches it:
+
+```python
+from datamaker.types import Project, Plan, Template
+
+projects: list[Project] = dm.get_projects()
+```
+
+They are `TypedDict`s, so nothing changes at runtime — methods still return the
+plain dicts `response.json()` produces, and `project["name"]` works exactly as
+before. The types are checker-only.
+
+To regenerate after the API changes:
+
+```bash
+python scripts/generate_schema.py
+```
+
+CI runs `python scripts/generate_schema.py --check` and fails if the committed
+types drift from the spec.
+
+Three schemas cannot currently be generated (`SetDetail`, `PackInstallListItem`,
+`SchemaGraphNavigation`): they are composed with `allOf`, which the generator
+merges away rather than emitting as a named class. Methods returning those keep
+`Dict`. The generator script lists them explicitly and fails if the set grows.

{datamaker_py-0.9.0 → datamaker_py-0.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "datamaker-py"
-version = "0.9.0"
+version = "0.11.0"
 description = "The official Python library for the Automators DataMaker API."
 readme = "README.md"
 requires-python = ">=3.11"

datamaker_py-0.11.0/src/datamaker/__init__.py

@@ -0,0 +1,12 @@
+from .main import DataMaker  # noqa
+from .template import Template  # noqa
+from .error import (  # noqa
+    DataMakerError,
+    DataMakerAPIError,
+    ReadOnlyConnectionError,
+    ToscaDatasetExistsError,
+    ToscaDatasetLockedError,
+    ToscaDatasetSchemaChangedError,
+    ToscaDatasetTooLargeError,
+)
+from .routes.tosca import ToscaDatasetPushResult  # noqa

datamaker_py-0.11.0/src/datamaker/error.py

@@ -0,0 +1,94 @@
+from typing import Any, List, Optional
+
+
+class DataMakerError(Exception):
+    pass
+
+
+class DataMakerAPIError(DataMakerError):
+    """The API answered with a non-2xx status.
+
+    Subclasses ``DataMakerError`` and keeps its message, so existing
+    ``except DataMakerError`` handlers are unaffected. Adds the status code and
+    the decoded JSON body (``None`` when the body was not JSON).
+    """
+
+    def __init__(self, message: str, status_code: int, body: Any = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+    def _detail(self, key: str) -> Any:
+        return self.body.get(key) if isinstance(self.body, dict) else None
+
+
+class ReadOnlyConnectionError(DataMakerAPIError):
+    """403: the connection is read-only, so DataMaker refused the write."""
+
+
+class ToscaDatasetExistsError(DataMakerAPIError):
+    """409: a Tosca data set of that name exists and ``on_existing`` is "fail"."""
+
+    @property
+    def dataset_id(self) -> Optional[str]:
+        """The id of the data set that is already there."""
+        return self._detail("datasetId")
+
+
+class ToscaDatasetLockedError(DataMakerAPIError):
+    """409: the data set is locked in Tosca Cloud, so it cannot be overwritten.
+
+    A test run or a "Test data - Expert" step holds it. Retry once it is
+    unlocked.
+    """
+
+    @property
+    def dataset_id(self) -> Optional[str]:
+        return self._detail("datasetId")
+
+
+class ToscaDatasetSchemaChangedError(DataMakerAPIError):
+    """409: an overwrite would drop columns the Tosca data set has.
+
+    Tosca only overwrites in place when the columns match. Added columns are
+    handled by the API; a removed column is refused unless the push asks for
+    ``on_schema_change="recreate"``.
+    """
+
+    @property
+    def dataset_id(self) -> Optional[str]:
+        return self._detail("datasetId")
+
+    @property
+    def added_columns(self) -> List[str]:
+        return self._detail("added") or []
+
+    @property
+    def removed_columns(self) -> List[str]:
+        return self._detail("removed") or []
+
+
+class ToscaDatasetTooLargeError(DataMakerAPIError):
+    """413: more rows or bytes than one push may write.
+
+    The row pair (``max_rows``, ``rows``) or the byte pair (``max_bytes``,
+    ``bytes``) is set, depending on which cap was hit. A set, input set or
+    dataset refused before its rows are loaded carries neither; the message
+    names the cap.
+    """
+
+    @property
+    def max_rows(self) -> Optional[int]:
+        return self._detail("maxRows")
+
+    @property
+    def rows(self) -> Optional[int]:
+        return self._detail("rows")
+
+    @property
+    def max_bytes(self) -> Optional[int]:
+        return self._detail("maxBytes")
+
+    @property
+    def bytes(self) -> Optional[int]:
+        return self._detail("bytes")

datamaker_py-0.11.0/src/datamaker/generated/__init__.py

@@ -0,0 +1,7 @@
+"""Types generated from the API's OpenAPI document. Do not edit by hand.
+
+Regenerate with `python scripts/generate_schema.py`; CI fails if this drifts
+from `spec/openapi.json`.
+"""
+
+from .schema import *  # noqa: F401,F403