3tears-datasources 0.14.0__py3-none-any.whl

3tears_datasources-0.14.0.dist-info/METADATA

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: 3tears-datasources
+Version: 0.14.0
+Summary: datasource entities, collections, namespace helpers, agent-yaml config model + driver abstraction for postgres/redshift/snowflake/bigquery backends
+Project-URL: Repository, https://github.com/pacepace/3tears
+Project-URL: Documentation, https://github.com/pacepace/3tears/tree/develop/packages/datasources
+Author: pace
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: 3tears-observe
+Requires-Dist: 3tears<1.0,>=0.9.1
+Requires-Dist: asyncpg>=0.29
+Requires-Dist: pydantic>=2.0
+Provides-Extra: bigquery
+Requires-Dist: google-cloud-bigquery>=3.0; extra == 'bigquery'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.15.18; extra == 'dev'
+Provides-Extra: redshift
+Requires-Dist: redshift-connector>=2.1; extra == 'redshift'
+Provides-Extra: snowflake
+Requires-Dist: snowflake-connector-python>=3.0; extra == 'snowflake'
+Description-Content-Type: text/markdown
+
+# 3tears-datasources
+
+Datasource entities, three-tier collections, namespace helpers, the
+agent-yaml-facing `DatasourceConfig`, and the `Driver` abstraction
+(plus concrete asyncpg + Redshift drivers) for the 3tears platform.
+
+This is the single source of truth for "what is a datasource" across
+every 3tears consumer.
+
+## Public surface
+
+Imported via `from threetears.datasources import …`:
+
+- **entities** -- `DataSourceEntity`, `DataSourceTableEntity`,
+  `DataSourceColumnEntity`, `DataSourceRelationEntity`,
+  `TableTemplateEntity` + the `DataSourceType`,
+  `DataSourceAccessMode`, `DataSourceStatus` enums.
+- **collections** -- `DataSourceCollection`,
+  `DataSourceTableCollection`, `DataSourceColumnCollection`,
+  `DataSourceRelationCollection`, `TableTemplateCollection`
+  (three-tier `SchemaBackedCollection` / `BaseCollection` subclasses
+  with L1/L2/L3 caching + `_publish_invalidation` on save).
+- **namespace** -- `DATASOURCE_NAMESPACE_TYPE`,
+  `datasource_namespace_id(uuid) -> uuid`,
+  `datasource_namespace_name(name) -> str`.
+- **config** -- `DatasourceConfig` (the agent-yaml-facing model the
+  SDK validates against) plus the per-driver `ConnectionConfig`
+  discriminated union.
+
+## Drivers
+
+The `Driver` ABC + `create_driver(config, *, hub_l3_pool=None)` factory
+are the entry point. Concrete drivers are accessed via the
+factory, NOT imported directly:
+
+```python
+from threetears.datasources.drivers import create_driver
+driver = create_driver(config.connection_config)
+try:
+    rows = await driver.fetch("SELECT * FROM customers WHERE id = $1", customer_id)
+finally:
+    await driver.close()
+```
+
+Driver implementations live behind extras keys:
+
+- `pip install '3tears-datasources[redshift]'` for `RedshiftDriver`
+- `pip install '3tears-datasources[snowflake]'` for `SnowflakeDriver`
+  (stub today; full impl tracked separately)
+- `pip install '3tears-datasources[bigquery]'` for `BigQueryDriver`
+  (stub today; full impl tracked separately)
+
+Postgres / Yugabyte / agent_internal coverage uses `asyncpg` which is
+a hard dep (no extras key required).
+
+See `IMPLEMENTING_DRIVERS.md` for the contract every new driver must
+satisfy.
+
+## Versioning policy
+
+`3tears-datasources` versions in **lockstep** with the rest of the
+3tears monorepo: every package shares one version, which tracks the
+framework git tag (`v0.9.1` at time of writing). All packages move
+together.
+
+The `pyproject.toml` depends on 3tears core via a compatible-release
+range (`3tears>=0.9.1,<1.0`); because the monorepo bumps together, any
+matching `0.9.x` core satisfies it.
+
+See `CHANGELOG.md` for the full version history.

