instructure-dap-client 2.2.0b2__tar.gz → 2.3.0__tar.gz

{instructure_dap_client-2.2.0b2 → instructure_dap_client-2.3.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022-2024 Instructure, Inc.
+Copyright (c) 2022-2026 Instructure, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal
@@ -19,3 +19,24 @@ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
+
+
+===============================================================================
+Third-party vendored components
+===============================================================================
+
+This distribution bundles the following third-party packages as top-level
+modules. Both are licensed under the MIT License, whose terms are reproduced
+above, with the copyright notices below. The versions bundled are recorded in
+`vendor/VENDORED.md`.
+
+`strong_typing` -- derived from https://github.com/hunyadi/strong_typing
+
+    Copyright (c) 2021-2026 Levente Hunyadi
+    Copyright (c) 2021-2026 Instructure Inc.
+    Copyright (c) 2021 Kheiron Medical Technologies Ltd.
+
+`pysqlsync` -- derived from https://github.com/hunyadi/pysqlsync
+
+    Copyright (c) 2023-2025 Levente Hunyadi
+    Copyright (c) 2026 Instructure, Inc.

instructure_dap_client-2.3.0/MANIFEST.in

@@ -0,0 +1,11 @@
+include dap/version_upgrade/*.sql
+
+# Vendored packages -- see vendor/VENDORED.md. `recursive-include` mirrors the
+# forks' own MANIFEST files, so package data added by a future re-vendor (e.g. a
+# new dialect README) is picked up without editing this file.
+include strong_typing/py.typed
+include pysqlsync/py.typed
+recursive-include pysqlsync *.md
+
+global-exclude *.pyc
+global-exclude __pycache__/*

{instructure_dap_client-2.2.0b2 → instructure_dap_client-2.3.0}/PKG-INFO

@@ -1,16 +1,14 @@
 Metadata-Version: 2.4
 Name: instructure-dap-client
-Version: 2.2.0b2
+Version: 2.3.0
 Summary: Data Access Platform client library
-Maintainer: Instucture, Inc.
-Maintainer-email: dapclient@instructure.com
-License: MIT
-Project-URL: Changelog, https://community.canvaslms.com/t5/Canvas-Change-Log/2025-API-and-CLI-Change-Log/ta-p/626858
-Classifier: Development Status :: 4 - Beta
+Maintainer-email: "Instructure, Inc." <dapclient@instructure.com>
+License-Expression: MIT
+Project-URL: Changelog, https://community.instructure.com/en/discussion/664378/2026-api-and-cli-change-log
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
 Classifier: Intended Audience :: End Users/Desktop
-Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
@@ -21,22 +19,24 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: aiohttp>=3.8.4
-Requires-Dist: aiohttp-retry>=2.8.3
-Requires-Dist: aiofiles>=23.1.0
-Requires-Dist: asyncclick==8.1.8
-Requires-Dist: types-aiofiles>=23.1.0
-Requires-Dist: json_strong_typing>=0.3.9
-Requires-Dist: pysqlsync[tsv]>=0.8.4
-Requires-Dist: PyJWT>=2.7.0
-Requires-Dist: tsv2py>=0.7.1
-Requires-Dist: rich>=14.0.0
+Requires-Dist: aiohttp==3.13.4
+Requires-Dist: aiohttp-retry==2.9.1
+Requires-Dist: aiofiles==25.1.0
+Requires-Dist: asyncclick==8.1.8.0
+Requires-Dist: PyJWT==2.13.0
+Requires-Dist: tsv2py==0.7.1
+Requires-Dist: rich==14.3.3
+Requires-Dist: jsonschema==4.26.0
+Requires-Dist: truststore==0.10.4
+Requires-Dist: typing_extensions==4.16.0; python_version < "3.12"
 Provides-Extra: postgresql
-Requires-Dist: pysqlsync[postgresql]>=0.8.4; extra == "postgresql"
+Requires-Dist: asyncpg==0.31.0; extra == "postgresql"
 Provides-Extra: mysql
-Requires-Dist: pysqlsync[mysql]>=0.8.4; extra == "mysql"
+Requires-Dist: aiomysql==0.3.2; extra == "mysql"
+Requires-Dist: PyMySQL[rsa]==1.2.0; extra == "mysql"
+Requires-Dist: cryptography==50.0.0; extra == "mysql"
 Provides-Extra: mssql
-Requires-Dist: pysqlsync[mssql]>=0.8.4; extra == "mssql"
+Requires-Dist: pyodbc==5.3.0; extra == "mssql"
 Dynamic: license-file
 
 # Data Access Platform Client Library

instructure_dap_client-2.3.0/README.md

@@ -0,0 +1,73 @@
+# Data Access Platform CLI & Client Library
+
+Data Access Platform (DAP) acts as a single source of data for analytics at Instructure. It provides efficient access to data collected across various educational products in bulk with high fidelity and low latency, adhering to a canonical data model.
+
+The DAP CLI and Client Library is a Python wrapper around the [DAP Query API](https://developerdocs.instructure.com/services/dap/query-api), allowing you to fetch an initial snapshot and incremental changes, or initialize a supported database and keep it synchronized with [data in DAP](https://developerdocs.instructure.com/services/dap/dataset).
+
+See [DAP Client Library Documentation](https://developerdocs.instructure.com/services/dap/dap-cli-readme).
+
+Docs source repo: https://github.com/instructure/data-access-platform-documentation.
+
+For development guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Generate lib-reference documentation
+
+`util/markdown_generator.py` (in the repository root, not under `cli/`) generates the GitBook Markdown
+client library reference — `lib-reference.md` — from the public API, the database replicator, the shared
+types, and the exception hierarchy.
+
+It depends on `instructure-markdown-doc`, hosted on the internal Artifactory (authentication required). It
+is **not** declared as a project dependency: it would force Artifactory authentication on every
+`pip install`. Instead it is installed on its own, after authenticating, only when generating the docs. In
+CI this is handled by the [`cli-doc.yml`](../.github/workflows/cli-doc.yml) workflow.
+
+### Authenticate to Artifactory
+
+`pip` needs to be pointed at the authenticated Artifactory PyPI index to resolve `instructure-markdown-doc`.
+
+1. Generate a personal **Identity Token** in the [JFrog UI](https://instructure.jfrog.io): click your
+   username (top right) → **Edit Profile** → **Generate an Identity Token**. Copy it.
+2. Export `ARTIFACTORY_INDEX_URL` in your shell profile (e.g. `~/.zshrc`), using your JFrog username (shown
+   under **Edit Profile**) as the username and the identity token as the password:
+
+   ```sh
+   export ARTIFACTORY_INDEX_URL="https://<jfrog-username>:<identity-token>@instructure.jfrog.io/artifactory/api/pypi/virtual-pypi/simple"
+   ```
+
+   Restart the shell (or `source` the profile) so the variable is set.
+
+> The token grants access under your account — treat it like a password. Keep it in your shell profile or a
+> secrets manager; do not commit it.
+
+### Run the generator
+
+With `ARTIFACTORY_INDEX_URL` set, install `instructure-markdown-doc` into the workspace environment, then
+run the generator from the **repository root** — the `cli.dap` imports resolve against `PYTHONPATH`, and the
+output path is relative to the script:
+
+```sh
+uv sync --all-packages --all-extras
+uv pip install --index "$ARTIFACTORY_INDEX_URL" instructure-markdown-doc==0.2.1
+PYTHONPATH=. uv run --no-sync python util/markdown_generator.py
+```
+
+`--no-sync` on the last command is required: a plain `uv run` re-syncs the environment, and because sync is
+exact it would uninstall the ad-hoc `instructure-markdown-doc` installed on the line before.
+
+The generated Markdown is written to `util/markdown/target/`.
+
+### Automatic publishing on release
+
+The [`cli-doc.yml`](../.github/workflows/cli-doc.yml) workflow runs the generator in CI. Its behavior
+depends on the trigger:
+
+- **Push/PR to `main`, or `workflow_dispatch`** — generates `lib-reference.md` and uploads it as a build
+  artifact (`generated-docs`). Nothing is published.
+- **Version tag push (`v*`, e.g. `v2.2.0`)** — first verifies the tag matches `__version__` in
+  `cli/dap/__init__.py` (failing fast on a mistagged release), then generates the doc and **opens a PR**
+  against the [documentation repo](https://github.com/instructure/data-access-platform-documentation),
+  replacing its `docs/lib-reference.md`. If the generated doc is unchanged, no PR is opened.
+
+The PR is authored by the "DAP Docs Updater" GitHub App (installed on the documentation repo with
+`Contents: write` + `Pull requests: write`); a human reviews and merges it. The branch and commit carry
+provenance back to the source tag and the Actions run.

{instructure_dap_client-2.2.0b2 → instructure_dap_client-2.3.0}/dap/__init__.py

@@ -6,9 +6,9 @@ to data collected across various educational products in bulk with high fidelity
 a canonical data model.
 """
 
-__version__ = "2.2.0b2"
-__copyright__ = "Copyright 2022-2025, Instructure, Inc."
+__version__ = "2.3.0"
+__copyright__ = "Copyright 2022-2026, Instructure, Inc."
 __license__ = "MIT"
 __maintainer__ = "Instructure, Inc."
 __email__ = "dapclient@instructure.com"
-__status__ = "Beta"
+__status__ = "Production"

{instructure_dap_client-2.2.0b2 → instructure_dap_client-2.3.0}/dap/actions/init_db.py

@@ -23,4 +23,6 @@ async def init_db(
         async def replicate_table_fn(namespace: str, table: str) -> None:
             await sql_replicator.initialize(namespace, table)
 
-        await session.execute_operation_on_tables(namespace, table_names, "initdb", replicate_table_fn)
+        await session.execute_operation_on_tables(
+            namespace, table_names, "initdb", replicate_table_fn
+        )

instructure_dap_client-2.3.0/dap/actions/list_db.py

@@ -0,0 +1,176 @@
+import json
+from datetime import datetime, timezone
+from typing import Optional
+
+from pysqlsync.model.id_types import PrefixedId, QualifiedId
+
+from .. import ui
+from ..api import DAPClient
+from ..dap_types import Credentials
+from ..integration.database import DatabaseConnection
+from ..replicator import meta_schema
+from ..replicator.sql_metatable_handler import (
+    get_table_meta_record,
+    get_table_names_in_namespace_from_meta,
+)
+
+
+def _count_from_clause(
+    dialect: str, target_schema: Optional[str], target_table: str
+) -> str:
+    if dialect == "mysql":
+        # MySQL has no schemas; pysqlsync uses namespace__table (ANSI_QUOTES mode is always enabled)
+        return str(PrefixedId(target_schema, target_table))
+    else:
+        # PostgreSQL and MSSQL use schema.table
+        return str(QualifiedId(target_schema, target_table))
+
+
+def cell(value: str | None, fallback: str = "-") -> tuple[ui.MsgType, str]:
+    if value is not None:
+        return (ui.MsgType.TITLE, value)
+    return (ui.MsgType.INFO, fallback)
+
+
+def calculate_age(timestamp: datetime) -> str:
+    # timestamp is naive but represents UTC time, so get current UTC time for comparison
+    now = (
+        datetime.now(timezone.utc).replace(tzinfo=None)
+        if timestamp.tzinfo is None
+        else datetime.now(timestamp.tzinfo)
+    )
+    age_seconds = int((now - timestamp).total_seconds())
+    days, remainder = divmod(age_seconds, 86400)
+    hours, remainder = divmod(remainder, 3600)
+    minutes, seconds = divmod(remainder, 60)
+    if days > 0:
+        return f"{days}d {hours}h" if hours > 0 else f"{days}d"
+    elif hours > 0:
+        return f"{hours}h {minutes}m" if minutes > 0 else f"{hours}h"
+    elif minutes > 0:
+        return f"{minutes}m {seconds}s" if seconds > 0 else f"{minutes}m"
+    else:
+        return f"{seconds}s"
+
+
+async def list_db(
+    base_url: str,
+    credentials: Credentials,
+    connection_string: str,
+    namespace: str,
+    tracking: Optional[bool] = None,
+    omit_not_replicated: bool = False,
+    omit_record_count: bool = False,
+) -> None:
+    dap_tables_names = []
+    async with DAPClient(
+        base_url=base_url, credentials=credentials, tracking=tracking
+    ) as session:
+        dap_tables_names = await session.get_tables(namespace)
+        if not omit_record_count:
+            ui.info("Querying table record counts...")
+        db_connection = DatabaseConnection(connection_string)
+        async with db_connection.connection as base_connection:
+            explorer = db_connection.engine.create_explorer(base_connection)
+            await explorer.synchronize(modules=[meta_schema])
+            db_table_names = await get_table_names_in_namespace_from_meta(
+                base_connection, namespace
+            )
+            db_table_meta_records: dict[str, Optional[meta_schema.table_sync]] = {}
+            for table_name in sorted(db_table_names):
+                meta = await get_table_meta_record(
+                    base_connection, namespace, table_name
+                )
+                if meta is not None:
+                    db_table_meta_records[table_name] = meta
+            if not omit_not_replicated:
+                for table_name in sorted(dap_tables_names):
+                    if table_name not in db_table_meta_records:
+                        db_table_meta_records[table_name] = None
+
+            db_table_record_counts = {}
+            for table_name, meta in db_table_meta_records.items():
+                if meta is not None and not omit_record_count:
+                    from_clause = _count_from_clause(
+                        db_connection.dialect, meta.target_schema, meta.target_table
+                    )
+                    count = await base_connection.query_one(
+                        int,
+                        f"SELECT COUNT(*) FROM {from_clause}",
+                    )
+                    db_table_record_counts[table_name] = count
+
+            title_str = f"Local database replication status of tables in namespace [bold]{namespace}[/bold]"
+            columns = [
+                ui.TableColumn("Name", style="bold"),
+                *(
+                    []
+                    if omit_record_count
+                    else [ui.TableColumn("Records", style="bold", justify="right")]
+                ),
+                ui.TableColumn("Data as of"),
+                ui.TableColumn("Staleness"),
+                ui.TableColumn("Schema", justify="right"),
+                ui.TableColumn("Use command"),
+            ]
+            ui.print_table(
+                title=title_str,
+                columns=columns,
+                rows=[
+                    [
+                        cell(table_name if meta is not None else None, table_name),
+                        *(
+                            []
+                            if omit_record_count
+                            else [
+                                cell(
+                                    str(db_table_record_counts[table_name])
+                                    if table_name in db_table_record_counts
+                                    else None
+                                )
+                            ]
+                        ),
+                        cell(
+                            meta.timestamp.replace(tzinfo=timezone.utc)
+                            .astimezone()
+                            .isoformat()
+                            if meta is not None
+                            else None,
+                            "Not replicated",
+                        ),
+                        cell(
+                            calculate_age(meta.timestamp) if meta is not None else None
+                        ),
+                        cell(str(meta.schema_version) if meta is not None else None),
+                        cell("syncdb" if meta is not None else None, "initdb"),
+                    ]
+                    for table_name, meta in db_table_meta_records.items()
+                ],
+            )
+            if not ui.is_interactive():
+                rows = []
+                for table_name, meta in db_table_meta_records.items():
+                    row: dict = {
+                        "name": table_name,
+                        "timestamp": meta.timestamp.replace(tzinfo=timezone.utc)
+                        .astimezone()
+                        .isoformat()
+                        if meta is not None
+                        else None,
+                        "staleness": calculate_age(meta.timestamp)
+                        if meta is not None
+                        else None,
+                        "schema": meta.schema_version if meta is not None else None,
+                        "command": "syncdb" if meta is not None else "initdb",
+                    }
+                    if not omit_record_count:
+                        row["records"] = db_table_record_counts.get(table_name)
+                    rows.append(row)
+                print(json.dumps(rows, indent=2))
+
+            if session.tracking_data:
+                session.tracking_data.set_cmd_info("listdb", namespace, None)
+                session.tracking_data.db_dialect = db_connection.dialect
+                session.tracking_data.db_version = await db_connection.get_version(
+                    db_connection.dialect, base_connection
+                )

{instructure_dap_client-2.2.0b2 → instructure_dap_client-2.3.0}/dap/actions/sync_db.py

@@ -23,4 +23,6 @@ async def sync_db(
         async def replicate_table_fn(namespace: str, table: str) -> None:
             await sql_replicator.synchronize(namespace, table)
 
-        await session.execute_operation_on_tables(namespace, table_names, "syncdb", replicate_table_fn)
+        await session.execute_operation_on_tables(
+            namespace, table_names, "syncdb", replicate_table_fn
+        )