ddaerospike 0.0.1__tar.gz

ddaerospike-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Davydov
+
+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.

ddaerospike-0.0.1/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: ddaerospike
+Version: 0.0.1
+Summary: Aerospike helpers: typed records, filters and a set manager on top of aerospike-native
+Keywords: python,aerospike,aerospike-native,ddaerospike
+Author: davyddd
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: aerospike-native>=1.0,<2
+Requires-Dist: dddesign>=2.1.1,<3
+Requires-Dist: ddutils>=0.3.2,<0.4.0
+Requires-Dist: pydantic>=2.10,<3
+Requires-Python: >=3.11, <3.15
+Project-URL: Repository, https://github.com/davyddd/ddaerospike
+Description-Content-Type: text/markdown
+
+# ddaerospike
+
+[![pypi](https://img.shields.io/pypi/v/ddaerospike.svg)](https://pypi.python.org/pypi/ddaerospike)
+[![downloads](https://static.pepy.tech/badge/ddaerospike/month)](https://pepy.tech/project/ddaerospike)
+[![versions](https://img.shields.io/pypi/pyversions/ddaerospike.svg)](https://github.com/davyddd/ddaerospike)
+[![codecov](https://codecov.io/gh/davyddd/ddaerospike/branch/main/graph/badge.svg)](https://app.codecov.io/github/davyddd/ddaerospike)
+[![license](https://img.shields.io/github/license/davyddd/ddaerospike.svg)](https://github.com/davyddd/ddaerospike/blob/main/LICENSE)
+
+Aerospike helpers: typed records, filters and a set manager on top of aerospike-native
+
+## Installation
+
+Install the library using pip:
+```bash
+pip install ddaerospike
+```
+
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `copier update` to pull in template updates.
+
+## AerospikeDsn
+
+A settings field for a cluster: `aerospike://host[:port][,host[:port]]/<namespace>`, validated as a URL like
+pydantic's `PostgresDsn`. The hosts are the seeds the client learns the rest of the cluster from (a missing port
+is 3000), the path names the namespace and is required.
+
+```python
+from pydantic_settings import BaseSettings
+
+from ddaerospike.dsn import AerospikeDsn
+
+
+class Settings(BaseSettings):
+    AEROSPIKE_URL: AerospikeDsn  # AEROSPIKE_URL=aerospike://aerospike-0,aerospike-1/application
+
+
+settings = Settings()
+settings.AEROSPIKE_URL.seeds      # 'aerospike-0:3000,aerospike-1:3000', what `new_client` takes
+settings.AEROSPIKE_URL.namespace  # 'application'
+```
+
+## AerospikeData
+
+A record of a set, every field a bin. Scalars and plain containers are simple bins; a `BaseModel` / `RootModel`
+field is a composite bin stored as a map or list. Datetimes are declared as `AerospikeTimestamp`: stored as integer
+microseconds since the epoch (UTC), read back as an aware datetime, and compared the same way by the filters; a
+bare `datetime` or `date` field is rejected at class definition, as is a bin name over 15 characters. Subclasses
+map to and from the domain through `to_entity` / `from_entity`.
+
+```python
+from pydantic import BaseModel
+
+from ddaerospike.data import AerospikeData, AerospikeTimestamp
+
+
+class Address(BaseModel):
+    city: str
+    zip_code: str | None = None
+
+
+class ProfileData(AerospikeData[Profile]):
+    name: str
+    age: int | None = None
+    created_at: AerospikeTimestamp
+    address: Address | None = None  # a composite bin
+
+    def to_entity(self, **kwargs) -> Profile:
+        return Profile(name=self.name, age=self.age, created_at=self.created_at)
+
+    @classmethod
+    def from_entity(cls, entity: Profile) -> 'ProfileData':
+        return cls(name=entity.name, age=entity.age, created_at=entity.created_at)
+```
+
+## AerospikeManager
+
+ORM-like access to one set, typed by its `AerospikeData` model: `get`, `get_map`, `get_list`, `find_one`, `put`
+and `delete`. It is a Django-style manager, not a dddesign repository: a context repository owns one and maps
+records to entities. The client is obtained for every call from `client_factory`, a `ConnectionManagerFactory`
+from [ddutils](https://github.com/davyddd/ddutils) called with `alias`, the way a
+[ddsql](https://github.com/davyddd/ddsql) adapter runs a query inside `factory(alias=...)`: the factory owns which
+cluster the alias means, the scope the client lives in (one per process and event loop, the client completes its
+futures on the loop it was created in), its lazy creation and its close on shutdown.
+
+```python
+import asyncio
+import os
+from enum import Enum
+from functools import partial
+
+from aerospike_native import Client, ClientPolicy, new_client
+from ddutils.connections import ConnectionManagerFactory
+from ddutils.scoped_registry import ScopedRegistry
+
+from ddaerospike.manager import AerospikeManager
+
+
+class AerospikeConnectionAlias(str, Enum):
+    PRIMARY = 'primary'
+
+
+async def create_client() -> Client:
+    policy = ClientPolicy()
+    policy.timeout = 5_000
+    return await new_client(policy, settings.AEROSPIKE_URL.seeds)
+
+
+def client_scope() -> tuple[int, asyncio.AbstractEventLoop]:
+    return os.getpid(), asyncio.get_running_loop()
+
+
+client_registries = {
+    AerospikeConnectionAlias.PRIMARY: ScopedRegistry[Client](
+        create_func=create_client, scope_func=client_scope, destructor_method_name='close'
+    ),
+}
+aerospike_client_factory = ConnectionManagerFactory(client_registries, default=AerospikeConnectionAlias.PRIMARY)
+
+
+class ProfileManager(AerospikeManager[ProfileData]):
+    client_factory = aerospike_client_factory
+    namespace = settings.AEROSPIKE_URL.namespace
+    set_name = 'profile'
+    ttl_seconds = 30 * 24 * 60 * 60  # set by every write; None leaves the record's TTL alone
+
+
+profile_manager = ProfileManager()
+
+await profile_manager.put(profile.id, ProfileData.from_entity(profile))
+data = await profile_manager.get(profile.id)                       # ProfileData | None
+await profile_manager.get_map([1, 2, 3])                           # {'1': ProfileData, ...}
+await profile_manager.put(profile.id, data, if_absent=True)        # False when the record exists
+await profile_manager.delete(profile.id)
+
+await aerospike_client_factory.close()                             # on shutdown
+```
+
+A bin set to `None` is removed from the record by the write; inside a composite bin the `None` values are left
+out. The `read_policy_fields`, `batch_policy_fields`, `query_policy_fields` and `write_policy_fields` class
+attributes (typed dicts from `ddaerospike.policies`) override the defaults: short timeouts, retries on reads only,
+`send_key` on writes so queries can return the primary key.
+
+## Filters
+
+`AerospikeFilterCollection(Model)` holds the conditions of one query on a set, bound to its record model: at most
+one secondary-index filter (a query runs on one index: equality on `int` / `str`, a range on `int`) and any number
+of filter expressions, ANDed and evaluated on every record the index or the whole set yields. `add_filter` checks
+the bin against the model and the value against the bin's scalar (an `int` widens to a `float` bin); values are
+normalized the way the server compares them (enums to their value, UUIDs to strings, datetimes to
+`AerospikeTimestamp` microseconds, `Decimal` to float), and every operator checks the type it accepts. A composite
+bin only takes `is_null` / `is_not_null`, which take no value.
+
+```python
+from ddaerospike.filters import AerospikeFilterCollection, AerospikeFilterOperator
+
+filters = (
+    AerospikeFilterCollection(ProfileData)
+    .add_filter('name', AerospikeFilterOperator.EQUAL, 'john', use_index=True)   # needs an index on `name`
+    .add_filter('age', AerospikeFilterOperator.BETWEEN, [18, 65])
+    .add_filter('address', AerospikeFilterOperator.IS_NOT_NULL)
+)
+
+items = await profile_manager.get_list(filters, limit=100)   # [AerospikeDataWithPK(pk='1', data=ProfileData(...)), ...]
+first = await profile_manager.find_one(filters)
+```
+
+## AerospikeFeatureFlagStorage
+
+The Aerospike backend of [ddutils](https://github.com/davyddd/ddutils) feature flags: one set, a flag per record
+(`FeatureFlagData`: `enabled`, `proportion`, `payload` bins, the flag name is the primary key), through an
+`AerospikeManager[FeatureFlagData]` the application wires. Client and server errors raise
+`FeatureFlagStorageError`, so `FeatureFlags` keeps serving the last known values; a record that does not validate
+is read as the defaults.
+
+```python
+from ddaerospike.feature_flags import AerospikeFeatureFlagStorage, FeatureFlagData
+from ddaerospike.manager import AerospikeManager
+from ddutils.feature_flags import FeatureFlags
+
+
+class FeatureFlagManager(AerospikeManager[FeatureFlagData]):
+    client_factory = aerospike_client_factory
+    namespace = settings.AEROSPIKE_URL.namespace
+    set_name = 'feature_flag'
+
+
+feature_flags = FeatureFlags(AerospikeFeatureFlagStorage(FeatureFlagManager()))
+
+if await feature_flags.is_enabled('new_checkout'):            # proportion 1.0: on or off for everyone
+    ...
+if await feature_flags.is_enabled('new_ranking', user_id):  # on for `proportion` of the users
+    ...
+```

ddaerospike-0.0.1/README.md

@@ -0,0 +1,205 @@
+# ddaerospike
+
+[![pypi](https://img.shields.io/pypi/v/ddaerospike.svg)](https://pypi.python.org/pypi/ddaerospike)
+[![downloads](https://static.pepy.tech/badge/ddaerospike/month)](https://pepy.tech/project/ddaerospike)
+[![versions](https://img.shields.io/pypi/pyversions/ddaerospike.svg)](https://github.com/davyddd/ddaerospike)
+[![codecov](https://codecov.io/gh/davyddd/ddaerospike/branch/main/graph/badge.svg)](https://app.codecov.io/github/davyddd/ddaerospike)
+[![license](https://img.shields.io/github/license/davyddd/ddaerospike.svg)](https://github.com/davyddd/ddaerospike/blob/main/LICENSE)
+
+Aerospike helpers: typed records, filters and a set manager on top of aerospike-native
+
+## Installation
+
+Install the library using pip:
+```bash
+pip install ddaerospike
+```
+
+## Development
+
+The project runs entirely in Docker. Requires Docker and [Fabric](https://www.fabfile.org/) on the host:
+
+```bash
+fab build      # build the dev image
+fab tests      # run pytest
+fab linters    # run ruff (with --fix), ty and complexipy
+fab shell      # IPython inside the container
+fab bash       # bash inside the container
+```
+
+This project was generated from [dd-lib-stub](https://github.com/davyddd/dd-lib-stub);
+run `copier update` to pull in template updates.
+
+## AerospikeDsn
+
+A settings field for a cluster: `aerospike://host[:port][,host[:port]]/<namespace>`, validated as a URL like
+pydantic's `PostgresDsn`. The hosts are the seeds the client learns the rest of the cluster from (a missing port
+is 3000), the path names the namespace and is required.
+
+```python
+from pydantic_settings import BaseSettings
+
+from ddaerospike.dsn import AerospikeDsn
+
+
+class Settings(BaseSettings):
+    AEROSPIKE_URL: AerospikeDsn  # AEROSPIKE_URL=aerospike://aerospike-0,aerospike-1/application
+
+
+settings = Settings()
+settings.AEROSPIKE_URL.seeds      # 'aerospike-0:3000,aerospike-1:3000', what `new_client` takes
+settings.AEROSPIKE_URL.namespace  # 'application'
+```
+
+## AerospikeData
+
+A record of a set, every field a bin. Scalars and plain containers are simple bins; a `BaseModel` / `RootModel`
+field is a composite bin stored as a map or list. Datetimes are declared as `AerospikeTimestamp`: stored as integer
+microseconds since the epoch (UTC), read back as an aware datetime, and compared the same way by the filters; a
+bare `datetime` or `date` field is rejected at class definition, as is a bin name over 15 characters. Subclasses
+map to and from the domain through `to_entity` / `from_entity`.
+
+```python
+from pydantic import BaseModel
+
+from ddaerospike.data import AerospikeData, AerospikeTimestamp
+
+
+class Address(BaseModel):
+    city: str
+    zip_code: str | None = None
+
+
+class ProfileData(AerospikeData[Profile]):
+    name: str
+    age: int | None = None
+    created_at: AerospikeTimestamp
+    address: Address | None = None  # a composite bin
+
+    def to_entity(self, **kwargs) -> Profile:
+        return Profile(name=self.name, age=self.age, created_at=self.created_at)
+
+    @classmethod
+    def from_entity(cls, entity: Profile) -> 'ProfileData':
+        return cls(name=entity.name, age=entity.age, created_at=entity.created_at)
+```
+
+## AerospikeManager
+
+ORM-like access to one set, typed by its `AerospikeData` model: `get`, `get_map`, `get_list`, `find_one`, `put`
+and `delete`. It is a Django-style manager, not a dddesign repository: a context repository owns one and maps
+records to entities. The client is obtained for every call from `client_factory`, a `ConnectionManagerFactory`
+from [ddutils](https://github.com/davyddd/ddutils) called with `alias`, the way a
+[ddsql](https://github.com/davyddd/ddsql) adapter runs a query inside `factory(alias=...)`: the factory owns which
+cluster the alias means, the scope the client lives in (one per process and event loop, the client completes its
+futures on the loop it was created in), its lazy creation and its close on shutdown.
+
+```python
+import asyncio
+import os
+from enum import Enum
+from functools import partial
+
+from aerospike_native import Client, ClientPolicy, new_client
+from ddutils.connections import ConnectionManagerFactory
+from ddutils.scoped_registry import ScopedRegistry
+
+from ddaerospike.manager import AerospikeManager
+
+
+class AerospikeConnectionAlias(str, Enum):
+    PRIMARY = 'primary'
+
+
+async def create_client() -> Client:
+    policy = ClientPolicy()
+    policy.timeout = 5_000
+    return await new_client(policy, settings.AEROSPIKE_URL.seeds)
+
+
+def client_scope() -> tuple[int, asyncio.AbstractEventLoop]:
+    return os.getpid(), asyncio.get_running_loop()
+
+
+client_registries = {
+    AerospikeConnectionAlias.PRIMARY: ScopedRegistry[Client](
+        create_func=create_client, scope_func=client_scope, destructor_method_name='close'
+    ),
+}
+aerospike_client_factory = ConnectionManagerFactory(client_registries, default=AerospikeConnectionAlias.PRIMARY)
+
+
+class ProfileManager(AerospikeManager[ProfileData]):
+    client_factory = aerospike_client_factory
+    namespace = settings.AEROSPIKE_URL.namespace
+    set_name = 'profile'
+    ttl_seconds = 30 * 24 * 60 * 60  # set by every write; None leaves the record's TTL alone
+
+
+profile_manager = ProfileManager()
+
+await profile_manager.put(profile.id, ProfileData.from_entity(profile))
+data = await profile_manager.get(profile.id)                       # ProfileData | None
+await profile_manager.get_map([1, 2, 3])                           # {'1': ProfileData, ...}
+await profile_manager.put(profile.id, data, if_absent=True)        # False when the record exists
+await profile_manager.delete(profile.id)
+
+await aerospike_client_factory.close()                             # on shutdown
+```
+
+A bin set to `None` is removed from the record by the write; inside a composite bin the `None` values are left
+out. The `read_policy_fields`, `batch_policy_fields`, `query_policy_fields` and `write_policy_fields` class
+attributes (typed dicts from `ddaerospike.policies`) override the defaults: short timeouts, retries on reads only,
+`send_key` on writes so queries can return the primary key.
+
+## Filters
+
+`AerospikeFilterCollection(Model)` holds the conditions of one query on a set, bound to its record model: at most
+one secondary-index filter (a query runs on one index: equality on `int` / `str`, a range on `int`) and any number
+of filter expressions, ANDed and evaluated on every record the index or the whole set yields. `add_filter` checks
+the bin against the model and the value against the bin's scalar (an `int` widens to a `float` bin); values are
+normalized the way the server compares them (enums to their value, UUIDs to strings, datetimes to
+`AerospikeTimestamp` microseconds, `Decimal` to float), and every operator checks the type it accepts. A composite
+bin only takes `is_null` / `is_not_null`, which take no value.
+
+```python
+from ddaerospike.filters import AerospikeFilterCollection, AerospikeFilterOperator
+
+filters = (
+    AerospikeFilterCollection(ProfileData)
+    .add_filter('name', AerospikeFilterOperator.EQUAL, 'john', use_index=True)   # needs an index on `name`
+    .add_filter('age', AerospikeFilterOperator.BETWEEN, [18, 65])
+    .add_filter('address', AerospikeFilterOperator.IS_NOT_NULL)
+)
+
+items = await profile_manager.get_list(filters, limit=100)   # [AerospikeDataWithPK(pk='1', data=ProfileData(...)), ...]
+first = await profile_manager.find_one(filters)
+```
+
+## AerospikeFeatureFlagStorage
+
+The Aerospike backend of [ddutils](https://github.com/davyddd/ddutils) feature flags: one set, a flag per record
+(`FeatureFlagData`: `enabled`, `proportion`, `payload` bins, the flag name is the primary key), through an
+`AerospikeManager[FeatureFlagData]` the application wires. Client and server errors raise
+`FeatureFlagStorageError`, so `FeatureFlags` keeps serving the last known values; a record that does not validate
+is read as the defaults.
+
+```python
+from ddaerospike.feature_flags import AerospikeFeatureFlagStorage, FeatureFlagData
+from ddaerospike.manager import AerospikeManager
+from ddutils.feature_flags import FeatureFlags
+
+
+class FeatureFlagManager(AerospikeManager[FeatureFlagData]):
+    client_factory = aerospike_client_factory
+    namespace = settings.AEROSPIKE_URL.namespace
+    set_name = 'feature_flag'
+
+
+feature_flags = FeatureFlags(AerospikeFeatureFlagStorage(FeatureFlagManager()))
+
+if await feature_flags.is_enabled('new_checkout'):            # proportion 1.0: on or off for everyone
+    ...
+if await feature_flags.is_enabled('new_ranking', user_id):  # on for `proportion` of the users
+    ...
+```

ddaerospike-0.0.1/ddaerospike/__init__.py

@@ -0,0 +1,3 @@
+from . import data, dsn, feature_flags, filters, manager, policies
+
+__all__ = ('data', 'dsn', 'feature_flags', 'filters', 'manager', 'policies')

ddaerospike-0.0.1/ddaerospike/data.py

@@ -0,0 +1,135 @@
+from datetime import UTC, date, datetime, timedelta
+from typing import Annotated, Any, Generic, NamedTuple, Self, TypeVar, get_origin
+
+from dddesign.structure.domains.constants import BaseEnum
+from dddesign.structure.domains.dto import DataTransferObject
+from ddutils.annotation_helpers import get_annotation_without_optional, is_subclass
+from pydantic import AfterValidator, BaseModel, BeforeValidator, PlainSerializer
+
+# Server-side limit on the length of a bin name
+BIN_NAME_MAX_LENGTH = 15
+
+_EPOCH = datetime(1970, 1, 1, tzinfo=UTC)
+_MICROSECOND = timedelta(microseconds=1)
+
+
+def timestamp_to_bin(value: datetime) -> int:
+    """A datetime as it is stored in a bin: integer microseconds since the epoch, so it compares as a number."""
+    if value.tzinfo is None:
+        raise ValueError('Aerospike timestamps must be timezone-aware')
+    return (value - _EPOCH) // _MICROSECOND
+
+
+def _timestamp_from_bin(value: Any) -> Any:
+    return _EPOCH + timedelta(microseconds=value) if isinstance(value, int) and not isinstance(value, bool) else value
+
+
+def _as_utc(value: datetime) -> datetime:
+    if value.tzinfo is None:
+        raise ValueError('Aerospike timestamps must be timezone-aware')
+    return value.astimezone(UTC)
+
+
+_TIMESTAMP_SERIALIZER = PlainSerializer(timestamp_to_bin, return_type=int)
+
+# The only way to declare a datetime bin: stored as integer microseconds (UTC), read back as an aware datetime,
+# and the same representation `AerospikeFilter` compares against. A bare `datetime` / `date` field is rejected.
+AerospikeTimestamp = Annotated[datetime, BeforeValidator(_timestamp_from_bin), AfterValidator(_as_utc), _TIMESTAMP_SERIALIZER]
+
+
+def _is_composite_annotation(annotation: Any) -> bool:
+    """A `BaseModel` bin (a `RootModel` is one), optional or not. A union of several types or a `Literal` is a simple bin."""
+    try:
+        inner = get_annotation_without_optional(annotation)
+    except TypeError:
+        return False
+    return is_subclass(inner, BaseModel)
+
+
+def _is_bare_date_annotation(annotation: Any, metadata: list[Any]) -> bool:
+    """A `datetime` / `date` bin (optional or not) declared without `AerospikeTimestamp`."""
+    try:
+        inner = get_annotation_without_optional(annotation)
+    except TypeError:
+        return False
+    if not is_subclass(inner, date):
+        return False
+    # pydantic unpacks a top-level `Annotated` into `metadata`; one inside `| None` stays in the annotation
+    if get_origin(inner) is Annotated:
+        metadata = [*metadata, *inner.__metadata__]
+    return not any(item is _TIMESTAMP_SERIALIZER for item in metadata)
+
+
+EntityT = TypeVar('EntityT')
+
+
+class AerospikeBinType(str, BaseEnum):
+    SIMPLE = 'simple'
+    COMPOSITE = 'composite'
+
+
+class AerospikeData(DataTransferObject, Generic[EntityT]):
+    """
+    A record of an Aerospike set: every field is a bin.
+
+    Scalars and plain containers are simple bins. A `BaseModel` / `RootModel` field (a nested object, a typed
+    list or dict) is a composite bin, stored as a map or list; `AerospikeManager` strips its `None` values
+    before writing, so an unset optional nested field costs nothing. Datetimes are declared as
+    `AerospikeTimestamp` (inside composite models too, so they are stored the same way).
+
+    Subclasses map to and from the domain through `to_entity` / `from_entity`.
+    """
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        too_long = tuple(field for field in cls.model_fields if len(field) > BIN_NAME_MAX_LENGTH)
+        if too_long:
+            raise TypeError(f'Aerospike bin names must be at most {BIN_NAME_MAX_LENGTH} characters, got {too_long!r}')
+        bare_dates = tuple(
+            field for field, info in cls.model_fields.items() if _is_bare_date_annotation(info.annotation, info.metadata)
+        )
+        if bare_dates:
+            raise TypeError(f'Datetime bins must be declared as `AerospikeTimestamp`, got {bare_dates!r}')
+
+    @classmethod
+    def get_bins(cls) -> dict[str, AerospikeBinType]:
+        return {
+            field: AerospikeBinType.COMPOSITE if _is_composite_annotation(info.annotation) else AerospikeBinType.SIMPLE
+            for field, info in cls.model_fields.items()
+        }
+
+    def filter_bins(self, bins: dict[str, AerospikeBinType]) -> dict[str, AerospikeBinType]:
+        """Hook: the bins this instance writes. Override to leave some out depending on the data."""
+        return bins
+
+    @classmethod
+    def factory(cls, data: dict[str, Any]) -> Self:
+        return cls.model_validate(data)
+
+    def to_entity(self, **kwargs: Any) -> EntityT:
+        raise NotImplementedError
+
+    @classmethod
+    def from_entity(cls, entity: EntityT) -> Self:
+        raise NotImplementedError
+
+
+# Bound to the real class, not a forward reference: pydantic builds a schema for `type[AerospikeDataT]` fields
+AerospikeDataT = TypeVar('AerospikeDataT', bound=AerospikeData)
+
+
+class AerospikeDataWithPK(NamedTuple, Generic[AerospikeDataT]):
+    # None when the record was written without `send_key`: the server then holds only the key digest
+    pk: str | None
+    data: AerospikeDataT
+
+
+__all__ = (
+    'AerospikeBinType',
+    'AerospikeData',
+    'AerospikeDataWithPK',
+    'AerospikeTimestamp',
+    'BIN_NAME_MAX_LENGTH',
+    'timestamp_to_bin',
+)

ddaerospike-0.0.1/ddaerospike/dsn.py

@@ -0,0 +1,47 @@
+from typing import Any, cast
+
+from pydantic import GetCoreSchemaHandler, GetJsonSchemaHandler, UrlConstraints
+from pydantic.json_schema import JsonSchemaValue
+from pydantic.networks import _BaseMultiHostUrl
+from pydantic_core.core_schema import AfterValidatorFunctionSchema, CoreSchema, no_info_after_validator_function
+
+DEFAULT_PORT = 3000
+
+
+class AerospikeDsn(_BaseMultiHostUrl):
+    """`aerospike://host[:port][,host[:port]]/<namespace>`.
+
+    The hosts are the seeds the client learns the rest of the cluster from; a missing port is 3000.
+    The path names the namespace and is required. Built like pydantic's own `PostgresDsn`.
+    """
+
+    _constraints = UrlConstraints(allowed_schemes=['aerospike'], host_required=True, default_port=DEFAULT_PORT)
+
+    @classmethod
+    def __get_pydantic_core_schema__(cls, source: type[Any], handler: GetCoreSchemaHandler) -> CoreSchema:
+        return no_info_after_validator_function(_require_namespace, super().__get_pydantic_core_schema__(source, handler))
+
+    @classmethod
+    def __get_pydantic_json_schema__(cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler) -> JsonSchemaValue:
+        # Peel off the after-validator above, the base class expects its own function-wrap schema
+        inner = cast('AfterValidatorFunctionSchema', core_schema)['schema']
+        return super().__get_pydantic_json_schema__(inner, handler)
+
+    @property
+    def namespace(self) -> str:
+        return (self.path or '').strip('/')
+
+    @property
+    def seeds(self) -> str:
+        """`host:port,host:port`, the form `aerospike_native.new_client` takes."""
+        # `default_port` fills the port of a single host only; in a host list the others come back as None
+        return ','.join(f'{host["host"]}:{host["port"] or DEFAULT_PORT}' for host in self.hosts())
+
+
+def _require_namespace(dsn: AerospikeDsn) -> AerospikeDsn:
+    if not dsn.namespace:
+        raise ValueError('the path must name the namespace, e.g. aerospike://host:3000/application_db')
+    return dsn
+
+
+__all__ = ('AerospikeDsn',)