3tears_datasources-0.14.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+threetears/datasources/__init__.py,sha256=sGWryTHfswlQSVt7hDoJaz3cAl7oaZuGUbchw0K6Pkk,4159
+threetears/datasources/collections.py,sha256=EzXGJKFGWKdaR3raiTVmth4JOl8j5ryZRrKXx_D4cc4,44096
+threetears/datasources/config.py,sha256=jKgxvJzkGdvXe1_AtmA-UVS-xVZ43SjMOSpsu0073tM,28616
+threetears/datasources/entities.py,sha256=leRa6oyScUrOIl703r8yY3_JlGC1l5RKRuKwuChCEak,10222
+threetears/datasources/introspection.py,sha256=dMacEtranLKQXclMskk8BZ5qVD8kU8BScpXcVNNHrw4,8637
+threetears/datasources/namespace.py,sha256=GBFZQeYwDVNvZFu8ZohFRmhxtBSLBUvi5FNl4HfCGOY,2005
+threetears/datasources/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+threetears/datasources/schema_priming.py,sha256=IXkXju7hDp2ixbHMzXoRnKeghhCkp70WdbK5ra9KEDo,7843
+threetears/datasources/secrets.py,sha256=EwydMcy8O-LoyZjEmdpyCgnHrc_cHKP57qZIuQ8fMak,988
+threetears/datasources/drivers/__init__.py,sha256=twb0YmrzzzCqwj8CuuGIr0uZjiCPieg90Iqq0wWd_dk,1510
+threetears/datasources/drivers/_sync_bridge.py,sha256=EyVQzexWgINt9K9Gn9Ry4k8Rh1WqCcvLlB7wCm7I18A,6581
+threetears/datasources/drivers/_util.py,sha256=TlYtT4lYIwLBK9iq3JHdRjU9XRTuHgzE2NubXdg8CRE,8889
+threetears/datasources/drivers/asyncpg_driver.py,sha256=Ulh0b9ZRACOIJSOQ8I9Iz1B_zJz5gj8qOZukauzA_JQ,31991
+threetears/datasources/drivers/base.py,sha256=PSQ1nU7W6X_xgtuYO-nRQOpbLxZ_QBtDzd7_-k4fGSY,30542
+threetears/datasources/drivers/bigquery_driver.py,sha256=2OizvNMdCjdFuPKF3U4QdQskmsvvtYVdilVGKT1RNOg,12607
+threetears/datasources/drivers/factory.py,sha256=VZ4fkRVmcqzXKbsg3MN6F_6a8WcYmDD_FkQJJyHBLXQ,5658
+threetears/datasources/drivers/redshift_driver.py,sha256=jPan3ACg5KEv4lhelIe2haYMI4Q_5WoObwzYTylS8KE,70224
+threetears/datasources/drivers/snowflake_driver.py,sha256=CIUApElMkSxAZQAN9Huvy6SPdF3ibkyCcKG-JH5G2mo,10944
+3tears_datasources-0.14.0.dist-info/METADATA,sha256=GiLb5zVTlTQlcr7KSizVA6K9I4TUi_80cj87qAbEOzs,4038
+3tears_datasources-0.14.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+3tears_datasources-0.14.0.dist-info/licenses/LICENSE,sha256=7GWEoEOcFJenZLt4LDzqH2K7QLxo_2m8rzG7Vv8VGXo,1066
+3tears_datasources-0.14.0.dist-info/RECORD,,

3tears_datasources-0.14.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

3tears_datasources-0.14.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Pace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+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.

threetears/datasources/__init__.py

