fennflow 0.1.0__tar.gz

fennflow-0.1.0/.github/ISSUE_TEMPLATE/bug-notice.yaml

@@ -0,0 +1,74 @@
+name: 🐛 fennflow Bug
+description: Report a bug or unexpected behavior in fennflow
+labels: ["bug"]
+assignees: ["Alex-FIR-IT"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for contributing to fennflow! ✊
+
+        Please provide as much information as possible to help us reproduce and fix your issue quickly.
+
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Initial Checks
+      description: Just making sure we're on the same page.
+      options:
+        - label: I'm using the [latest version](https://github.com/Alex-FIR-IT/fennflow/releases/latest) of fennflow
+          required: true
+        - label: I've searched for my issue in [the issue tracker](https://github.com/Alex-FIR-IT/fennflow/issues) before opening this issue
+          required: true
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: |
+        Please explain what you're seeing and what you would expect to see.
+
+        - **A line of code is worth a thousand words**: you can include minimal, reproducible example code below.
+    validations:
+      required: true
+
+  - type: textarea
+    id: stacktrace
+    attributes:
+      label: Stacktrace
+      description: |
+        Please provide the full stacktrace of any error you're encountering.
+    validations:
+      required: false
+
+  - type: textarea
+    id: example
+    attributes:
+      label: Minimal, Reproducible Example
+      description: >
+        If at all possible, please add a self-contained,
+        [minimal, reproducible example](https://stackoverflow.com/help/minimal-reproducible-example)
+        that demonstrates the bug.
+
+        (This will be automatically formatted as code, so no need for backticks.)
+
+      placeholder: |
+        from fennflow import ...
+
+        ...
+      render: Python
+
+  - type: textarea
+    id: version
+    attributes:
+      label: Python, fennflow & packages that used by fennflow version
+      description: |
+        Which version of Python, fennflow, and packages that used by fennflow are you using?
+      value: |
+        - Python:
+        - fennflow:
+        - aiobotocore: 
+        - pydantic:
+    validations:
+      required: true

fennflow-0.1.0/.github/ISSUE_TEMPLATE/engineering-task.yaml

@@ -0,0 +1,49 @@
+name: ⚙️ fennflow Engineering Task
+description: "Internal engineering task (CI, tooling, testing, typing, infrastructure)"
+labels: [ "infra" ]
+assignees: [ "Alex-FIR-IT" ]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for improving fennflow’s engineering quality ✊
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: |
+        Please describe the engineering or infrastructure task in detail.
+
+        This may include:
+        * CI/CD improvements (GitHub Actions, pipelines)
+        * Type checking (mypy, pyright)
+        * Linting / formatting (ruff, black)
+        * Testing infrastructure or coverage improvements
+        * Build / packaging / dependency management changes
+
+        Include context and motivation for why this change is needed.
+    validations:
+      required: true
+
+  - type: textarea
+    id: impact
+    attributes:
+      label: Impact
+      description: |
+        Describe the impact of this change on the development process or codebase quality.
+
+        Examples:
+        * Improved maintainability
+        * Faster CI feedback
+        * Better type safety
+        * Reduced technical debt
+    validations:
+      required: true
+
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: |
+        Add any links, tools, or examples that might help understand the task better.

fennflow-0.1.0/.github/ISSUE_TEMPLATE/feature-request.yaml

@@ -0,0 +1,30 @@
+name: 🚀 fennflow Feature Request
+description: "Suggest a new feature for fennflow"
+labels: ["enhancement"]
+assignees: ["Alex-FIR-IT"]
+
+body:
+  - type: markdown
+    attributes:
+      value: Thank you for contributing to fennflow! ✊
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: |
+        Please give as much detail as possible about the feature you would like to suggest. 🙏
+
+        You might like to add:
+        * A demo of how code might look when using the feature
+        * Your use case(s) for the feature
+        * Reference to other projects that have a similar feature
+    validations:
+      required: true
+
+  - type: textarea
+    id: references
+    attributes:
+      label: References
+      description: |
+        Please add any links or references that might help us understand your feature request better. 📚

fennflow-0.1.0/.github/ISSUE_TEMPLATE/question.yaml

@@ -0,0 +1,35 @@
+name: ❓ fennflow Question
+description: "Ask a question about fennflow"
+labels: ["question"]
+assignees: ["Alex-FIR-IT"]
+
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for reaching out to the fennflow community! We're here to help! 🤝
+
+  - type: textarea
+    id: question
+    attributes:
+      label: Question
+      description: |
+        Please provide as much detail as possible about your question. 🙏
+
+        You might like to include:
+        * Code snippets showing what you've tried
+        * Error messages you're encountering (if any)
+        * Expected vs actual behavior
+        * Your use case and what you're trying to achieve
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional Context
+      description: |
+        Please provide any additional context that might help us better understand your question, such as:
+        * Your fennflow version
+        * Your Python version
+        * Relevant configuration or environment details 📝

fennflow-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: monthly
+    cooldown:
+      default-days: 7
+    groups:
+      github-actions:
+        patterns:
+          - "*"

fennflow-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,6 @@
+- Closes #<issue>
+
+### Checklist
+
+- [ ] Any **AI generated code** has been reviewed line-by-line by the human PR author, who stands by it.
+- [ ] **PR title** is fit for the [release changelog](https://github.com/Alex-FIR-IT/FennFlow/releases).

fennflow-0.1.0/.github/release.yml

@@ -0,0 +1,19 @@
+changelog:
+  exclude:
+    labels:
+      - docs
+      - chore
+  categories:
+    - title: 🚀 Features
+      labels:
+        - enhancement
+    - title: 🐛 Bug Fixes
+      labels:
+        - bug
+    - title: 📦 Dependencies
+      labels:
+        - dependency
+    - title: 🔧 Internal
+      labels:
+        - ci
+        - infra

fennflow-0.1.0/.github/workflows/coverage-report.yml

@@ -0,0 +1,81 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
+
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Run ruff
+        run: uv run ruff check src/
+
+      - name: Run tests with coverage
+        run: uv run pytest --cov=src/fennflow
+        env:
+          COVERAGE_FILE: .coverage.${{ matrix.python-version }}
+
+      - name: Upload coverage artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+
+  coverage:
+    runs-on: ubuntu-latest
+    needs: [ test ]
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-groups
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@70fc10c6e5e1ce46ad2ea6f2b72d43f7d47b13c3 # v8
+        with:
+          merge-multiple: true
+          path: .coverage-data
+
+      - name: Combine coverage
+        run: uv run coverage combine .coverage-data/
+
+      - name: Convert to XML
+        run: uv run coverage xml
+
+      - name: Upload to Codacy
+        uses: codacy/codacy-coverage-reporter-action@89d6c85cfafaec52c72b6c5e8b2878d33104c699 # v1
+        with:
+          project-token: ${{ secrets.CODACY_PROJECT_TOKEN }}
+          coverage-reports: coverage.xml
+
+  all-tests-passed:
+    runs-on: ubuntu-latest
+    needs: [ coverage ]
+    steps:
+      - run: echo "All matrix jobs passed"

fennflow-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # required for Trusted Publishing
+      contents: write   # required to create GitHub Release
+
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3 # v6
+        with:
+          fetch-depth: 0  # needed for uv-dynamic-versioning to read git tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
+
+      - name: Build
+        run: uvx hatch build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3
+        with:
+          generate_release_notes: true  # auto-generates from merged PRs/commits
+          files: dist/*

fennflow-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+.idea
+.env
+.notes
+site
+main.py

fennflow-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

fennflow-0.1.0/LICENSE

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

fennflow-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: fennflow
+Version: 0.1.0
+Summary: Atomic-like S3 Framework with Saga Pattern, the Pydantic way
+Project-URL: Homepage, https://github.com/Alex-FIR-IT/FennFlow
+Project-URL: Source, https://github.com/Alex-FIR-IT/FennFlow
+Project-URL: Documentation, https://github.com/Alex-FIR-IT/FennFlow/blob/master/docs/README.md
+Author-email: AlexFIR <osintfir@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+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 :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: aiobotocore>=3.0.0
+Requires-Dist: certifi>=2023.11.17
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+    <a href="https://github.com/Alex-FIR-IT/FennFlow">
+    <picture>
+      <img src="https://c438939f-e2e4-4a9c-a938-fc6e872413f4.selstorage.ru/github.png" alt="FennFlow">
+    </picture>
+  </a>
+</div>
+<div align="center">
+  <h3>Atomic-like S3 Framework, the Pydantic way</h3>
+</div>
+<div align="center">
+  <a href="https://github.com/Alex-FIR-IT/FennFlow/actions/workflows/coverage-report.yml"><img src="https://github.com/Alex-FIR-IT/FennFlow/actions/workflows/coverage-report.yml/badge.svg?branch=master" alt="CI"></a>
+  <a href="https://app.codacy.com/gh/Alex-FIR-IT/FennFlow/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_coverage"><img src="https://app.codacy.com/project/badge/Coverage/3db23fc6c6f248f2926731b0bdf0d012" alt="Codacy Coverage"></a>
+  <a href="https://github.com/users/Alex-FIR-IT/projects/2/views/2"><img src="https://img.shields.io/badge/Roadmap-green?logo=github" alt="Roadmap"></a>
+  <a href="https://github.com/Alex-FIR-IT"><img src="https://img.shields.io/pypi/pyversions/fennflow?logo=python&logoColor=white" alt="versions"></a>
+  <a href="https://github.com/Alex-FIR-IT/fennflow/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-brightgreen" alt="License: MIT"></a>
+  <a href="https://github.com/Alex-FIR-IT/fennflow/commits/master/"><img src="https://img.shields.io/github/last-commit/Alex-FIR-IT/fennflow?logo=github" alt="Last Commit"></a>
+  <a href="https://app.codacy.com/gh/Alex-FIR-IT/FennFlow/dashboard?utm_source=gh&utm_medium=referral&utm_content=&utm_campaign=Badge_grade"><img src="https://app.codacy.com/project/badge/Grade/3db23fc6c6f248f2926731b0bdf0d012" alt="Codacy Grade"></a>
+</div>
+
+---
+
+**Documentation**: [docs/README.md](https://github.com/Alex-FIR-IT/FennFlow/blob/master/docs/README.md)
+
+---
+
+### <em>FennFlow is a Python s3 framework designed to help you quickly, confidently, and painlessly manipulate files in your object storage implementing Saga-like compensation flow.</em>
+
+## Why use FennFlow?
+
+Working with aiobotocore often feels like handling raw bytes and dicts. `FennFlow` wraps S3 operations into a high-level
+Unit of Work pattern, providing:
+
+- **Atomic-like multistep operations** — if something fails, previous actions are automatically compensated (Saga
+  Pattern).
+- **Clean Architecture** — treat S3 as proper repositories using mixins (`PutRepository`, `GetRepository`, etc.).
+- **Pydantic-powered models** — work with `TextContent`, `JsonContent`, `ImageContent` and others instead of raw bytes.
+
+## Supported Connectors
+
+| Connector           | Description                                  | Documentation                               |
+|---------------------|----------------------------------------------|---------------------------------------------|
+| AWS S3              | s3 compatible object storage via aiobotocore | [Quick start](docs/connectors/s3.md)        |
+| In-Memory (default) | great for and tests and development          | [Quick start](docs/connectors/in-memory.md) |
+
+## Supported Backends
+
+FennFlow uses backend as a source of truth for your file storage.
+No matter what your file storage contains, backend ensures your data is consistent.
+
+| Backend             | Description                                         | Documenration                             |
+|---------------------|-----------------------------------------------------|-------------------------------------------|
+| In-Memory (default) | great for and tests, development and small projects | [Quick start](docs/backends/in-memory.md) |
+
+### Backend Comparison
+
+|                    | Raw aiobotocore                                   | In-Memory                                                                                     |
+|--------------------|---------------------------------------------------|-----------------------------------------------------------------------------------------------|
+| **Consistency**    | 🔴 None<br>No link between files and metadata     | 🟡 Medium<br>Consistent within process lifetime, lost on crash                                | 
+| **Compensation**   | 🔴 None<br>Orphaned files on failure              | 🟡 Medium<br>Automatic within process, orphaned files possible on crash                       | 
+| **Reliability**    | 🔴 Low<br>Failures leave storage in unknown state | 🟡 Medium<br>Syncs with storage on restart, files uploaded during crash cannot be compensated | 
+| **Latency**        | ✅ Lowest<br>Pure S3 network overhead only         | ✅ Lowest<br>Minimal in-process overhead                                                       | 
+| **Infrastructure** | ✅ None                                            | ✅ None                                                                                        |
+| **Memory usage**   | ✅ None                                            | 🟡 Stores file metadata in-process                                                            |
+
+## Quick Start
+
+Here's a minimal example of FennFlow:
+
+```python3
+import asyncio
+
+from fennflow import ConfigDict, UnitOfWork
+from fennflow.backends import InMemoryBackendConfig
+from fennflow.connectors import S3ConnectorConfig
+from fennflow.files import BinaryContent, JsonContent, TextContent
+from fennflow.repositories import (
+    DeleteRepository,
+    GetRepository,
+    ListRepository,
+    PutRepository,
+    S3RepoField,
+    )
+
+
+# 1. Define your repository with mixins
+class CrudRepository(
+    PutRepository,
+    DeleteRepository,
+    GetRepository,
+    ListRepository,
+    ):
+    pass
+
+
+# 2. Set up your Unit of Work
+class UOW(UnitOfWork):
+    my_files = S3RepoField(CrudRepository, bucket_name="my_files")
+    config = ConfigDict(
+        backend=InMemoryBackendConfig(),
+        connector=S3ConnectorConfig(),
+        )
+
+
+async def main():
+    text_file = TextContent.from_content("Hello, world!")
+    json_file = JsonContent.from_content([1, 2, 3])
+    binary_file = BinaryContent(data=b"some bytes", media_type="text/plain")
+
+    async with UOW() as uow:
+        await uow.my_files.at("folder1").put(
+            text_file,
+            json_file,
+            binary_file,
+            )
+
+        paths = await uow.my_files.at("folder1").list()
+        print(paths)  # ListResponse[Filepath, ...]
+
+        files = await uow.my_files.get(*paths)
+        print(files)  # MediaResponse[TextContent, JsonContent, BinaryContent]
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Next Steps
+
+Read the [docs](https://github.com/Alex-FIR-IT/FennFlow/blob/master/docs/README.md) to learn more about working with
+FennFlow.
+