sqlalchemy-foundation-kit 0.0.0__py3-none-any.whl

sqlalchemy_foundation_kit-0.0.0.dist-info/METADATA

@@ -0,0 +1,624 @@
+Metadata-Version: 2.4
+Name: sqlalchemy-foundation-kit
+Version: 0.0.0
+Summary: Foundation layer for SQLAlchemy-based services with UoW, session management, and observability
+Project-URL: Repository, https://github.com/bedrock-python/sqlalchemy-foundation-kit
+Project-URL: Documentation, https://bedrock-python.github.io/sqlalchemy-foundation-kit/
+Project-URL: Changelog, https://github.com/bedrock-python/sqlalchemy-foundation-kit/blob/master/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/bedrock-python/sqlalchemy-foundation-kit/issues
+Author-email: Alex Shalaev <shalaevad.alexey@yandex.ru>
+License: Apache License
+        Version 2.0, January 2004
+        http://www.apache.org/licenses/
+        
+        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+        
+        1. Definitions.
+        
+        "License" shall mean the terms and conditions for use, reproduction,
+        and distribution as defined by Sections 1 through 9 of this document.
+        
+        "Licensor" shall mean the copyright owner or entity authorized by
+        the copyright owner that is granting the License.
+        
+        "Legal Entity" shall mean the union of the acting entity and all
+        other entities that control, are controlled by, or are under common
+        control with that entity. For the purposes of this definition,
+        "control" means (i) the power, direct or indirect, to cause the
+        direction or management of such entity, whether by contract or
+        otherwise, or (ii) ownership of fifty percent (50%) or more of the
+        outstanding shares, or (iii) beneficial ownership of such entity.
+        
+        "You" (or "Your") shall mean an individual or Legal Entity
+        exercising permissions granted by this License.
+        
+        "Source" form shall mean the preferred form for making modifications,
+        including but not limited to software source code, documentation
+        source, and configuration files.
+        
+        "Object" form shall mean any form resulting from mechanical
+        transformation or translation of a Source form, including but
+        not limited to compiled object code, generated documentation,
+        and conversions to other media types.
+        
+        "Work" shall mean the work of authorship, whether in Source or
+        Object form, made available under the License, as indicated by a
+        copyright notice that is included in or attached to the work
+        (an example is provided in the Appendix below).
+        
+        "Derivative Works" shall mean any work, whether in Source or Object
+        form, that is based on (or derived from) the Work and for which the
+        editorial revisions, annotations, elaborations, or other modifications
+        represent, as a whole, an original work of authorship. For the purposes
+        of this License, Derivative Works shall not include works that remain
+        separable from, or merely link (or bind by name) to the interfaces of,
+        the Work and Derivative Works thereof.
+        
+        "Contribution" shall mean any work of authorship, including
+        the original version of the Work and any modifications or additions
+        to that Work or Derivative Works thereof, that is intentionally
+        submitted to Licensor for inclusion in the Work by the copyright owner
+        or by an individual or Legal Entity authorized to submit on behalf of
+        the copyright owner. For the purposes of this definition, "submitted"
+        means any form of electronic, verbal, or written communication sent
+        to the Licensor or its representatives, including but not limited to
+        communication on electronic mailing lists, source code control systems,
+        and issue tracking systems that are managed by, or on behalf of, the
+        Licensor for the purpose of discussing and improving the Work, but
+        excluding communication that is conspicuously marked or otherwise
+        designated in writing by the copyright owner as "Not a Contribution."
+        
+        "Contributor" shall mean Licensor and any individual or Legal Entity
+        on behalf of whom a Contribution has been received by Licensor and
+        subsequently incorporated within the Work.
+        
+        2. Grant of Copyright License. Subject to the terms and conditions of
+        this License, each Contributor hereby grants to You a perpetual,
+        worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+        copyright license to reproduce, prepare Derivative Works of,
+        publicly display, publicly perform, sublicense, and distribute the
+        Work and such Derivative Works in Source or Object form.
+        
+        3. Grant of Patent License. Subject to the terms and conditions of
+        this License, each Contributor hereby grants to You a perpetual,
+        worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+        (except as stated in this section) patent license to make, have made,
+        use, offer to sell, sell, import, and otherwise transfer the Work,
+        where such license applies only to those patent claims licensable
+        by such Contributor that are necessarily infringed by their
+        Contribution(s) alone or by combination of their Contribution(s)
+        with the Work to which such Contribution(s) was submitted. If You
+        institute patent litigation against any entity (including a
+        cross-claim or counterclaim in a lawsuit) alleging that the Work
+        or a Contribution incorporated within the Work constitutes direct
+        or contributory patent infringement, then any patent licenses
+        granted to You under this License for that Work shall terminate
+        as of the date such litigation is filed.
+        
+        4. Redistribution. You may reproduce and distribute copies of the
+        Work or Derivative Works thereof in any medium, with or without
+        modifications, and in Source or Object form, provided that You
+        meet the following conditions:
+        
+        (a) You must give any other recipients of the Work or
+        Derivative Works a copy of this License; and
+        
+        (b) You must cause any modified files to carry prominent notices
+        stating that You changed the files; and
+        
+        (c) You must retain, in the Source form of any Derivative Works
+        that You distribute, all copyright, patent, trademark, and
+        attribution notices from the Source form of the Work,
+        excluding those notices that do not pertain to any part of
+        the Derivative Works; and
+        
+        (d) If the Work includes a "NOTICE" text file as part of its
+        distribution, then any Derivative Works that You distribute must
+        include a readable copy of the attribution notices contained
+        within such NOTICE file, excluding those notices that do not
+        pertain to any part of the Derivative Works, in at least one
+        of the following places: within a NOTICE text file distributed
+        as part of the Derivative Works; within the Source form or
+        documentation, if provided along with the Derivative Works; or,
+        within a display generated by the Derivative Works, if and
+        wherever such third-party notices normally appear. The contents
+        of the NOTICE file are for informational purposes only and
+        do not modify the License. You may add Your own attribution
+        notices within Derivative Works that You distribute, alongside
+        or as an addendum to the NOTICE text from the Work, provided
+        that such additional attribution notices cannot be construed
+        as modifying the License.
+        
+        You may add Your own copyright statement to Your modifications and
+        may provide additional or different license terms and conditions
+        for use, reproduction, or distribution of Your modifications, or
+        for any such Derivative Works as a whole, provided Your use,
+        reproduction, and distribution of the Work otherwise complies with
+        the conditions stated in this License.
+        
+        5. Submission of Contributions. Unless You explicitly state otherwise,
+        any Contribution intentionally submitted for inclusion in the Work
+        by You to the Licensor shall be under the terms and conditions of
+        this License, without any additional terms or conditions.
+        Notwithstanding the above, nothing herein shall supersede or modify
+        the terms of any separate license agreement you may have executed
+        with Licensor regarding such Contributions.
+        
+        6. Trademarks. This License does not grant permission to use the trade
+        names, trademarks, service marks, or product names of the Licensor,
+        except as required for reasonable and customary use in describing the
+        origin of the Work and reproducing the content of the NOTICE file.
+        
+        7. Disclaimer of Warranty. Unless required by applicable law or
+        agreed to in writing, Licensor provides the Work (and each
+        Contributor provides its Contributions) on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+        implied, including, without limitation, any warranties or conditions
+        of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+        PARTICULAR PURPOSE. You are solely responsible for determining the
+        appropriateness of using or redistributing the Work and assume any
+        risks associated with Your exercise of permissions under this License.
+        
+        8. Limitation of Liability. In no event and under no legal theory,
+        whether in tort (including negligence), contract, or otherwise,
+        unless required by applicable law (such as deliberate and grossly
+        negligent acts) or agreed to in writing, shall any Contributor be
+        liable to You for damages, including any direct, indirect, special,
+        incidental, or consequential damages of any character arising as a
+        result of this License or out of the use or inability to use the
+        Work (including but not limited to damages for loss of goodwill,
+        work stoppage, computer failure or malfunction, or any and all
+        other commercial damages or losses), even if such Contributor
+        has been advised of the possibility of such damages.
+        
+        9. Accepting Warranty or Additional Liability. While redistributing
+        the Work or Derivative Works thereof, You may choose to offer,
+        and charge a fee for, acceptance of support, warranty, indemnity,
+        or other liability obligations and/or rights consistent with this
+        License. However, in accepting such obligations, You may act only
+        on Your own behalf and on Your sole responsibility, not on behalf
+        of any other Contributor, and only if You agree to indemnify,
+        defend, and hold each Contributor harmless for any liability
+        incurred by, or claims asserted against, such Contributor by reason
+        of your accepting any such warranty or additional liability.
+        
+        END OF TERMS AND CONDITIONS
+        
+        APPENDIX: How to apply the Apache License to your work.
+        
+        To apply the Apache License to your work, attach the following
+        boilerplate notice, with the fields enclosed by brackets "[]"
+        replaced with your own identifying information. (Don't include
+        the brackets!) The text should be enclosed in the appropriate
+        comment syntax for the file format. We also recommend that a
+        file or class name and description of purpose be included on the
+        same "printed page" as the copyright notice for easier
+        identification within third-party archives.
+        
+        Copyright 2026 Alex Shalaev
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+        http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+License-File: LICENSE
+Keywords: foundation,microservices,observability,opentelemetry,postgres,postgresql,sqlalchemy,tracing,unit-of-work,uow
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic<3.0.0,>=2.5.0
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0.35
+Provides-Extra: all
+Requires-Dist: dependency-injector<5.0.0,>=4.41.0; extra == 'all'
+Requires-Dist: dishka<2.0.0,>=1.3.0; extra == 'all'
+Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-asyncpg<1.0.0,>=0.41b0; extra == 'all'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy<1.0.0,>=0.41b0; extra == 'all'
+Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == 'all'
+Requires-Dist: orjson<4.0.0,>=3.9.0; extra == 'all'
+Requires-Dist: prometheus-client<1.0.0,>=0.19.0; extra == 'all'
+Requires-Dist: pydantic-settings<3.0.0,>=2.3.0; extra == 'all'
+Provides-Extra: dependency-injector
+Requires-Dist: dependency-injector<5.0.0,>=4.41.0; extra == 'dependency-injector'
+Provides-Extra: dishka
+Requires-Dist: dishka<2.0.0,>=1.3.0; extra == 'dishka'
+Provides-Extra: metrics
+Requires-Dist: prometheus-client<1.0.0,>=0.19.0; extra == 'metrics'
+Provides-Extra: orjson
+Requires-Dist: orjson<4.0.0,>=3.9.0; extra == 'orjson'
+Provides-Extra: settings
+Requires-Dist: pydantic-settings<3.0.0,>=2.3.0; extra == 'settings'
+Provides-Extra: telemetry
+Requires-Dist: opentelemetry-api<2.0.0,>=1.20.0; extra == 'telemetry'
+Requires-Dist: opentelemetry-instrumentation-asyncpg<1.0.0,>=0.41b0; extra == 'telemetry'
+Requires-Dist: opentelemetry-instrumentation-sqlalchemy<1.0.0,>=0.41b0; extra == 'telemetry'
+Requires-Dist: opentelemetry-sdk<2.0.0,>=1.20.0; extra == 'telemetry'
+Description-Content-Type: text/markdown
+
+# sqlalchemy-foundation-kit
+
+<div align="center">
+
+[![PyPI - Version](https://img.shields.io/pypi/v/sqlalchemy-foundation-kit?style=flat-square&logo=pypi&logoColor=white)](https://pypi.org/project/sqlalchemy-foundation-kit/)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/sqlalchemy-foundation-kit?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/sqlalchemy-foundation-kit/)
+[![License](https://img.shields.io/github/license/bedrock-python/sqlalchemy-foundation-kit?style=flat-square)](https://github.com/bedrock-python/sqlalchemy-foundation-kit/blob/master/LICENSE)
+
+[![CI](https://img.shields.io/github/actions/workflow/status/bedrock-python/sqlalchemy-foundation-kit/ci.yml?branch=master&style=flat-square&logo=github&label=CI)](https://github.com/bedrock-python/sqlalchemy-foundation-kit/actions/workflows/ci.yml)
+[![codecov](https://img.shields.io/codecov/c/github/bedrock-python/sqlalchemy-foundation-kit?style=flat-square&logo=codecov&logoColor=white)](https://codecov.io/gh/bedrock-python/sqlalchemy-foundation-kit)
+[![Documentation](https://img.shields.io/badge/docs-github_pages-blue?style=flat-square&logo=materialformkdocs&logoColor=white)](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
+
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json&style=flat-square)](https://github.com/astral-sh/ruff)
+[![Type checked: mypy](https://img.shields.io/badge/type_checker-mypy-blue?style=flat-square&logo=python)](http://mypy-lang.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json&style=flat-square)](https://github.com/astral-sh/uv)
+
+</div>
+
+---
+
+**Production-ready foundation for SQLAlchemy-based async services with Unit of Work, session management, and observability**
+
+`sqlalchemy-foundation-kit` is a standalone, batteries-included foundation for building async SQLAlchemy microservices. It bundles everything you commonly re-implement for every service into a single library:
+
+- **PostgreSQL configuration** — Pydantic-based settings with grouped connection / pool / query options
+- **Session management** — `AsyncSessionManager` with pgbouncer transaction-mode compatibility
+- **Unit of Work pattern** — `AsyncSQLAlchemyUnitOfWork` with automatic commit/rollback
+- **Base ORM models** — Pre-configured `Base`, mixins, custom types (`PydanticJSONB`, `UnConstrainedEnum`)
+- **Observability** — Prometheus connection-pool metrics and OpenTelemetry tracing
+- **DI integration** — Ready-to-use providers for [`dishka`](https://github.com/reagento/dishka) and `dependency-injector`
+
+Only `sqlalchemy[asyncio]` and `pydantic` are required by default — everything else is an opt-in extra.
+
+## Key Features
+
+✅ **Single dependency** — All foundation pieces in one place  
+✅ **Unit of Work pattern** — Transactional consistency with automatic commit/rollback  
+✅ **Connection pool management** — `AsyncSessionManager` with metrics and health checks  
+✅ **pgbouncer compatible** — Custom connection class for transaction mode  
+✅ **Observability built-in** — Prometheus metrics + OpenTelemetry tracing  
+✅ **Type-safe configuration** — Pydantic settings with validation  
+✅ **Base ORM models** — Pre-configured `Base` with naming conventions and mixins  
+
+## Installation
+
+```bash
+# Basic installation (core functionality)
+pip install sqlalchemy-foundation-kit
+
+# With pydantic-settings support
+pip install sqlalchemy-foundation-kit[settings]
+
+# With Prometheus metrics
+pip install sqlalchemy-foundation-kit[metrics]
+
+# With OpenTelemetry tracing
+pip install sqlalchemy-foundation-kit[telemetry]
+
+# With dishka dependency injection
+pip install sqlalchemy-foundation-kit[dishka]
+
+# With dependency-injector containers
+pip install sqlalchemy-foundation-kit[dependency-injector]
+
+# With orjson serialization
+pip install sqlalchemy-foundation-kit[orjson]
+
+# All features
+pip install sqlalchemy-foundation-kit[all]
+```
+
+## Quick Start
+
+### 1. Configuration (with pydantic-settings)
+
+```python
+from pydantic import SecretStr
+from pydantic_settings import BaseSettings
+from sqlalchemy_foundation_kit.contrib.settings import (
+    BasePostgresConfig,
+    ConnectionSettings,
+    PoolSettings,
+    QuerySettings,
+)
+
+class Settings(BaseSettings):
+    postgres: BasePostgresConfig = BasePostgresConfig(
+        connection=ConnectionSettings(
+            host="localhost",
+            port=5432,
+            user="postgres",
+            password=SecretStr("secret"),
+            database="mydb",
+        ),
+        pool=PoolSettings(),  # Uses defaults
+        query=QuerySettings(),  # Uses defaults
+        application_name="my-service",
+    )
+```
+
+Or implement `PostgresSettingsProtocol` directly:
+
+```python
+from dataclasses import dataclass
+from sqlalchemy_foundation_kit import (
+    PostgresSettingsProtocol,
+    ConnectionSettingsProtocol,
+    PoolSettingsProtocol,
+    QuerySettingsProtocol,
+)
+
+@dataclass
+class MyConnectionSettings:
+    host: str = "localhost"
+    port: int = 5432
+    user: str = "postgres"
+    database: str = "mydb"
+
+@dataclass
+class MyPoolSettings:
+    kind: str = "async_adapted_queue"
+    size: int | None = 10
+    max_overflow: int | None = 20
+    pre_ping: bool = True
+    recycle: int | None = 3600
+    timeout: float | None = 30.0
+
+@dataclass
+class MyQuerySettings:
+    echo: bool = False
+    statement_cache_size: int | None = 0
+    prepared_statement_cache_size: int | None = 0
+    isolation_level: str | None = None
+
+class PostgresConfig:
+    connection: ConnectionSettingsProtocol = MyConnectionSettings()
+    pool: PoolSettingsProtocol = MyPoolSettings()
+    query: QuerySettingsProtocol = MyQuerySettings()
+    application_name: str = "my-service"
+    db_schema: str | None = None
+    use_orjson_serialization: bool = True
+    jit: str | None = "off"
+    
+    def to_dsn(self) -> str:
+        return f"postgresql+asyncpg://{self.connection.user}@{self.connection.host}:{self.connection.port}/{self.connection.database}"
+```
+
+### 2. Define ORM Models
+
+```python
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy_foundation_kit import BaseTable, DatetimeColumnsMixin
+
+class UserDB(BaseTable, DatetimeColumnsMixin):
+    __tablename__ = "users"
+    __created_at_index__ = True  # Index on created_at
+
+    id: Mapped[UUID] = mapped_column(primary_key=True)
+    email: Mapped[str] = mapped_column(unique=True)
+    username: Mapped[str]
+```
+
+### 3. Create Session Manager
+
+```python
+from sqlalchemy_foundation_kit import create_async_session_manager
+
+async def main():
+    session_manager = create_async_session_manager(
+        settings.postgres,
+        metrics=postgres_metrics,  # optional
+    )
+    
+    async with session_manager.get_transaction() as session:
+        user = UserDB(id=uuid4(), email="user@example.com", username="user")
+        session.add(user)
+        # Auto-commit on exit
+```
+
+### 4. Unit of Work Pattern
+
+```python
+from unit_of_work_kit import AsyncSQLAlchemyUnitOfWork, AsyncSQLAlchemyUowTransaction
+
+# Define your transaction with repositories
+class MyTransaction(AsyncSQLAlchemyUowTransaction):
+    @property
+    def users(self) -> UserRepository:
+        if self._users is None:
+            self._users = PostgresUserRepository(self.session)
+        return self._users
+
+# Create UoW
+class MyUnitOfWork(AsyncSQLAlchemyUnitOfWork[MyTransaction]):
+    def __init__(self, session_maker):
+        super().__init__(session_maker, transaction_factory=MyTransaction)
+
+# Usage in use case
+class CreateUserUseCase:
+    def __init__(self, uow: MyUnitOfWork):
+        self._uow = uow
+    
+    async def execute(self, email: str) -> User:
+        async with self._uow.transaction() as tx:
+            user = await tx.users.create(email=email)
+            await tx.outbox.create(UserCreatedEvent(...))
+        return user
+```
+
+## What's Included
+
+### Core (always available)
+- **Session Management**: `AsyncSessionManager`, `AsyncCConnection`
+- **Base ORM**: `Base`, `BaseTable`, `DatetimeColumnsMixin`, `UnConstrainedEnum`, `PydanticJSONB`
+- **Unit of Work**: `AsyncUnitOfWork`, `AsyncSQLAlchemyUnitOfWork`, `IsolationLevel`
+- **Protocols**: `PostgresSettingsProtocol`, `PostgresMetricsProtocol`
+- **Utilities**: `build_engine_kwargs`, `resolve_pool_class`, `load_orm_metadata`
+
+### Contrib (optional dependencies)
+
+#### `contrib.settings` (requires `[settings]`)
+```python
+from sqlalchemy_foundation_kit.contrib.settings import (
+    BasePostgresConfig,
+    BasePostgresMigrationsConfig,
+)
+```
+- `BasePostgresConfig` — Pydantic-based PostgreSQL configuration
+- `BasePostgresMigrationsConfig` — Migrations configuration
+
+#### `contrib.metrics` (requires `[metrics]`)
+```python
+from sqlalchemy_foundation_kit.contrib.metrics import PostgresMetrics
+```
+- `PostgresMetrics` — Prometheus metrics for connection pool
+- Tracks: pool size, checked out connections, checkout duration, errors
+
+#### `contrib.di` (requires `[dishka]`)
+```python
+from sqlalchemy_foundation_kit.contrib.di import (
+    AsyncDatabaseProvider,
+    AsyncUnitOfWorkProvider,
+    PrometheusPostgresMetricsProvider,
+)
+```
+- `AsyncDatabaseProvider` — Provides `AsyncSessionManager` and `async_sessionmaker`
+- `AsyncUnitOfWorkProvider` — Provides `AsyncUnitOfWork`
+- `PrometheusPostgresMetricsProvider` — Provides Prometheus metrics integration
+
+**Example with Dishka:**
+```python
+from dishka import make_async_container
+from sqlalchemy_foundation_kit.contrib.di import (
+    AsyncDatabaseProvider,
+    AsyncUnitOfWorkProvider,
+    PrometheusPostgresMetricsProvider,
+)
+
+container = make_async_container(
+    AsyncDatabaseProvider(),
+    AsyncUnitOfWorkProvider(),
+    PrometheusPostgresMetricsProvider(),
+    # ... your providers
+)
+```
+
+#### `contrib.dependency_injector` (requires `[dependency-injector]`)
+```python
+from sqlalchemy_foundation_kit.contrib.dependency_injector import (
+    DatabaseContainer,
+    AsyncDatabaseResourceProvider,
+    PrometheusMetricsContainer,
+)
+```
+- `DatabaseContainer` — Container providing `session_manager`, `session_maker`, and `uow`
+- `AsyncDatabaseResourceProvider` — Manual lifecycle management helper
+- `PrometheusMetricsContainer` — Container for Prometheus metrics integration
+
+**Example with dependency-injector:**
+```python
+from dependency_injector import containers, providers
+from sqlalchemy_foundation_kit.contrib.dependency_injector import (
+    DatabaseContainer,
+    PrometheusMetricsContainer,
+)
+
+class AppContainer(containers.DeclarativeContainer):
+    config = providers.Singleton(Settings)
+    
+    metrics = providers.Container(
+        PrometheusMetricsContainer,
+        metrics_settings=config.provided.metrics,
+        default_prefix=providers.Object("myapp"),
+        postgres_settings=config.provided.postgres,
+    )
+    
+    database = providers.Container(
+        DatabaseContainer,
+        postgres_config=config.provided.postgres,
+        metrics=metrics.postgres_metrics,
+    )
+
+container = AppContainer()
+await container.init_resources()
+
+# Use dependencies
+uow = container.database.uow()
+async with uow.transaction() as tx:
+    user = await tx.users.create(...)
+```
+
+#### `contrib.telemetry` (requires `[telemetry]`)
+```python
+from sqlalchemy_foundation_kit.contrib.telemetry import (
+    instrument_sqlalchemy,
+    instrument_asyncpg,
+    TracedAsyncUnitOfWork,
+)
+```
+- `instrument_sqlalchemy()` — OpenTelemetry instrumentation for SQLAlchemy
+- `instrument_asyncpg()` — OpenTelemetry instrumentation for asyncpg
+- `TracedAsyncUnitOfWork` — UoW with automatic span creation
+
+**Example with OpenTelemetry:**
+```python
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import ConsoleSpanExporter, BatchSpanProcessor
+
+# Setup tracer
+provider = TracerProvider()
+processor = BatchSpanProcessor(ConsoleSpanExporter())
+provider.add_span_processor(processor)
+trace.set_tracer_provider(provider)
+
+# Instrument SQLAlchemy
+from sqlalchemy_foundation_kit.contrib.telemetry import (
+    instrument_sqlalchemy,
+    TracedAsyncUnitOfWork,
+)
+
+instrument_sqlalchemy(engine=engine)
+
+# Use traced UoW
+uow = TracedAsyncUnitOfWork(
+    session_maker=session_maker,
+    transaction_factory=MyTransaction,
+    service_name="my-service",
+)
+
+async with uow.transaction() as tx:
+    # Automatically creates span "uow.transaction"
+    user = await tx.users.create(...)
+```
+
+## Architecture
+
+```mermaid
+graph LR
+    A[Your Service] --> B[sqlalchemy-foundation-kit]
+    B --> C[SQLAlchemy asyncio]
+    B --> D[Pydantic]
+    B -.optional.-> E[Prometheus]
+    B -.optional.-> F[OpenTelemetry]
+    B -.optional.-> G[dishka / dependency-injector]
+```
+
+## Documentation
+
+Full documentation is available at [https://bedrock-python.github.io/sqlalchemy-foundation-kit/](https://bedrock-python.github.io/sqlalchemy-foundation-kit/)
+
+## License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

sqlalchemy_foundation_kit-0.0.0.dist-info/RECORD

@@ -0,0 +1,49 @@
+sqlalchemy_foundation_kit/__init__.py,sha256=xtcURKDp2xFv-I_5YuynsV5Gq2hvGgWxw6iPyaqbH5I,2914
+sqlalchemy_foundation_kit/__version__.py,sha256=ShXQBVjyiSOHxoQJS2BvNG395W4KZfqMxZWBAR0MZrE,22
+sqlalchemy_foundation_kit/_typing.py,sha256=YCdPX-UBlReYnRC1QHmyUsSnIiYURiYFjESkp6YyOJI,740
+sqlalchemy_foundation_kit/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlalchemy_foundation_kit/base/__init__.py,sha256=nGXKR1miz-AonBihfAkIXWjBmykOQlbrPctdv3z5Td4,1257
+sqlalchemy_foundation_kit/base/_optional.py,sha256=kjBfLP1KT416ldQMrfMCVS5o3b2wjOvdqWkBXTQ7vgg,1120
+sqlalchemy_foundation_kit/base/engine.py,sha256=tFXDwIuD1JYVfy60_eUUCMC_OT1RgIiKRksYFlSasSU,8030
+sqlalchemy_foundation_kit/base/metadata.py,sha256=VVHMGRBqhwP2gkcDNW_KhTkY5WDYmUl-b5LazevFp0Y,1949
+sqlalchemy_foundation_kit/base/models.py,sha256=-U8awfKRVdm8_nZ7JLC-A5PSu5CZtqd0umzs0D1mETs,3071
+sqlalchemy_foundation_kit/base/serialization.py,sha256=SFWQRJtfCiWfkcZMu8Ory77_vBRMGYnxwQ7ES_NGvCc,2640
+sqlalchemy_foundation_kit/base/types.py,sha256=2DbcIskR2PQlek_oG3wJB24fY9ME0Vs2hJue5CMPkF8,2398
+sqlalchemy_foundation_kit/config/__init__.py,sha256=fbdChslutQVSHHqA2D-7u6Hudse0zNXF00ue8LAb2yA,353
+sqlalchemy_foundation_kit/config/postgres.py,sha256=rpxcOO8FBKxA1WghVfbgRWeOV-L5LWmgKEcHT5cYPGE,5741
+sqlalchemy_foundation_kit/contrib/__init__.py,sha256=t4Ua_wMb9GlYGu3MtcNDRF-vIedweXsxEwjUrlLTpPU,124
+sqlalchemy_foundation_kit/contrib/_metrics_utils.py,sha256=dXXUjaNPZ3Rdmf6Xi1-O75CLoTyFbXe1YvTtivyQTGo,657
+sqlalchemy_foundation_kit/contrib/dependency_injector/__init__.py,sha256=Ctd0Oyo1LwKmltUDRZzrm1AiJ3AeGK8oBl1PbvSt4FM,635
+sqlalchemy_foundation_kit/contrib/dependency_injector/_base.py,sha256=kDcu007F1OtCMHGtOLJnbdNZ-77_VcQbYyJwHgiTo-8,1047
+sqlalchemy_foundation_kit/contrib/dependency_injector/_deps.py,sha256=lCzWEqGj5L6n6ZtKx51FWo4C2F3Mw5B6GZqgmXGrA4g,1011
+sqlalchemy_foundation_kit/contrib/dependency_injector/database.py,sha256=io3iOIGF-vM-TwfEo3Qc3Vfvx_u8Yc6ZYarepoCBdTc,6796
+sqlalchemy_foundation_kit/contrib/dependency_injector/metrics.py,sha256=vwA5bdYPiqFoZVVIaICLh6yPugNOwJtueSaY7t04mQk,2890
+sqlalchemy_foundation_kit/contrib/di/__init__.py,sha256=SAIWxHDw2oS6-UxBhBCuqiSm3ElKlFcXvnAGVZn9meM,493
+sqlalchemy_foundation_kit/contrib/di/_base.py,sha256=SezOBBH-5Br-MRxkqnIJod0NFGtvslAAcdUCnbzBum0,809
+sqlalchemy_foundation_kit/contrib/di/_deps.py,sha256=K6Ln3gxaqEH24OpHZ-e3VMLcV6qT4nEkgiv-17SMKDQ,872
+sqlalchemy_foundation_kit/contrib/di/database.py,sha256=_3-XZ2wWdWL3lk_VMakqYTN5frylfES8E9D1k73jZQ8,5936
+sqlalchemy_foundation_kit/contrib/di/metrics.py,sha256=s8fbF1fgteJOj0e-New-5PM1OoYrhUYFska7FemNCoA,2029
+sqlalchemy_foundation_kit/contrib/metrics/__init__.py,sha256=Vt_Rf1JTwQOqxeer5UsKJmAiJzkGgC2kI2G6u_FVvlo,144
+sqlalchemy_foundation_kit/contrib/metrics/postgres.py,sha256=9ahHRqxN3DKOejxPGTWUFxommTZ_AHimZEX1LWYgJMs,4636
+sqlalchemy_foundation_kit/contrib/settings/__init__.py,sha256=oqycBh88yICRu4Qmis0o48_mpYlulnXpVTQpZFQb2og,363
+sqlalchemy_foundation_kit/contrib/settings/postgres.py,sha256=JgRuiKAdKCR3Uwqovxbl612ak4gWcHlbv0QNRGrR420,7225
+sqlalchemy_foundation_kit/contrib/telemetry/__init__.py,sha256=-DZqccnNgJDx_8yr-4J0x4JV2_wCIwjvB9kGFjet6ks,349
+sqlalchemy_foundation_kit/contrib/telemetry/instrumentations.py,sha256=s7-J3iozoYLkz32Vq_LaAkaNKUvjcZa9aQEgoVLINBY,3483
+sqlalchemy_foundation_kit/contrib/telemetry/uow.py,sha256=L45693SRt1tfl3JVcDoc3pKLSSm2Etbze4D-ClpekcE,7532
+sqlalchemy_foundation_kit/protocols/__init__.py,sha256=tzPF_J0-sE1_xDbypoH3fUbsUlr2gD0N79hHCAlBTBM,475
+sqlalchemy_foundation_kit/protocols/metrics.py,sha256=VuyvHdvgk4gDqCEpqWHN9jsNuv-LPygZ5eBaXu7zkuI,2505
+sqlalchemy_foundation_kit/session/__init__.py,sha256=3UYIjcNLk0yYqaoOzcATPueb8Oxw9W4O0vGjaHusT74,701
+sqlalchemy_foundation_kit/session/builder.py,sha256=-furDMJZMizNREhM9I80nD-rT0DXys0XEarwGVDIQgA,9402
+sqlalchemy_foundation_kit/session/connection.py,sha256=y1nx7MOG8DeWW1s37cFWvs39Tm1lyAgjt6MN0JBpZzQ,913
+sqlalchemy_foundation_kit/session/factories.py,sha256=h-yKru8N2HJLjPEdj4gRzPWc9ID6qwC3SPBMYHBddnM,4487
+sqlalchemy_foundation_kit/session/locks.py,sha256=8ciOLHWnjlaCiG_KAIAtlvzKl3w0zn3hbCgmmuQ7RXI,2178
+sqlalchemy_foundation_kit/session/manager.py,sha256=3wx9AByzFo1zs2lwC0AtFMD3BH5WD3EwvH5i-bfZzVI,9576
+sqlalchemy_foundation_kit/session/retry.py,sha256=d_JJNt-2xWzpkBZhfIiya18j6ZJCb_rMXOFcIsVXFy0,2504
+sqlalchemy_foundation_kit/uow/__init__.py,sha256=TZuySWNtPcQIBFWxp3GCgAAQ7nE38IxF6dECzCcoj2o,539
+sqlalchemy_foundation_kit/uow/enums.py,sha256=zqjo_lDK-qORptX6baigCIyj8RdW74NrVT8Uqv0CjIg,463
+sqlalchemy_foundation_kit/uow/protocols.py,sha256=eO3Cb7LCkcFP4-6sq8PDyeY6R5Pz0rnrJSPwFG1CosE,3138
+sqlalchemy_foundation_kit/uow/sqlalchemy.py,sha256=fqu80OzJVVhrguNHDq1LOo2icSe-lN4o0HyxotHvG94,16068
+sqlalchemy_foundation_kit-0.0.0.dist-info/METADATA,sha256=lPSIBB4vamJId63Lim6xBHyMPsi9rk2SDl6D8LzHbOg,27598
+sqlalchemy_foundation_kit-0.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sqlalchemy_foundation_kit-0.0.0.dist-info/licenses/LICENSE,sha256=HqasrACfRh7mgdbiXMVrs_X8dOCZed1b8KXY7i6Ch14,10239
+sqlalchemy_foundation_kit-0.0.0.dist-info/RECORD,,

sqlalchemy_foundation_kit-0.0.0.dist-info/WHEEL

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