datamasque-python 1.0.0__tar.gz

datamasque_python-1.0.0/.editorconfig

@@ -0,0 +1,21 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab

datamasque_python-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,124 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  lint:
+    name: Lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: ruff check
+        run: uv run ruff check datamasque tests
+
+      - name: ruff format --check
+        run: uv run ruff format --check datamasque tests
+
+  typecheck:
+    name: Typecheck (mypy)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: mypy
+        run: uv run mypy datamasque
+
+  test:
+    name: Tests (py${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.9', '3.10', '3.11', '3.12', '3.13']
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --frozen --python ${{ matrix.python-version }}
+
+      - name: pytest
+        run: >-
+          uv run --python ${{ matrix.python-version }}
+          pytest tests/
+          --junitxml=report.xml
+          --cov=datamasque
+          --cov-report=term
+          --cov-report=xml:coverage.xml
+          --import-mode=importlib
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-py${{ matrix.python-version }}
+          path: |
+            report.xml
+            coverage.xml
+          retention-days: 7
+
+  docs:
+    name: Docs (sphinx)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: uv sync --frozen
+
+      - name: sphinx-build
+        run: uv run sphinx-build -b html -W --keep-going docs docs/_build/html
+
+      - name: Upload built docs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: docs-html
+          path: docs/_build/html
+          retention-days: 7

datamasque_python-1.0.0/.github/workflows/release-testpypi.yml

@@ -0,0 +1,60 @@
+name: Release (TestPyPI)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Show package version
+        run: |
+          VERSION="$(uv run python -c 'import tomllib; print(tomllib.loads(open("pyproject.toml","rb").read().decode())["project"]["version"])')"
+          echo "Publishing version: ${VERSION}"
+          echo "::notice title=TestPyPI version::${VERSION}"
+
+      - name: Build
+        run: uv build
+
+      - name: Validate distributions
+        run: uvx twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist-testpypi
+          path: dist/
+          retention-days: 7
+
+  publish:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/datamasque-python
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist-testpypi
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

datamasque_python-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,62 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  build:
+    name: Build sdist and wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(uv run python -c 'import tomllib,sys; print(tomllib.loads(open("pyproject.toml","rb").read().decode())["project"]["version"])')"
+          echo "Tag version:     ${TAG_VERSION}"
+          echo "Package version: ${PKG_VERSION}"
+          if [ "${TAG_VERSION}" != "${PKG_VERSION}" ]; then
+            echo "::error::Tag ${GITHUB_REF_NAME} does not match pyproject.toml version ${PKG_VERSION}"
+            exit 1
+          fi
+
+      - name: Build
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/datamasque-python
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

datamasque_python-1.0.0/.gitignore

@@ -0,0 +1,55 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+coverage.xml
+report.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Sphinx documentation
+docs/_build/
+
+# pyenv
+.python-version
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# mypy
+.mypy_cache/
+
+# IDE settings
+.vscode/
+.idea/

datamasque_python-1.0.0/.readthedocs.yaml

@@ -0,0 +1,18 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.13"
+  jobs:
+    post_create_environment:
+      - pip install uv
+    post_install:
+      - UV_PROJECT_ENVIRONMENT=$READTHEDOCS_VIRTUALENV_PATH uv sync --frozen --all-groups
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

datamasque_python-1.0.0/CONTRIBUTING.rst

@@ -0,0 +1,166 @@
+============
+Contributing
+============
+
+Thanks for your interest in contributing to ``datamasque-python``!
+Contributions, bug reports, and feature requests are all welcome.
+
+Reporting bugs
+==============
+
+File an issue on the `GitHub issue tracker <https://github.com/datamasque/datamasque-python/issues>`_.
+Please include:
+
+- the version of ``datamasque-python`` you're using (``pip show datamasque-python``);
+- the Python version and operating system;
+- a minimal reproducer if possible;
+- the full traceback if the bug manifests as an exception.
+
+If the bug concerns a specific DataMasque server API response,
+include the status code and (with any sensitive fields redacted) the response body.
+
+Feature requests
+================
+
+Open an issue describing what you'd like to do and why.
+We're particularly interested in feedback on:
+
+- public API shape (method names, argument names, return types);
+- endpoints not yet wrapped by the client;
+- improvements to the typed return models.
+
+Development setup
+=================
+
+The project uses `uv <https://docs.astral.sh/uv/>`_ for dependency management.
+Install dependencies and set up a virtual environment:
+
+.. code-block:: console
+
+    git clone https://github.com/datamasque/datamasque-python.git
+    cd datamasque-python
+    uv sync
+
+Running the tests
+=================
+
+.. code-block:: console
+
+    uv run pytest
+
+The test suite runs entirely against mocked HTTP responses (``requests_mock``),
+so no DataMasque server is required.
+
+Linting and type-checking
+=========================
+
+.. code-block:: console
+
+    uv run ruff check datamasque tests
+    uv run ruff format --check datamasque tests
+    uv run mypy datamasque
+
+``ruff check`` enforces import order,
+Python style,
+and a set of pydocstyle rules (``D101``, ``D102``, ``D204``, ``D205``, ``D213``)
+that require docstrings on all public classes and methods.
+``ruff format`` applies the project's formatting style.
+``mypy`` runs in strict mode with ``disallow_untyped_defs``.
+
+Code style
+==========
+
+- **Line length:**
+  120 characters.
+  Enforced by ``ruff format``.
+- **Docstrings and comments:**
+  use `semantic line breaks <https://sembr.org/>`_ —
+  break at clause boundaries, not column widths.
+  This applies to text files (such as this file) as well as Python source.
+- **Docstring content:**
+
+  - Write for library consumers, not maintainers.
+  - Keep docstrings concise; no internal implementation notes.
+  - Multi-line docstrings start on the next line after the opening triple quotes.
+  - In Python docstrings,
+    use single backticks around anything code-like —
+    ``default_role = "any"`` in ``docs/conf.py`` makes Sphinx auto-link Python identifiers
+    and render everything else as monospace.
+    In top-level ``.rst`` files (``README.rst``, ``CONTRIBUTING.rst``, ``HISTORY.rst``)
+    use double backticks instead —
+    those are rendered directly by GitHub,
+    which doesn't honour the Sphinx role config.
+
+- **Enum member casing:**
+  enum members are ``lower_snake_case``, for example, ``DatabaseType.postgres``.
+- **Enum comparisons:**
+  use ``is`` / ``is not`` when comparing against specific enum members, not ``==`` / ``!=``.
+- **String formatting in messages:**
+  errors, log lines, and other user-facing messages follow a consistent quoting convention —
+  backticks around enum values and code identifiers,
+  double quotes around free-form string values.
+  Avoid ``!r`` in f-strings;
+  it produces Python's default single-quoted ``repr``,
+  which conflicts with the convention.
+  Use a single-quoted outer f-string
+  so double-quoted value literals don't need escaping:
+
+  .. code-block:: python
+
+      raise DataMasqueUserError(
+          f'The ruleset "{name}" is in `{state.value}` state.'
+      )
+
+  ``__str__`` follows this rule (it is a user-facing representation).
+  ``__repr__`` does not —
+  it follows Python's native ``repr`` convention,
+  where ``!r`` and single quotes are idiomatic.
+
+- **Identifier casing for initialisms:**
+  only the first letter of an initialism is capitalised in a camel-case identifier —
+  ``DataMasqueApiError``, not ``DataMasqueAPIError``.
+  The brand ``DataMasque`` is always spelled out in full.
+- **Serialization conventions:**
+  API models subclass pydantic ``BaseModel``.
+
+  - Serialise outgoing request bodies with ``model.model_dump(exclude_none=True, mode="json")``;
+    add ``by_alias=True`` when the model uses field aliases.
+  - Parse incoming responses with ``Model.model_validate(response.json())``.
+  - Use ``ConfigDict(extra="forbid")`` on outgoing request models
+    so a typo in a field name fails loudly.
+  - Use ``ConfigDict(extra="allow")`` on incoming response models
+    so unknown fields the server may add in future don't break deserialisation.
+- **Imports:**
+
+  - All imports at the top of the file; no inline imports.
+  - Absolute imports only; relative imports are not used.
+
+- **Formatting:**
+  run ``uv run ruff format`` before committing.
+
+Pull requests
+=============
+
+1. Fork the repository and create a feature branch.
+2. Add tests for any behavioural change.
+3. Run ``uv run pytest``, ``uv run ruff check``, ``uv run ruff format --check``, and ``uv run mypy``
+   locally before opening the PR.
+4. Keep commits focused; one logical change per commit is easier to review.
+5. Open a PR against ``main`` and describe what the change does and why.
+6. The maintainers will review and either merge, request changes, or close with an explanation.
+
+Commit messages
+===============
+
+Use `conventional commits <https://www.conventionalcommits.org/>`_ format where practical:
+``feat: add cancel_run method``,
+``fix: handle 401 retry for multipart uploads``,
+``docs: clarify make_request exception semantics``,
+and so on.
+
+License
+=======
+
+By contributing,
+you agree that your contributions will be licensed under the Apache License 2.0,
+the same license as the rest of the project.

datamasque_python-1.0.0/HISTORY.rst

@@ -0,0 +1,194 @@
+=======
+History
+=======
+
+1.0.0 (2026-04-21)
+------------------
+
+* **First public open-source release.**
+* All request and response types are now pydantic v2 models.
+* Added support for many new APIs.
+* Added ``DataMasqueIfmClient`` for the in-flight masking (IFM) API.
+* Overhauled error handling and added new exception types.
+* Certain request models now accept either a server-assigned ID or the corresponding object
+  (``ConnectionConfig``, ``Ruleset``) for entity-reference fields.
+* Added ``token_source`` callable-based authentication
+  to both ``DataMasqueInstanceConfig`` and ``DataMasqueIfmInstanceConfig``
+  as an alternative to ``password``.
+* Ruleset is now mandatory on masking run requests.
+* Fixed file data discovery API to accept both JSON path and standard locators.
+* Replaced the CSV-only ``get_rulesets_generated_from_csv`` with ``get_generated_rulesets``,
+  which handles all three async-ruleset-generation flows (CSV, column selection, file selection).
+
+0.6.3 (2026-04-10)
+------------------
+
+* Added ``db2i`` to ``DatabaseType`` enum.
+
+0.6.2 (2026-03-17)
+------------------
+
+* Added ``RULESET_LIBRARY_MANAGER`` user role.
+* Fixed superuser role value (``admin`` instead of empty string).
+* Superusers can now be created via the users API.
+* Fixed API field for user roles (``user_roles`` instead of ``roles``/``is_superuser``).
+
+0.6.1 (2026-03-16)
+------------------
+
+* Added ``InvalidLibraryError`` exception type.
+
+0.6.0 (2026-03-11)
+------------------
+
+* Added support for ruleset libraries.
+* Removed ``too_big`` from ruleset validation statuses (no longer used).
+* Migrated toolchain to ``uv`` with ``ruff``.
+* Added support for ``validating`` run status.
+
+0.5.1 (2026-03-10)
+------------------
+
+* Added ``delete_user_by_id_if_exists`` and ``delete_user_by_username_if_exists``.
+
+0.4.12 (2026-01-29)
+-------------------
+
+* Added support for downloading files.
+* Fixed positional argument call in ``dmclient.py``.
+
+0.4.11 (2025-12-11)
+-------------------
+
+* Fixed ``start_async_ruleset_generation_from_csv`` to use new file upload specification.
+
+0.4.10 (2025-12-10)
+-------------------
+
+* Fixed issue with file uploads when request was retried after a 401 response.
+
+0.4.9 (2025-11-26)
+------------------
+
+* Added ``get_run_report`` and ``start_schema_discovery_run`` endpoints.
+
+0.4.8 (2025-09-19)
+------------------
+
+* Updated ``admin_install`` endpoint to support username parameter
+
+0.4.7 (2025-08-29)
+------------------
+
+* Added support for Redshift
+
+0.4.6 (2025-07-18)
+------------------
+
+* Added support for ``engine_options`` in database connection config
+* Updated ``ruleset`` endpoint to use ``upsert`` behaviour
+* Updated Snowflake connection handling for encrypted connection strings
+
+0.4.5 (2025-06-30)
+------------------
+
+* Added support for ``hash_columns`` in ruleset generator requests.
+
+0.4.4 (2025-06-09)
+------------------
+
+* Added support for Azure Blob Storage as a Snowflake staging platform.
+
+0.4.3 (2025-05-16)
+------------------
+
+* Added support for specifying Snowflake staging platform.
+
+0.4.2 (2025-04-03)
+------------------
+
+* Added support for Snowflake keypair authentication.
+
+0.4.1 (2025-03-25)
+------------------
+
+* Made snowflake role field optional.
+
+0.4.0 (2025-03-17)
+------------------
+
+* Added support for Snowflake connections.
+
+0.3.0 (2024-10-24)
+------------------
+
+* Added support for asynchronous ruleset generation with ``start_async_ruleset_generation``.
+* Added support for CSV-based ruleset generation with ``start_async_ruleset_generation_from_csv`` and ``get_rulesets_generated_from_csv``.
+
+0.2.9 (2024-09-27)
+------------------
+
+* Added support for the ``dynamo_default_sse`` configuration option on DynamoDB connections.
+
+0.2.7 (2024-08-26)
+------------------
+
+* Fixed the user creation API.
+
+0.2.6 (2024-08-09)
+------------------
+
+* Removed the ``run_not_started`` pseudo-status from the ``MaskingRunStatus`` enum.
+* Added support for the ``data_encoding`` connection parameter on MySQL and MariaDB.
+
+0.2.5 (2024-08-07)
+------------------
+
+* Added support for the ``finished_with_warnings`` run status.
+
+0.2.4 (2024-08-01)
+------------------
+
+* Added support for MSSQL Linked Server connections.
+
+0.2.3 (2024-07-30)
+------------------
+
+* Fixed ``set_locality`` passing in "locality" rather than "region".
+
+0.2.2 (2024-07-29)
+------------------
+
+* Add support for passing a filename or StringIO when uploading a license
+* Add handling for HTTP 502 errors
+
+0.2.1 (2024-07-23)
+------------------
+
+* Add Ruleset model
+* Fix numerous issues with the new Connection models
+* Introduce a separate model for Dynamo connections
+
+0.2.0 (2024-07-22)
+------------------
+
+* Drastic simplification of the config models
+* Add new features:
+    * file data discovery
+    * file ruleset generation
+    * locality
+    * seed file deletion
+    * list connections and delete connections
+    * user APIs
+* Use v2 ruleset generation API
+
+0.1.2 (2024-01-22)
+------------------
+
+* Export RunID, remove RunFailureReason
+* Run tests using Tox against Python 3.9 and above
+
+0.1.1 (2024-01-19)
+------------------
+
+* First release