Metadata-Version: 2.4
Name: 3tears-datasources
Version: 0.14.1
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.
