Metadata-Version: 2.4
Name: appfx-cosmosdb
Version: 0.1.0
Summary: Python helpers for Azure Cosmos DB SQL and MongoDB APIs.
Author-email: DB Lee <dongbum@outlook.com>
License-Expression: MIT
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.11.5
Provides-Extra: sql
Requires-Dist: azure-cosmos>=4.9.0; extra == "sql"
Requires-Dist: azure-identity>=1.22.0; extra == "sql"
Provides-Extra: mongo
Requires-Dist: pymongo>=4.13.2; extra == "mongo"
Provides-Extra: all
Requires-Dist: azure-cosmos>=4.9.0; extra == "all"
Requires-Dist: azure-identity>=1.22.0; extra == "all"
Requires-Dist: pymongo>=4.13.2; extra == "all"
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: mypy>=1.9; extra == "dev"
Requires-Dist: pytest>=8.4; extra == "dev"
Requires-Dist: pytest-asyncio>=1.0; extra == "dev"
Requires-Dist: pytest-cov>=6.2; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: twine>=6.1; extra == "dev"
Dynamic: license-file

# appfx-cosmosdb

`appfx-cosmosdb` provides type-safe, async repository helpers for Azure Cosmos DB
using either the SQL/Core API or the MongoDB API. The package keeps the two API
surfaces explicit so applications import only the implementation they use.

## Package identity

| Purpose | Name |
| --- | --- |
| Distribution | `appfx-cosmosdb` |
| SQL/Core API namespace | `appfx.cosmosdb.sql` |
| MongoDB API namespace | `appfx.cosmosdb.mongo` |

The top-level `appfx.cosmosdb` package is not the public home for repository or
entity classes. Import from `appfx.cosmosdb.sql` or `appfx.cosmosdb.mongo`
directly.

## Installation

Install only the dependencies for the Cosmos DB API you use:

```powershell
python -m pip install "appfx-cosmosdb[sql]"
python -m pip install "appfx-cosmosdb[mongo]"
```

Install both SQL and MongoDB dependencies when one application uses both APIs:

```powershell
python -m pip install "appfx-cosmosdb[all]"
```

For local development:

```powershell
python -m pip install --upgrade pip
python -m pip install -e ".[dev,all]"
```

## SQL/Core API quick start

```python
from appfx.cosmosdb.sql import RepositoryBase, RootEntityBase, SortDirection, SortField


class Customer(RootEntityBase["Customer", str]):
    name: str
    email: str
    is_active: bool = True


class CustomerRepository(RepositoryBase[Customer, str]):
    def __init__(self, connection_string: str, database_name: str):
        super().__init__(
            connection_string=connection_string,
            database_name=database_name,
            container_name="customers",
        )


async with CustomerRepository(connection_string, "app") as repo:
    await repo.add_async(Customer(id="customer-1", name="Ada", email="ada@example.com"))

    active_customers = await repo.find_async(
        {"is_active": True},
        sort_fields=[SortField("name", SortDirection.ASCENDING)],
    )
```

SQL entities automatically include a computed `/_partitionKey` value derived
from the entity id. Use raw SQL methods for projections, aggregations, and other
queries that are clearer in Cosmos DB SQL syntax.

## MongoDB API quick start

```python
from appfx.cosmosdb.mongo import RepositoryBase, RootEntityBase, SortDirection, SortField
from pydantic import Field


class Customer(RootEntityBase["Customer", str]):
    name: str
    email: str
    tags: list[str] = Field(default_factory=list)


class CustomerRepository(RepositoryBase[Customer, str]):
    def __init__(self, connection_string: str, database_name: str):
        super().__init__(
            connection_string=connection_string,
            database_name=database_name,
            collection_name="customers",
        )


async with CustomerRepository(connection_string, "app") as repo:
    await repo.add_async(Customer(id="customer-1", name="Ada", email="ada@example.com"))

    premium_customers = await repo.find_async(
        {"tags": {"$in": ["premium"]}},
        sort_fields=[SortField("name", SortDirection.ASCENDING)],
    )
```

Mongo repositories pass predicate dictionaries through to MongoDB-style query
operators, including array and regular-expression operators supported by the
driver and Cosmos DB MongoDB API.

## Core concepts

- **Entity models** inherit from `RootEntityBase["EntityName", KeyType]` for
  independently stored documents and from `EntityBase` for nested models.
- **Repositories** inherit from the API-specific `RepositoryBase[TEntity, TKey]`
  and centralize CRUD, query, count, pagination, and bulk-delete operations.
- **Sort helpers** are public from both API namespaces:
  `SortField` and `SortDirection`.
- **Resource cleanup** should use `async with repo:` or `await repo.close()`.

## Documentation

- [Documentation index](docs/index.md)
- [API overview](docs/API_REFERENCE.md)
- [SQL/Core API reference](docs/API_REFERENCE_SQL.md)
- [MongoDB API reference](docs/API_REFERENCE_MONGO.md)
- [Hands-on guide](docs/HANDS_ON_GUIDE.md)
- [Standalone examples](examples/README.md)

## Testing

The default test suite is unit-test focused:

```powershell
python -m pytest
```

Live Cosmos DB tests require explicit integration setup, including a Cosmos DB
account, API-specific connection settings, and any required Azure RBAC or
network access. Do not put credentials in source-controlled files.

## Development validation

```powershell
python -m pytest
python -m pytest --cov
python -m ruff check .
python -m ruff format --check .
python -m mypy
python -m build
python -m twine check dist/*
```

## License and provenance

This package is licensed under the MIT License. Portions of the documentation
were adapted from earlier Cosmos DB helper documentation that was also MIT
licensed; obsolete package names, repository URLs, and legacy branding were
removed during the `appfx-cosmosdb` migration.
