bazis-async-background 2.2.0__tar.gz

bazis_async_background-2.2.0/.dockerignore

@@ -0,0 +1,3 @@
+.gitlab-ci.yml
+.gitignore
+.dockerignore

bazis_async_background-2.2.0/.github/workflows/build-publish.yml

@@ -0,0 +1,16 @@
+name: Build and Publish
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    uses: ecofuture-tech/.github/.github/workflows/reusable-build-publish.yml@main
+    secrets:
+      PYPI_TOKEN: ${{ secrets.PYPI_TOKEN }}
+      TEST_PYPI_TOKEN: ${{ secrets.TEST_PYPI_TOKEN }}

bazis_async_background-2.2.0/.github/workflows/update-licenses.yml

@@ -0,0 +1,18 @@
+name: Update Licenses
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - '**.py'
+      - 'pyproject.toml'
+
+permissions:
+  contents: write
+
+jobs:
+  update-licenses:
+    uses: ecofuture-tech/.github/.github/workflows/reusable-update-licenses.yml@main
+    secrets:
+      WORKFLOW_LICENSE_TOKEN: ${{ secrets.WORKFLOW_LICENSE_TOKEN }}

bazis_async_background-2.2.0/.gitignore

@@ -0,0 +1,44 @@
+.idea
+.ipynb_checkpoints
+.mypy_cache
+.vscode
+__pycache__
+.pytest_cache
+htmlcov
+dist
+site
+.coverage
+coverage.xml
+.netlify
+test.db
+log.txt
+Pipfile.lock
+env3.*
+env
+docs_build
+venv
+.venv
+docs.zip
+archive.zip
+
+.env
+local.env
+*/.env*
+
+# vim temporary files
+*~
+.*.sw?
+*.DS_Store
+
+*.egg-info
+build
+dist
+
+docs/_autosummary
+docs/_build
+*.DS_Store
+*.log
+my-*
+My*
+*/**/_version.py
+/uv.lock

bazis_async_background-2.2.0/PKG-INFO

