persistence-kit 0.1.0__tar.gz

persistence_kit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andres Felipe Serrano Barrios
+
+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.

persistence_kit-0.1.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: persistence-kit
+Version: 0.1.0
+Summary: Reusable persistence and repository toolkit
+License: MIT
+License-File: LICENSE
+Keywords: repository,persistence,mongodb,sqlalchemy,async
+Author: Andres Felipe Serrano Barrios
+Author-email: andresfserrano1@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT 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: Topic :: Database
+Classifier: Typing :: Typed
+Requires-Dist: asyncpg (>=0.30.0,<0.31.0)
+Requires-Dist: motor (>=3.7.1,<4.0.0)
+Requires-Dist: pydantic-settings (>=2.3.0,<3.0.0)
+Requires-Dist: sqlalchemy[asyncio] (>=2.0.43,<3.0.0)
+Requires-Dist: typing-extensions (>=4.12.0,<5.0.0)
+Project-URL: Documentation, https://github.com/andresfserrano/persistence-kit#readme
+Project-URL: Homepage, https://pypi.org/project/persistence-kit/
+Project-URL: Repository, https://github.com/andresfserrano/persistence-kit
+Description-Content-Type: text/markdown
+
+# persistence-kit
+
+Reusable persistence toolkit with async repository implementations for:
+
+- `memory`
+- `mongo` (Motor)
+- `postgres` (SQLAlchemy async + asyncpg)
+
+Author: Andres Felipe Serrano Barrios
+
+## Installation
+
+```bash
+pip install persistence-kit
+```
+
+## Quick Start
+
+```python
+from persistence_kit.repository_factory import register_entity, get_repo
+from persistence_kit.config import Database
+
+# register entities during application startup
+register_entity(
+    "user",
+    {
+        "entity": User,
+        "collection": "users",
+        "database": Database.MEMORY,
+        "unique": {"email": "email"},
+    },
+)
+
+repo = get_repo("user")
+```
+
+## Supported Environment Variables
+
+- `REPO_DATABASE=memory|mongo|postgres`
+- `MONGO_DSN`
+- `MONGO_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `POSTGRES_DB`
+
+## Publish to PyPI (Manual)
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## Automated Publish via GitHub Actions
+
+This repository includes a workflow at `.github/workflows/publish-pypi.yml`.
+
+It publishes to PyPI when:
+
+- a GitHub Release is published
+- the release tag points to the current `main` HEAD
+
+Prerequisite:
+
+- Configure PyPI Trusted Publishing for this repository and workflow file.
+
+## Preview Releases Without PRs
+
+Use `.github/workflows/publish-preview.yml` to publish directly from GitHub Actions
+without merging a PR.
+
+How it works:
+
+- Trigger `Publish Preview Package` manually from the Actions tab.
+- Enter a `version` (for example `0.1.1.dev1` or `0.1.2.dev1`).
+- Choose target repository: `testpypi` (recommended) or `pypi`.
+- The workflow patches `pyproject.toml` version only inside the CI run, builds, and publishes.
+- No commit and no PR are required for this preview publish flow.
+
+Important:
+
+- Prefer `*.devN` versions for preview builds.
+- PyPI/TestPyPI do not allow re-uploading the same file version.
+
+## Local Test Releases (No PR Required)
+
+If you want to test changes from your machine in external projects without opening a PR,
+publish a prerelease from local code to TestPyPI.
+
+### 1. Create a TestPyPI token
+
+- Create an API token in TestPyPI.
+- Export it as environment variable:
+
+```bash
+export TWINE_PASSWORD="pypi-***"
+```
+
+### 2. Publish from local code
+
+```bash
+bash ./scripts/publish-local.sh 0.1.1.dev1 testpypi
+```
+
+You can publish another local iteration with a new version:
+
+```bash
+bash ./scripts/publish-local.sh 0.1.1.dev2 testpypi
+```
+
+### 3. Install from external projects
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple persistence-kit==0.1.1.dev1
+```
+
+## Recommended Release Strategy
+
+- Local experimental testing: publish `0.x.y.devN` to TestPyPI from local machine.
+- Official release: publish `0.x.y` to PyPI through GitHub Release (`publish-pypi.yml`).
+

persistence_kit-0.1.0/README.md