@@ -0,0 +1,119 @@
+"""datasource entities, collections, namespace helpers, and agent.yaml config model.
+
+this package is the single source of truth for datasource primitives
+across every 3tears consumer (Hub, agent pods, future products). the
+``Driver`` abstraction + per-backend driver implementations land in
+``threetears.datasources.drivers`` (datasource-task-09 through 12);
+drivers are accessed via the
+:func:`threetears.datasources.drivers.create_driver` factory and are
+NOT re-exported from this top-level ``__all__`` -- the package root
+stays free of backend-library imports (asyncpg, redshift_connector,
+etc.) so a consumer that never uses a given driver doesn't pay the
+import cost.
+
+public surface (per shard DS-07-10):
+
+- entities -- :class:`DataSourceEntity`, :class:`DataSourceTableEntity`,
+  :class:`DataSourceColumnEntity`, :class:`DataSourceRelationEntity`,
+  :class:`TableTemplateEntity` + lifecycle enums (:class:`DataSourceType`,
+  :class:`DataSourceAccessMode`, :class:`DataSourceStatus`)
+- collections -- :class:`DataSourceCollection`,
+  :class:`DataSourceTableCollection`, :class:`DataSourceColumnCollection`,
+  :class:`DataSourceRelationCollection`, :class:`TableTemplateCollection`
+- namespace helpers -- :data:`DATASOURCE_NAMESPACE_TYPE`,
+  :func:`datasource_namespace_id`, :func:`datasource_namespace_name`
+- agent.yaml-facing config -- :class:`DatasourceConfig`
+
+driver implementations live in the ``drivers`` subpackage and are
+imported lazily via the factory:
+
+    from threetears.datasources.drivers import create_driver, Driver
+"""
+
+from __future__ import annotations
+
+# Version is derived from package metadata so pyproject.toml stays the
+# single source of truth -- a release that bumps the version in
+# pyproject without updating ``__init__.py`` can't drift the runtime
+# ``__version__``.
+from importlib.metadata import PackageNotFoundError as _PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("3tears-datasources")
+except _PackageNotFoundError:  # pragma: no cover - dev fallback
+    __version__ = "unknown"
+
+from threetears.datasources.collections import (
+    DataSourceCollection,
+    DataSourceColumnCollection,
+    DataSourceRelationCollection,
+    DataSourceSchemaDigestCollection,
+    DataSourceTableCollection,
+    TableTemplateCollection,
+)
+from threetears.datasources.config import (
+    AgentInternalConnectionConfig,
+    BigQueryConnectionConfig,
+    ConnectionConfig,
+    DatasourceConfig,
+    PostgresConnectionConfig,
+    RedshiftConnectionConfig,
+    SnowflakeConnectionConfig,
+    YugabyteConnectionConfig,
+)
+from threetears.datasources.entities import (
+    DataSourceAccessMode,
+    DataSourceColumnEntity,
+    DataSourceEntity,
+    DataSourceRelationEntity,
+    DataSourceSchemaDigestEntity,
+    DataSourceStatus,
+    DataSourceTableEntity,
+    DataSourceType,
+    TableTemplateEntity,
+)
+from threetears.datasources.introspection import (
+    IntrospectionDiff,
+    compute_column_hash,
+    compute_introspection_diff,
+)
+from threetears.datasources.namespace import (
+    DATASOURCE_NAMESPACE_TYPE,
+    datasource_namespace_id,
+    datasource_namespace_name,
+)
+from threetears.datasources.schema_priming import SchemaPrimingIntegration
+
+__all__ = [
+    "DATASOURCE_NAMESPACE_TYPE",
+    "AgentInternalConnectionConfig",
+    "BigQueryConnectionConfig",
+    "ConnectionConfig",
+    "DataSourceAccessMode",
+    "DataSourceCollection",
+    "DataSourceColumnCollection",
+    "DataSourceColumnEntity",
+    "DataSourceEntity",
+    "DataSourceRelationCollection",
+    "DataSourceRelationEntity",
+    "DataSourceSchemaDigestCollection",
+    "DataSourceSchemaDigestEntity",
+    "DataSourceStatus",
+    "DataSourceTableCollection",
+    "DataSourceTableEntity",
+    "DataSourceType",
+    "DatasourceConfig",
+    "IntrospectionDiff",
+    "PostgresConnectionConfig",
+    "RedshiftConnectionConfig",
+    "SchemaPrimingIntegration",
+    "SnowflakeConnectionConfig",
+    "TableTemplateCollection",
+    "TableTemplateEntity",
+    "YugabyteConnectionConfig",
+    "compute_column_hash",
+    "compute_introspection_diff",
+    "datasource_namespace_id",
+    "datasource_namespace_name",
+]