@@ -0,0 +1,271 @@
+Metadata-Version: 2.4
+Name: bazis-async-background
+Version: 2.2.0
+Summary: Async Background core framework for Bazis.
+Author-email: Ilya Kharyn <ilya.tt07@gmail.com>
+Maintainer-email: Ilya Kharyn <ilya.tt07@gmail.com>
+Project-URL: Home, https://github.com/ecofuture-tech/bazis-async-background
+Keywords: bazis,django,fastapi,async,background,kafka,framework
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Framework :: Django
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: bazis
+Requires-Dist: bazis-ws
+Requires-Dist: faststream[kafka]
+Provides-Extra: test
+Requires-Dist: bazis-test-utils; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+
+# Bazis Async Background
+
+[![PyPI version](https://img.shields.io/pypi/v/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Core background task framework for Bazis. It provides Kafka broker helpers, task schemas, status storage in Redis, and a base API to retrieve task results.
+
+## Quick Start
+
+```bash
+# Install the package
+uv add bazis-async-background
+
+# Configure environment variables / settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# Run consumer in Kubernetes
+python manage.py kafka_consumer_single
+
+# Run multiple consumers locally
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+## Table of Contents
+
+- [Description](#description)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+  - [Environment Variables / Settings](#environment-variables--settings)
+  - [Route Registration](#route-registration)
+- [Usage](#usage)
+  - [Running Consumers](#running-consumers)
+- [Examples](#examples)
+- [License](#license)
+- [Links](#links)
+
+## Description
+
+**Bazis Async Background** is a core package for running background tasks in the Bazis framework. It includes:
+
+- **Kafka Producer** — sending tasks to Kafka queue
+- **Kafka Consumer** — processing tasks from the queue
+- **Redis storage** — storing task execution results
+- **API endpoint** — retrieving results by task_id
+
+## Requirements
+
+- **Python**: 3.12+
+- **bazis**: latest version
+- **PostgreSQL**: 12+
+- **Redis**: For storing results and caching
+- **Kafka**: For task queue
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add bazis-async-background
+```
+
+### Using pip
+
+```bash
+pip install bazis-async-background
+```
+
+## Running Tests
+
+Run from the project root:
+
+```bash
+docker compose -f sample/docker-compose.test.yml up --build --exit-code-from bazis-async-background-pytest --attach bazis-async-background-pytest --attach bazis-async-background-consumer-test
+```
+
+This waits for the pytest container to finish and streams logs only from the Python containers, so test completion and output are easy to follow.
+
+## Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │ Background task request
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│ (Async Background)  │
+└──────┬──────────────┘
+       │ 1. Return task_id (202)
+       │ 2. Send to Kafka
+       ▼
+┌─────────────────────┐
+│   Kafka Topic       │
+│ (async_background)  │
+└──────┬──────────────┘
+       │
+       │ Consumer polls
+       ▼
+┌─────────────────────┐
+│  Kafka Consumer     │
+│  (Background Worker)│
+└──────┬──────────────┘
+       │ 3. Process task
+       │ 4. Save result to Redis
+       ▼
+┌─────────────────────┐
+│      Redis          │
+│   (Results Store)   │
+└──────┬──────────────┘
+       │
+       │ 5. GET /async_background_response/{task_id}/
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│   (Get Result)      │
+└─────────────────────┘
+```
+
+## Configuration
+
+### Environment Variables / Settings
+
+Add to your `.env` or `settings.py`:
+
+```bash
+# Required settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+
+# Optional settings
+KAFKA_CONSUMER_LIFETIME_SEC=900           # Consumer lifetime (15 minutes)
+KAFKA_CONSUMER_LIFETIME_JITTER_SEC=180    # Random deviation (3 minutes)
+KAFKA_AUTO_OFFSET_RESET=latest
+KAFKA_ENABLE_AUTO_COMMIT=true
+KAFKA_AUTO_COMMIT_INTERVAL_MS=5000
+KAFKA_LOG_LEVEL=INFO
+```
+
+**Parameters**:
+
+- `KAFKA_TASKS` — dotted module paths imported by the consumer to register tasks
+- `KAFKA_BOOTSTRAP_SERVERS` — Kafka broker address
+- `KAFKA_TOPIC_ASYNC_REQUEST` — topic for async tasks
+- `KAFKA_GROUP_ID` — consumer group
+- `KAFKA_CONSUMER_LIFETIME_SEC` — consumer working time before restart
+- `KAFKA_CONSUMER_LIFETIME_JITTER_SEC` — random deviation to avoid simultaneous restart
+- `KAFKA_AUTO_OFFSET_RESET` — Kafka auto offset reset policy
+- `KAFKA_ENABLE_AUTO_COMMIT` — Kafka auto-commit toggle
+- `KAFKA_AUTO_COMMIT_INTERVAL_MS` — auto-commit interval in ms
+- `KAFKA_LOG_LEVEL` — log level for consumers
+
+### Route Registration
+
+Add the route for getting results to your `router.py`:
+
+```python
+from bazis.core.routing import BazisRouter
+
+router = BazisRouter(prefix='/api/v1')
+
+# Register background task results route
+router.register('bazis.contrib.async_background.router')
+```
+
+This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
+
+## Usage
+
+### Running Consumers
+
+#### For Kubernetes (one consumer per pod)
+
+```bash
+python manage.py kafka_consumer_single
+```
+
+Runs one consumer that processes tasks from Kafka. Suitable for horizontal scaling in Kubernetes.
+
+#### For Local Development (multiple consumers)
+
+```bash
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+Runs 5 consumers in separate processes. Suitable for local development or deployment without orchestration.
+
+**Parameters**:
+
+- `--consumers-count` — number of consumers to run (default: 1)
+
+## Examples
+
+### Minimal Task Registration
+
+```python
+from bazis.contrib.async_background.broker import get_broker_for_consumer
+from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
+from bazis.contrib.async_background.utils import set_and_publish_status_async
+from pydantic import BaseModel
+
+
+class DemoPayload(BaseModel):
+    message: str
+
+
+@get_broker_for_consumer().subscriber("my_app_background_tasks")
+async def consumer_demo(task: KafkaTask[DemoPayload]):
+    await set_and_publish_status_async(
+        task_id=task.task_id,
+        channel_name=task.channel_name,
+        status=TaskStatus.COMPLETED,
+        response={"echo": task.payload.model_dump()},
+    )
+```
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Bazis Documentation](https://github.com/ecofuture-tech/bazis) — main repository
+- [Bazis Async Background Repository](https://github.com/ecofuture-tech/bazis-async-background) — package repository
+- [Issue Tracker](https://github.com/ecofuture-tech/bazis-async-background/issues) — report bugs or request features
+- [Apache Kafka](https://kafka.apache.org/) — Kafka documentation

bazis_async_background-2.2.0/README.md

@@ -0,0 +1,244 @@
+# Bazis Async Background
+
+[![PyPI version](https://img.shields.io/pypi/v/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bazis-async-background.svg)](https://pypi.org/project/bazis-async-background/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+Core background task framework for Bazis. It provides Kafka broker helpers, task schemas, status storage in Redis, and a base API to retrieve task results.
+
+## Quick Start
+
+```bash
+# Install the package
+uv add bazis-async-background
+
+# Configure environment variables / settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# Run consumer in Kubernetes
+python manage.py kafka_consumer_single
+
+# Run multiple consumers locally
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+## Table of Contents
+
+- [Description](#description)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Architecture](#architecture)
+- [Configuration](#configuration)
+  - [Environment Variables / Settings](#environment-variables--settings)
+  - [Route Registration](#route-registration)
+- [Usage](#usage)
+  - [Running Consumers](#running-consumers)
+- [Examples](#examples)
+- [License](#license)
+- [Links](#links)
+
+## Description
+
+**Bazis Async Background** is a core package for running background tasks in the Bazis framework. It includes:
+
+- **Kafka Producer** — sending tasks to Kafka queue
+- **Kafka Consumer** — processing tasks from the queue
+- **Redis storage** — storing task execution results
+- **API endpoint** — retrieving results by task_id
+
+## Requirements
+
+- **Python**: 3.12+
+- **bazis**: latest version
+- **PostgreSQL**: 12+
+- **Redis**: For storing results and caching
+- **Kafka**: For task queue
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add bazis-async-background
+```
+
+### Using pip
+
+```bash
+pip install bazis-async-background
+```
+
+## Running Tests
+
+Run from the project root:
+
+```bash
+docker compose -f sample/docker-compose.test.yml up --build --exit-code-from bazis-async-background-pytest --attach bazis-async-background-pytest --attach bazis-async-background-consumer-test
+```
+
+This waits for the pytest container to finish and streams logs only from the Python containers, so test completion and output are easy to follow.
+
+## Architecture
+
+```
+┌─────────────┐
+│   Client    │
+└──────┬──────┘
+       │ Background task request
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│ (Async Background)  │
+└──────┬──────────────┘
+       │ 1. Return task_id (202)
+       │ 2. Send to Kafka
+       ▼
+┌─────────────────────┐
+│   Kafka Topic       │
+│ (async_background)  │
+└──────┬──────────────┘
+       │
+       │ Consumer polls
+       ▼
+┌─────────────────────┐
+│  Kafka Consumer     │
+│  (Background Worker)│
+└──────┬──────────────┘
+       │ 3. Process task
+       │ 4. Save result to Redis
+       ▼
+┌─────────────────────┐
+│      Redis          │
+│   (Results Store)   │
+└──────┬──────────────┘
+       │
+       │ 5. GET /async_background_response/{task_id}/
+       ▼
+┌─────────────────────┐
+│   API Endpoint      │
+│   (Get Result)      │
+└─────────────────────┘
+```
+
+## Configuration
+
+### Environment Variables / Settings
+
+Add to your `.env` or `settings.py`:
+
+```bash
+# Required settings
+INSTALLED_APPS='["bazis.contrib.async_background", ...]'
+BAZIS_CONFIG_APPS='["bazis.contrib.async_background", ...]'
+KAFKA_TASKS='["my_app.background.tasks"]'
+
+# Kafka settings
+KAFKA_BOOTSTRAP_SERVERS=localhost:9093
+KAFKA_TOPIC_ASYNC_REQUEST=my_app_background_tasks
+KAFKA_GROUP_ID=my_app_background
+
+# Optional settings
+KAFKA_CONSUMER_LIFETIME_SEC=900           # Consumer lifetime (15 minutes)
+KAFKA_CONSUMER_LIFETIME_JITTER_SEC=180    # Random deviation (3 minutes)
+KAFKA_AUTO_OFFSET_RESET=latest
+KAFKA_ENABLE_AUTO_COMMIT=true
+KAFKA_AUTO_COMMIT_INTERVAL_MS=5000
+KAFKA_LOG_LEVEL=INFO
+```
+
+**Parameters**:
+
+- `KAFKA_TASKS` — dotted module paths imported by the consumer to register tasks
+- `KAFKA_BOOTSTRAP_SERVERS` — Kafka broker address
+- `KAFKA_TOPIC_ASYNC_REQUEST` — topic for async tasks
+- `KAFKA_GROUP_ID` — consumer group
+- `KAFKA_CONSUMER_LIFETIME_SEC` — consumer working time before restart
+- `KAFKA_CONSUMER_LIFETIME_JITTER_SEC` — random deviation to avoid simultaneous restart
+- `KAFKA_AUTO_OFFSET_RESET` — Kafka auto offset reset policy
+- `KAFKA_ENABLE_AUTO_COMMIT` — Kafka auto-commit toggle
+- `KAFKA_AUTO_COMMIT_INTERVAL_MS` — auto-commit interval in ms
+- `KAFKA_LOG_LEVEL` — log level for consumers
+
+### Route Registration
+
+Add the route for getting results to your `router.py`:
+
+```python
+from bazis.core.routing import BazisRouter
+
+router = BazisRouter(prefix='/api/v1')
+
+# Register background task results route
+router.register('bazis.contrib.async_background.router')
+```
+
+This adds the endpoint: `GET /api/v1/async_background_response/{task_id}/`
+
+## Usage
+
+### Running Consumers
+
+#### For Kubernetes (one consumer per pod)
+
+```bash
+python manage.py kafka_consumer_single
+```
+
+Runs one consumer that processes tasks from Kafka. Suitable for horizontal scaling in Kubernetes.
+
+#### For Local Development (multiple consumers)
+
+```bash
+python manage.py kafka_consumer_multiple --consumers-count=5
+```
+
+Runs 5 consumers in separate processes. Suitable for local development or deployment without orchestration.
+
+**Parameters**:
+
+- `--consumers-count` — number of consumers to run (default: 1)
+
+## Examples
+
+### Minimal Task Registration
+
+```python
+from bazis.contrib.async_background.broker import get_broker_for_consumer
+from bazis.contrib.async_background.schemas import KafkaTask, TaskStatus
+from bazis.contrib.async_background.utils import set_and_publish_status_async
+from pydantic import BaseModel
+
+
+class DemoPayload(BaseModel):
+    message: str
+
+
+@get_broker_for_consumer().subscriber("my_app_background_tasks")
+async def consumer_demo(task: KafkaTask[DemoPayload]):
+    await set_and_publish_status_async(
+        task_id=task.task_id,
+        channel_name=task.channel_name,
+        status=TaskStatus.COMPLETED,
+        response={"echo": task.payload.model_dump()},
+    )
+```
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Bazis Documentation](https://github.com/ecofuture-tech/bazis) — main repository
+- [Bazis Async Background Repository](https://github.com/ecofuture-tech/bazis-async-background) — package repository
+- [Issue Tracker](https://github.com/ecofuture-tech/bazis-async-background/issues) — report bugs or request features
+- [Apache Kafka](https://kafka.apache.org/) — Kafka documentation

bazis_async_background-2.2.0/bazis/contrib/async_background/__init__.py

@@ -0,0 +1,21 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# 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.
+
+from importlib.metadata import version
+
+
+try:
+    __version__ = version('bazis-async-background')
+except Exception:
+    __version__ = 'dev'

bazis_async_background-2.2.0/bazis/contrib/async_background/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '2.2.0'
+__version_tuple__ = version_tuple = (2, 2, 0)
+
+__commit_id__ = commit_id = 'g639234d6d'

bazis_async_background-2.2.0/bazis/contrib/async_background/apps.py

@@ -0,0 +1,23 @@
+# Copyright 2026 EcoFuture Technology Services LLC and contributors
+#
+# 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.
+
+from django.utils.translation import gettext_lazy as _
+
+from bazis.core.utils.apps import BaseConfig
+
+
+class AsyncBackgroundConfig(BaseConfig):
+    name = "bazis.contrib.async_background"
+    verbose_name = _("AsyncBackground")
+    default = True