@@ -0,0 +1,123 @@
+# persistence-kit
+
+Reusable persistence toolkit with async repository implementations for:
+
+- `memory`
+- `mongo` (Motor)
+- `postgres` (SQLAlchemy async + asyncpg)
+
+Author: Andres Felipe Serrano Barrios
+
+## Installation
+
+```bash
+pip install persistence-kit
+```
+
+## Quick Start
+
+```python
+from persistence_kit.repository_factory import register_entity, get_repo
+from persistence_kit.config import Database
+
+# register entities during application startup
+register_entity(
+    "user",
+    {
+        "entity": User,
+        "collection": "users",
+        "database": Database.MEMORY,
+        "unique": {"email": "email"},
+    },
+)
+
+repo = get_repo("user")
+```
+
+## Supported Environment Variables
+
+- `REPO_DATABASE=memory|mongo|postgres`
+- `MONGO_DSN`
+- `MONGO_DB`
+- `POSTGRES_USER`
+- `POSTGRES_PASSWORD`
+- `POSTGRES_HOST`
+- `POSTGRES_PORT`
+- `POSTGRES_DB`
+
+## Publish to PyPI (Manual)
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+python -m twine upload dist/*
+```
+
+## Automated Publish via GitHub Actions
+
+This repository includes a workflow at `.github/workflows/publish-pypi.yml`.
+
+It publishes to PyPI when:
+
+- a GitHub Release is published
+- the release tag points to the current `main` HEAD
+
+Prerequisite:
+
+- Configure PyPI Trusted Publishing for this repository and workflow file.
+
+## Preview Releases Without PRs
+
+Use `.github/workflows/publish-preview.yml` to publish directly from GitHub Actions
+without merging a PR.
+
+How it works:
+
+- Trigger `Publish Preview Package` manually from the Actions tab.
+- Enter a `version` (for example `0.1.1.dev1` or `0.1.2.dev1`).
+- Choose target repository: `testpypi` (recommended) or `pypi`.
+- The workflow patches `pyproject.toml` version only inside the CI run, builds, and publishes.
+- No commit and no PR are required for this preview publish flow.
+
+Important:
+
+- Prefer `*.devN` versions for preview builds.
+- PyPI/TestPyPI do not allow re-uploading the same file version.
+
+## Local Test Releases (No PR Required)
+
+If you want to test changes from your machine in external projects without opening a PR,
+publish a prerelease from local code to TestPyPI.
+
+### 1. Create a TestPyPI token
+
+- Create an API token in TestPyPI.
+- Export it as environment variable:
+
+```bash
+export TWINE_PASSWORD="pypi-***"
+```
+
+### 2. Publish from local code
+
+```bash
+bash ./scripts/publish-local.sh 0.1.1.dev1 testpypi
+```
+
+You can publish another local iteration with a new version:
+
+```bash
+bash ./scripts/publish-local.sh 0.1.1.dev2 testpypi
+```
+
+### 3. Install from external projects
+
+```bash
+pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple persistence-kit==0.1.1.dev1
+```
+
+## Recommended Release Strategy
+
+- Local experimental testing: publish `0.x.y.devN` to TestPyPI from local machine.
+- Official release: publish `0.x.y` to PyPI through GitHub Release (`publish-pypi.yml`).

persistence_kit-0.1.0/persistence_kit/__init__.py

@@ -0,0 +1,5 @@
+from .abstract_repository import Repository
+from .abstract_view_repo import ViewRepository
+from .config import Database, RepoSettings
+
+__all__ = ["Repository", "ViewRepository", "Database", "RepoSettings"]

persistence_kit-0.1.0/persistence_kit/abstract_repository.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from typing import Optional, Sequence, TypeVar, Generic, Hashable, Mapping, Any
+
+T = TypeVar("T")
+TId = TypeVar("TId", bound=Hashable)
+
+class Repository(ABC, Generic[T, TId]):
+    @abstractmethod
+    async def add(self, entity: T) -> None: ...
+
+    @abstractmethod
+    async def get(self, entity_id: TId) -> Optional[T]: ...
+
+    @abstractmethod
+    async def list(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 50,
+        sort_by: str | None = None,
+        sort_desc: bool = False,
+    ) -> Sequence[T]: ...
+
+    @abstractmethod
+    async def update(self, entity: T) -> None: ...
+
+    @abstractmethod
+    async def delete(self, entity_id: TId) -> None: ...
+
+    @abstractmethod
+    async def get_by_index(self, index: str, value: Hashable) -> Optional[T]: ...
+
+    @abstractmethod
+    async def list_by_fields(
+        self,
+        criteria: Mapping[str, Hashable | list[Hashable] | Mapping[str, Any]],
+        *,
+        offset: int = 0,
+        limit: Optional[int] = 50,
+        sort_by: str | None = None,
+        sort_desc: bool = False,
+    ) -> Sequence[T]: ...

persistence_kit-0.1.0/persistence_kit/abstract_view_repo.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from typing import Optional, Sequence, TypeVar, Generic, Hashable, Mapping, Any
+
+T = TypeVar("T")
+TId = TypeVar("TId", bound=Hashable)
+
+class ViewRepository(ABC, Generic[T, TId]):
+    @abstractmethod
+    async def get_with(self, entity_id: TId, include: Sequence[str]) -> Optional[dict]: ...
+
+    @abstractmethod
+    async def get_by_index_with(
+        self,
+        index: str,
+        value: Hashable,
+        include: Sequence[str],
+    ) -> Optional[dict]: ...
+
+    @abstractmethod
+    async def list_with(
+        self,
+        *,
+        offset: int = 0,
+        limit: int = 50,
+        include: Sequence[str] = (),
+        sort_by: str | None = None,
+        sort_desc: bool = False,
+    ) -> list[dict]: ...
+
+    @abstractmethod
+    async def list_by_fields(
+        self,
+        criteria: Mapping[str, Hashable | list[Hashable] | Mapping[str, Any]],
+        *,
+        offset: int = 0,
+        limit: Optional[int] = 50,
+        include: Sequence[str] = (),
+        sort_by: str | None = None,
+        sort_desc: bool = False,
+    ) -> list[dict]: ...

persistence_kit-0.1.0/persistence_kit/config.py

@@ -0,0 +1,26 @@
+from enum import Enum
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Database(str, Enum):
+    MEMORY = "memory"
+    MONGO = "mongo"
+    POSTGRES = "postgres"
+
+
+class RepoSettings(BaseSettings):
+    repo_database: Database = Database.MEMORY
+
+    mongo_dsn: str | None = None
+    mongo_db: str | None = None
+
+    postgres_user: str | None = None
+    postgres_password: str | None = None
+    postgres_host: str | None = None
+    postgres_port: int | None = 5432
+    postgres_db: str | None = None
+
+    # Keep the library environment-agnostic. Host applications decide
+    # whether settings come from .env, process env vars, secret stores, etc.
+    model_config = SettingsConfigDict(extra="ignore")

persistence_kit-0.1.0/persistence_kit/py.typed

@@ -0,0 +1 @@
+

persistence_kit-0.1.0/persistence_kit/repository/.idea/inspectionProfiles/profiles_settings.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <settings>
+    <option name="USE_PROJECT_PROFILE" value="false" />
+    <version value="1.0" />
+  </settings>
+</component>

persistence_kit-0.1.0/persistence_kit/repository/.idea/misc.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectRootManager" version="2" project-jdk-name="Python 3.11 virtualenv at C:\Users\andre\OneDrive\Escritorio\SIGA\Backend\.venv" project-jdk-type="Python SDK" />
+</project>

persistence_kit-0.1.0/persistence_kit/repository/.idea/modules.xml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ProjectModuleManager">
+    <modules>
+      <module fileurl="file://$PROJECT_DIR$/.idea/repository.iml" filepath="$PROJECT_DIR$/.idea/repository.iml" />
+    </modules>
+  </component>
+</project>

persistence_kit-0.1.0/persistence_kit/repository/.idea/repository.iml

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<module type="PYTHON_MODULE" version="4">
+  <component name="NewModuleRootManager">
+    <content url="file://$MODULE_DIR$" />
+    <orderEntry type="jdk" jdkName="Python 3.11 virtualenv at C:\Users\andre\OneDrive\Escritorio\SIGA\Backend\.venv" jdkType="Python SDK" />
+    <orderEntry type="sourceFolder" forTests="false" />
+  </component>
+</module>

persistence_kit-0.1.0/persistence_kit/repository/.idea/workspace.xml

@@ -0,0 +1,48 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="ChangeListManager">
+    <list default="true" id="3353231d-cbff-4250-b6f6-e702a244cb73" name="Changes" comment="" />
+    <option name="SHOW_DIALOG" value="false" />
+    <option name="HIGHLIGHT_CONFLICTS" value="true" />
+    <option name="HIGHLIGHT_NON_ACTIVE_CHANGELIST" value="false" />
+    <option name="LAST_RESOLUTION" value="IGNORE" />
+  </component>
+  <component name="ProjectColorInfo"><![CDATA[{
+  "associatedIndex": 7
+}]]></component>
+  <component name="ProjectId" id="3A5AquY2AKyR9xwjoFWX4R6KC9b" />
+  <component name="ProjectViewState">
+    <option name="hideEmptyMiddlePackages" value="true" />
+    <option name="showLibraryContents" value="true" />
+  </component>
+  <component name="PropertiesComponent"><![CDATA[{
+  "keyToString": {
+    "ModuleVcsDetector.initialDetectionPerformed": "true",
+    "RunOnceActivity.ShowReadmeOnStart": "true",
+    "last_opened_file_path": "C:/Users/andre/OneDrive/Escritorio/aux programación udea/persistence_kit/repository",
+    "vue.rearranger.settings.migration": "true"
+  }
+}]]></component>
+  <component name="SharedIndexes">
+    <attachedChunks>
+      <set>
+        <option value="bundled-js-predefined-d6986cc7102b-9c94529fcfe0-JavaScript-PY-252.26199.168" />
+        <option value="bundled-python-sdk-b3d66beaba9a-c6efb3732140-com.jetbrains.pycharm.pro.sharedIndexes.bundled-PY-252.26199.168" />
+      </set>
+    </attachedChunks>
+  </component>
+  <component name="TaskManager">
+    <task active="true" id="Default" summary="Default task">
+      <changelist id="3353231d-cbff-4250-b6f6-e702a244cb73" name="Changes" comment="" />
+      <created>1771872251986</created>
+      <option name="number" value="Default" />
+      <option name="presentableId" value="Default" />
+      <updated>1771872251986</updated>
+      <workItem from="1771872254661" duration="18000" />
+    </task>
+    <servers />
+  </component>
+  <component name="TypeScriptGeneratedFilesManager">
+    <option name="version" value="3" />
+  </component>
+</project>

persistence_kit-0.1.0/persistence_kit/repository/__init__.py

@@ -0,0 +1,18 @@
+from .memory_repo import MemoryRepository
+from .mongo_repo import DataclassMapper, MongoRepository
+from .sqlalchemy_repo import (
+    SqlAlchemyRepository,
+    SqlDataclassMapper,
+    build_table_from_dataclass,
+    get_engine,
+)
+
+__all__ = [
+    "MemoryRepository",
+    "MongoRepository",
+    "DataclassMapper",
+    "SqlAlchemyRepository",
+    "SqlDataclassMapper",
+    "build_table_from_dataclass",
+    "get_engine",
+]

persistence_kit-0.1.0/persistence_kit/repository/filter_ops.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Mapping
+
+
+_SIMPLE_OPS = {"gte", "gt", "lte", "lt", "eq", "ne"}
+
+
+def is_multi_value(value: Any) -> bool:
+    return isinstance(value, list)
+
+
+def is_range_dict(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def iter_range_ops(value: Mapping[str, Any]) -> Iterable[tuple[str, Any]]:
+    if not value:
+        return []
+    items = list(value.items())
+    for op, v in items:
+        if op == "between":
+            if not isinstance(v, list) or len(v) != 2:
+                raise ValueError("between expects a list with exactly two values")
+        elif op == "in":
+            if not isinstance(v, list):
+                raise ValueError("in expects a list")
+        elif op in _SIMPLE_OPS:
+            continue
+        else:
+            raise ValueError(f"Unsupported operator: {op}")
+    return items

persistence_kit-0.1.0/persistence_kit/repository/memory_repo/__init__.py

@@ -0,0 +1,3 @@
+from .memory_repo import MemoryRepository
+
+__all__ = ["MemoryRepository"]