bazis-author 2.2.0__tar.gz

bazis_author-2.2.0/.dockerignore

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

bazis_author-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_author-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_author-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_author-2.2.0/PKG-INFO

@@ -0,0 +1,589 @@
+Metadata-Version: 2.4
+Name: bazis-author
+Version: 2.2.0
+Summary: Author management module for Bazis framework.
+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-author
+Keywords: bazis,django,fastapi,pydantic,framework,jsonapi,author
+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-users
+Provides-Extra: test
+Requires-Dist: bazis-test-utils; extra == "test"
+Provides-Extra: dev
+Requires-Dist: ruff; extra == "dev"
+
+# Bazis Author
+
+[![PyPI version](https://img.shields.io/pypi/v/bazis-author.svg)](https://pypi.org/project/bazis-author/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/bazis-author.svg)](https://pypi.org/project/bazis-author/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+An extension package for Bazis that provides automatic authorship tracking for models (who created and who updated records).
+
+## Quick Start
+
+```bash
+# Install the package
+uv add bazis-author
+
+# Create model with authorship tracking
+from bazis.contrib.author.models_abstract import AuthorMixin
+from bazis.core.models_abstract import DtMixin, UuidMixin, JsonApiMixin
+from django.db import models
+
+class Article(AuthorMixin, DtMixin, UuidMixin, JsonApiMixin):
+    """Article with author tracking"""
+    title = models.CharField(max_length=255)
+    content = models.TextField()
+    
+    class Meta:
+        verbose_name = 'Article'
+        verbose_name_plural = 'Articles'
+
+# Create route with automatic author population
+from bazis.contrib.author.routes_abstract import AuthorRouteBase
+from django.apps import apps
+
+class ArticleRouteSet(AuthorRouteBase):
+    model = apps.get_model('myapp.Article')
+```
+
+## Table of Contents
+
+- [Description](#description)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Core Components](#core-components)
+  - [Model Mixins](#model-mixins)
+  - [Base Routes](#base-routes)
+  - [Admin Mixins](#admin-mixins)
+- [Usage](#usage)
+  - [Creating Model with Authorship](#creating-model-with-authorship)
+  - [Creating Route with Authorship](#creating-route-with-authorship)
+  - [Admin Setup](#admin-setup)
+- [How It Works](#how-it-works)
+- [Examples](#examples)
+- [License](#license)
+- [Links](#links)
+
+## Description
+
+**Bazis Author** is an extension package for the Bazis framework that provides automatic authorship tracking for records. The package includes:
+
+- **AuthorMixin** — mixin for models adding `author` (who created) and `author_updated` (who updated) fields
+- **AuthorRouteBase** and **AuthorRequiredRouteBase** — base route classes with automatic author field population
+- **AuthorAdminMixin** — admin mixin with convenient filters and readonly fields
+
+The main advantage of the package is fully automatic author field population without the need to write additional code.
+
+**This package requires `bazis` and `bazis-users` packages to be installed.**
+
+## Requirements
+
+- **Python**: 3.12+
+- **bazis**: latest version
+- **bazis-users**: latest version
+- **PostgreSQL**: 12+
+- **Redis**: For caching
+
+## Installation
+
+### Using uv (recommended)
+
+```bash
+uv add bazis-author
+```
+
+### Using pip
+
+```bash
+pip install bazis-author
+```
+
+## Core Components
+
+### Model Mixins
+
+#### AuthorMixin
+
+Mixin for models adding authorship tracking fields.
+
+**Location**: `bazis.contrib.author.models_abstract.AuthorMixin`
+
+**Added fields**:
+
+- `author` — Foreign Key to user who created the record (nullable)
+- `author_updated` — Foreign Key to user who last updated the record (nullable)
+
+**Features**:
+
+- Inherits from `UserMixin`, has access to user context via `CTX_USER_REQUEST`
+- Automatically populates `author` when creating record
+- Automatically updates `author_updated` on every save
+- Fields are optional (nullable), so records can be created without a user
+
+**Example usage**:
+
+```python
+from bazis.contrib.author.models_abstract import AuthorMixin
+from bazis.core.models_abstract import DtMixin, UuidMixin, JsonApiMixin
+from django.db import models
+
+class Document(AuthorMixin, DtMixin, UuidMixin, JsonApiMixin):
+    """Document with authorship tracking"""
+    title = models.CharField('Title', max_length=255)
+    content = models.TextField('Content')
+    
+    class Meta:
+        verbose_name = 'Document'
+        verbose_name_plural = 'Documents'
+```
+
+### Base Routes
+
+#### AuthorRouteMixin
+
+Base mixin for routes that automatically populate author fields.
+
+**Location**: `bazis.contrib.author.routes_abstract.AuthorRouteMixin`
+
+**Features**:
+
+- Excludes `author` and `author_updated` fields from CREATE and UPDATE schemas (they are populated automatically)
+- Uses `hook_before_create` and `hook_before_update` hooks to set author
+- Sets author only for authenticated users
+
+**Methods**:
+
+- `hook_before_create(item)` — sets `author` before creating record
+- `hook_before_update(item)` — sets `author_updated` before updating record
+
+#### AuthorRouteBase
+
+Base route class with authorship support for optional authentication.
+
+**Location**: `bazis.contrib.author.routes_abstract.AuthorRouteBase`
+
+**Inheritance**: `AuthorRouteMixin` + `UserRouteBase`
+
+Use this class when endpoints are accessible to both authenticated and anonymous users.
+
+**Example usage**:
+
+```python
+from bazis.contrib.author.routes_abstract import AuthorRouteBase
+from django.apps import apps
+
+class ArticleRouteSet(AuthorRouteBase):
+    """Route for articles with automatic authorship"""
+    model = apps.get_model('myapp.Article')
+```
+
+#### AuthorRequiredRouteBase
+
+Base route class with authorship support for required authentication.
+
+**Location**: `bazis.contrib.author.routes_abstract.AuthorRequiredRouteBase`
+
+**Inheritance**: `AuthorRouteMixin` + `UserRequiredRouteBase`
+
+Use this class when endpoints require mandatory authentication (return 401 for unauthenticated requests).
+
+**Example usage**:
+
+```python
+from bazis.contrib.author.routes_abstract import AuthorRequiredRouteBase
+from django.apps import apps
+
+class PrivateDocumentRouteSet(AuthorRequiredRouteBase):
+    """Route for private documents (authenticated only)"""
+    model = apps.get_model('myapp.PrivateDocument')
+```
+
+### Admin Mixins
+
+#### AuthorAdminMixin
+
+Mixin for Django admin classes adding convenient work with author fields.
+
+**Location**: `bazis.contrib.author.admin_abstract.AuthorAdminMixin`
+
+**Capabilities**:
+
+- Adds `author__username` to search fields
+- Makes `author` and `author_updated` fields readonly
+- Adds autocomplete filter by author to list view
+- Automatically populates author fields when saving through admin
+
+**Example usage**:
+
+```python
+from django.contrib import admin
+from bazis.contrib.author.admin_abstract import AuthorAdminMixin
+from bazis.core.admin_abstract import DtAdminMixin
+from .models import Article
+
+@admin.register(Article)
+class ArticleAdmin(AuthorAdminMixin, DtAdminMixin, admin.ModelAdmin):
+    list_display = ('id', 'title', 'author', 'author_updated', 'dt_created')
+    search_fields = ('title', 'content')
+```
+
+## Usage
+
+### Creating Model with Authorship
+
+```python
+from bazis.contrib.author.models_abstract import AuthorMixin
+from bazis.core.models_abstract import DtMixin, UuidMixin, JsonApiMixin
+from django.db import models
+
+class Article(AuthorMixin, DtMixin, UuidMixin, JsonApiMixin):
+    """Article with automatic author tracking"""
+    title = models.CharField('Title', max_length=255)
+    content = models.TextField('Content')
+    is_published = models.BooleanField('Published', default=False)
+    
+    class Meta:
+        verbose_name = 'Article'
+        verbose_name_plural = 'Articles'
+    
+    def __str__(self):
+        return self.title
+```
+
+### Creating Route with Authorship
+
+#### For public endpoints (optional authentication)
+
+```python
+from bazis.contrib.author.routes_abstract import AuthorRouteBase
+from django.apps import apps
+
+class ArticleRouteSet(AuthorRouteBase):
+    """
+    Articles can be created by anonymous users.
+    If user is authenticated - author fields will be populated automatically.
+    """
+    model = apps.get_model('myapp.Article')
+```
+
+**Behavior**:
+- Anonymous user creates record → `author` and `author_updated` remain `null`
+- Authenticated user creates record → `author` is automatically populated
+- Any user updates record → `author_updated` is populated if user is authenticated
+
+#### For private endpoints (required authentication)
+
+```python
+from bazis.contrib.author.routes_abstract import AuthorRequiredRouteBase
+from django.apps import apps
+
+class PrivateDocumentRouteSet(AuthorRequiredRouteBase):
+    """
+    Documents are accessible only to authenticated users.
+    Anonymous users will get 401.
+    """
+    model = apps.get_model('myapp.PrivateDocument')
+```
+
+**Behavior**:
+- Anonymous user tries to create/update record → 401 Unauthorized
+- Authenticated user creates record → `author` is automatically populated
+- Authenticated user updates record → `author_updated` is automatically updated
+
+### Admin Setup
+
+```python
+from django.contrib import admin
+from bazis.contrib.author.admin_abstract import AuthorAdminMixin
+from bazis.core.admin_abstract import DtAdminMixin
+from .models import Article
+
+@admin.register(Article)
+class ArticleAdmin(AuthorAdminMixin, DtAdminMixin, admin.ModelAdmin):
+    list_display = ('id', 'title', 'author', 'author_updated', 'is_published', 'dt_created')
+    search_fields = ('title', 'content')
+    list_filter = ('is_published',)
+    readonly_fields = ('dt_created', 'dt_updated')
+```
+
+**What AuthorAdminMixin provides**:
+
+1. **Autocomplete filter by author** in list view
+2. **Search by author username** (`author__username`)
+3. **Readonly fields** `author` and `author_updated` (cannot be edited)
+4. **Automatic population** when saving through admin
+
+## How It Works
+
+### In Models
+
+When calling `save()` on a model with `AuthorMixin`:
+
+1. Check for user presence in `CTX_USER_REQUEST` context
+2. If user exists:
+   - When creating record (`author` is empty) → set `author`
+   - When updating record → update `author_updated`
+3. Call `super().save()` to save
+
+```python
+def save(self, *args, **kwargs):
+    if author := self.CTX_USER_REQUEST.get():
+        if not self.author:
+            self.author = author
+        self.author_updated = author
+    super().save(*args, **kwargs)
+```
+
+### In Routes
+
+When creating/updating record via API:
+
+1. **In CREATE**: `hook_before_create(item)` is triggered
+   - If user is NOT anonymous → set `item.author`
+   
+2. **In UPDATE**: `hook_before_update(item)` is triggered
+   - If user is NOT anonymous → set `item.author_updated`
+
+3. Fields `author` and `author_updated` are **excluded** from CREATE/UPDATE schemas, so client cannot pass them
+
+```python
+fields: dict[ApiAction, SchemaFields] = {
+    CrudApiAction.CREATE: SchemaFields(
+        exclude={'author': None, 'author_updated': None},
+    ),
+    CrudApiAction.UPDATE: SchemaFields(
+        exclude={'author': None, 'author_updated': None},
+    ),
+}
+```
+
+### In Admin
+
+When saving through Django Admin:
+
+1. `save_model()` — sets author from `request.user`
+2. `save_formset()` — sets author for inline models
+
+## Examples
+
+### Complete Application Example
+
+**models.py**:
+```python
+from bazis.contrib.author.models_abstract import AuthorMixin
+from bazis.core.models_abstract import DtMixin, UuidMixin, JsonApiMixin
+from django.db import models
+
+class Article(AuthorMixin, DtMixin, UuidMixin, JsonApiMixin):
+    """Public article"""
+    title = models.CharField('Title', max_length=255)
+    content = models.TextField('Content')
+    is_published = models.BooleanField('Published', default=False)
+    
+    class Meta:
+        verbose_name = 'Article'
+        verbose_name_plural = 'Articles'
+
+class PrivateNote(AuthorMixin, DtMixin, UuidMixin, JsonApiMixin):
+    """Private note (authenticated only)"""
+    title = models.CharField('Title', max_length=255)
+    content = models.TextField('Content')
+    
+    class Meta:
+        verbose_name = 'Note'
+        verbose_name_plural = 'Notes'
+```
+
+**routes.py**:
+```python
+from bazis.contrib.author.routes_abstract import AuthorRouteBase, AuthorRequiredRouteBase
+from django.apps import apps
+
+class ArticleRouteSet(AuthorRouteBase):
+    """Articles accessible to everyone, but author is tracked if user is authenticated"""
+    model = apps.get_model('myapp.Article')
+
+class PrivateNoteRouteSet(AuthorRequiredRouteBase):
+    """Notes accessible only to authenticated users"""
+    model = apps.get_model('myapp.PrivateNote')
+```
+
+**router.py**:
+```python
+from bazis.core.routing import BazisRouter
+from . import routes
+
+router = BazisRouter(tags=['Content'])
+router.register(routes.ArticleRouteSet.as_router())
+router.register(routes.PrivateNoteRouteSet.as_router())
+```
+
+**admin.py**:
+```python
+from django.contrib import admin
+from bazis.contrib.author.admin_abstract import AuthorAdminMixin
+from bazis.core.admin_abstract import DtAdminMixin
+from .models import Article, PrivateNote
+
+@admin.register(Article)
+class ArticleAdmin(AuthorAdminMixin, DtAdminMixin, admin.ModelAdmin):
+    list_display = ('id', 'title', 'author', 'is_published', 'dt_created')
+    search_fields = ('title', 'content')
+    list_filter = ('is_published',)
+
+@admin.register(PrivateNote)
+class PrivateNoteAdmin(AuthorAdminMixin, DtAdminMixin, admin.ModelAdmin):
+    list_display = ('id', 'title', 'author', 'dt_created')
+    search_fields = ('title', 'content')
+```
+
+### API Usage Examples
+
+**Creating article by anonymous user**:
+```bash
+POST /api/v1/content/article/
+Content-Type: application/json
+
+{
+  "data": {
+    "type": "myapp.article",
+    "attributes": {
+      "title": "My Article",
+      "content": "Article content",
+      "is_published": true
+    }
+  }
+}
+
+# Response: 201 Created
+# author and author_updated will be null
+```
+
+**Creating article by authenticated user**:
+```bash
+POST /api/v1/content/article/
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "data": {
+    "type": "myapp.article",
+    "attributes": {
+      "title": "My Article",
+      "content": "Article content",
+      "is_published": true
+    }
+  }
+}
+
+# Response: 201 Created
+# author is automatically set to current user
+```
+
+**Attempting to create private note without authentication**:
+```bash
+POST /api/v1/content/private_note/
+Content-Type: application/json
+
+{
+  "data": {
+    "type": "myapp.privatenote",
+    "attributes": {
+      "title": "Secret Note",
+      "content": "Secret content"
+    }
+  }
+}
+
+# Response: 401 Unauthorized
+```
+
+**Creating private note with authentication**:
+```bash
+POST /api/v1/content/private_note/
+Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+Content-Type: application/json
+
+{
+  "data": {
+    "type": "myapp.privatenote",
+    "attributes": {
+      "title": "Secret Note",
+      "content": "Secret content"
+    }
+  }
+}
+
+# Response: 201 Created
+# author is automatically set to current user
+```
+
+### Authorship Check in Responses
+
+Fields `author` and `author_updated` are returned in the `relationships` block:
+
+```json
+{
+  "data": {
+    "type": "myapp.article",
+    "id": "123e4567-e89b-12d3-a456-426614174000",
+    "attributes": {
+      "title": "My Article",
+      "content": "Article content",
+      "is_published": true
+    },
+    "relationships": {
+      "author": {
+        "data": {
+          "type": "users.user",
+          "id": "456e7890-e89b-12d3-a456-426614174000"
+        }
+      },
+      "author_updated": {
+        "data": {
+          "type": "users.user",
+          "id": "456e7890-e89b-12d3-a456-426614174000"
+        }
+      }
+    }
+  }
+}
+```
+
+## License
+
+Apache License 2.0
+
+See [LICENSE](LICENSE) file for details.
+
+## Links
+
+- [Bazis Documentation](https://github.com/ecofuture-tech/bazis) — main repository
+- [Bazis Users](https://github.com/ecofuture-tech/bazis-users) — user management package
+- [Bazis Author Repository](https://github.com/ecofuture-tech/bazis-author) — package repository
+- [Issue Tracker](https://github.com/ecofuture-tech/bazis-author/issues) — report bugs or request features
+
+## Support
+
+If you have questions or issues:
+- Check the [Bazis documentation](https://github.com/ecofuture-tech/bazis)
+- Search [existing issues](https://github.com/ecofuture-tech/bazis-author/issues)
+- Create a [new issue](https://github.com/ecofuture-tech/bazis-author/issues/new) with detailed information
+
+---
+
+Made with ❤️ by the Bazis team