# CodeFinal Shared Backend Utilities
Shared Django utilities, models, serializers, and validation that mirror the TypeScript shared types. This package ensures consistency between your Django backend and React frontend for the CodeFinal fire inspection system.
## Installation
```bash
# From your Django project directory
pip install -e /path/to/packages/backend-utils
```
Or add to your `requirements.txt`:
```txt
-e /path/to/packages/backend-utils
```
## Quick Start
### 1. Update Your Django User Model
Replace your existing Django user model imports with shared utilities:
```python
# accounts/models.py
from codefinal_shared import (
UUIDMixin, TimestampMixin, AccountFieldsMixin,
SharedUserManager, ROLE_CHOICES, STATUS_CHOICES
)
from django.contrib.auth.models import AbstractUser
class CustomUser(AbstractUser, UUIDMixin, TimestampMixin, AccountFieldsMixin):
objects = SharedUserManager()
class Meta:
ordering = ["-created_at"]
```
### 2. Update Your Serializers
Use shared serializers for consistent API responses:
```python
# accounts/serializers.py
from codefinal_shared import (
AccountSerializer, LoginRequestSerializer, LoginResponseSerializer,
create_api_response, create_error_response
)
class UserSerializer(AccountSerializer):
class Meta(AccountSerializer.Meta):
model = CustomUser
# Add any additional fields specific to your implementation
```
### 3. Update Your Views
Use shared authentication and validation utilities:
```python
# accounts/views.py
from codefinal_shared import (
authenticate_user, AuthTokenManager,
validate_login_data, create_api_response
)
@api_view(['POST'])
def login_view(request):
email = request.data.get('email')
password = request.data.get('password')
# Use shared authentication
result = authenticate_user(email, password)
return Response(result, status=200 if result['success'] else 400)
```
## Core Components
### Constants
```python
from codefinal_shared import AccountRole, AccountStatus, SubscriptionLevel
# Use enum values that match TypeScript
user.role = AccountRole.ADMINISTRATOR.value
user.status = AccountStatus.ACTIVE.value
```
### Model Mixins
```python
from codefinal_shared import UUIDMixin, TimestampMixin, AccountFieldsMixin
class YourModel(UUIDMixin, TimestampMixin):
# Automatically gets UUID primary key and created_at/updated_at fields
pass
```
### Serializers
```python
from codefinal_shared import AccountSerializer, create_api_response
# Consistent API responses
return create_api_response(
data=user_data,
message="Operation successful"
)
```
### Validation
```python
from codefinal_shared import validate_login_data, validate_email_format
# Validation that matches frontend Zod schemas
validation_result = validate_login_data(email, password)
if not validation_result['valid']:
return create_error_response("Validation failed", validation_result['errors'])
```
### Authentication
```python
from codefinal_shared import AuthTokenManager, TwoFactorAuthMixin
# JWT token management
tokens = AuthTokenManager.create_tokens_for_user(user)
# Two-factor authentication
class CustomUser(AbstractUser, TwoFactorAuthMixin):
def setup_2fa(self):
return self.enable_two_factor()
```
## Features
### ✅ Type Consistency
All utilities match the shared TypeScript types exactly, ensuring frontend and backend stay in sync.
### ✅ Validation Matching
Python validation functions mirror the Zod schemas from the frontend, providing identical validation logic.
### ✅ API Response Format
Consistent API response structure matching `TypeScript ApiResponse` and `ApiError` interfaces.
### ✅ Authentication Utilities
Complete JWT token management and two-factor authentication support.
### ✅ Django Integration
Drop-in replacements for common Django patterns with enhanced type safety.
## Available Utilities
### Models
- `UUIDMixin` - UUID primary key
- `TimestampMixin` - created_at/updated_at fields
- `AccountFieldsMixin` - Complete user account fields
- `TenantAwareMixin` - Subscription level support
- `SharedUserManager` - Consistent user creation
### Serializers
- `AccountSerializer` - User account serialization
- `LoginRequestSerializer` - Login request validation
- `LoginResponseSerializer` - Login response format
- `PaginatedResponseSerializer` - Paginated API responses
### Validation
- `validate_email_format()` - Email validation matching frontend
- `validate_password_strength()` - Password strength checking
- `validate_login_data()` - Complete login validation
- `DjangoFormValidator` - Django form integration
### Authentication
- `AuthTokenManager` - JWT token creation/management
- `TwoFactorAuthMixin` - TOTP two-factor authentication
- `authenticate_user()` - Complete authentication flow
- `create_user_permissions_list()` - Permission management
### Constants
- `AccountRole` - User roles enum
- `AccountStatus` - Account status enum
- `SubscriptionLevel` - Subscription level enum
- `ROLE_CHOICES`, `STATUS_CHOICES` - Django choices
## Migration Guide
### From Existing Django Project
1. **Install the package**:
```bash
pip install -e /path/to/packages/backend-utils
```
2. **Update your models** to use shared mixins:
```python
# Before
class CustomUser(AbstractUser):
id = models.UUIDField(primary_key=True, default=uuid.uuid4)
role = models.CharField(max_length=100, choices=ROLE_CHOICES)
# After
from codefinal_shared import UUIDMixin, AccountFieldsMixin
class CustomUser(AbstractUser, UUIDMixin, AccountFieldsMixin):
pass # Fields are provided by mixins
```
3. **Update serializers** to use shared formats:
```python
# Before
class UserSerializer(serializers.ModelSerializer):
# Custom serialization logic
# After
from codefinal_shared import AccountSerializer
class UserSerializer(AccountSerializer):
# Inherits consistent serialization
```
4. **Update views** to use shared utilities:
```python
# Before
def login_view(request):
# Custom authentication logic
# After
from codefinal_shared import authenticate_user
def login_view(request):
return authenticate_user(email, password)
```
## Benefits
### 🎯 **Type Safety**
Ensures your Django models exactly match the TypeScript interfaces used in the frontend.
### 🔄 **Consistency**
Identical validation, serialization, and response formats between frontend and backend.
### 🚀 **Productivity**
Drop-in utilities eliminate boilerplate code and reduce development time.
### 🛡️ **Reliability**
Shared validation logic prevents frontend/backend mismatches that cause bugs.
### 📈 **Scalability**
Easily extend utilities as your application grows, with changes automatically reflected across projects.
## License
MIT License - matches the main CodeFinal project licensing.
Raw data
{
"_id": null,
"home_page": null,
"name": "finstack-backend",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "finstack, django, authentication, shared, utilities, backend, api",
"author": null,
"author_email": "FeatherShark Team <team@feathershark.com>",
"download_url": "https://files.pythonhosted.org/packages/08/bf/3bf03342c42c335c1100d859b761bdb43eeee353dfc86f66fc3ec3d5906b/finstack_backend-1.0.5.tar.gz",
"platform": null,
"description": "# CodeFinal Shared Backend Utilities\n\nShared Django utilities, models, serializers, and validation that mirror the TypeScript shared types. This package ensures consistency between your Django backend and React frontend for the CodeFinal fire inspection system.\n\n## Installation\n\n```bash\n# From your Django project directory\npip install -e /path/to/packages/backend-utils\n```\n\nOr add to your `requirements.txt`:\n```txt\n-e /path/to/packages/backend-utils\n```\n\n## Quick Start\n\n### 1. Update Your Django User Model\n\nReplace your existing Django user model imports with shared utilities:\n\n```python\n# accounts/models.py\nfrom codefinal_shared import (\n UUIDMixin, TimestampMixin, AccountFieldsMixin, \n SharedUserManager, ROLE_CHOICES, STATUS_CHOICES\n)\nfrom django.contrib.auth.models import AbstractUser\n\nclass CustomUser(AbstractUser, UUIDMixin, TimestampMixin, AccountFieldsMixin):\n objects = SharedUserManager()\n \n class Meta:\n ordering = [\"-created_at\"]\n```\n\n### 2. Update Your Serializers\n\nUse shared serializers for consistent API responses:\n\n```python\n# accounts/serializers.py\nfrom codefinal_shared import (\n AccountSerializer, LoginRequestSerializer, LoginResponseSerializer,\n create_api_response, create_error_response\n)\n\nclass UserSerializer(AccountSerializer):\n class Meta(AccountSerializer.Meta):\n model = CustomUser\n # Add any additional fields specific to your implementation\n```\n\n### 3. Update Your Views\n\nUse shared authentication and validation utilities:\n\n```python\n# accounts/views.py\nfrom codefinal_shared import (\n authenticate_user, AuthTokenManager, \n validate_login_data, create_api_response\n)\n\n@api_view(['POST'])\ndef login_view(request):\n email = request.data.get('email')\n password = request.data.get('password')\n \n # Use shared authentication\n result = authenticate_user(email, password)\n \n return Response(result, status=200 if result['success'] else 400)\n```\n\n## Core Components\n\n### Constants\n```python\nfrom codefinal_shared import AccountRole, AccountStatus, SubscriptionLevel\n\n# Use enum values that match TypeScript\nuser.role = AccountRole.ADMINISTRATOR.value\nuser.status = AccountStatus.ACTIVE.value\n```\n\n### Model Mixins\n```python\nfrom codefinal_shared import UUIDMixin, TimestampMixin, AccountFieldsMixin\n\nclass YourModel(UUIDMixin, TimestampMixin):\n # Automatically gets UUID primary key and created_at/updated_at fields\n pass\n```\n\n### Serializers\n```python\nfrom codefinal_shared import AccountSerializer, create_api_response\n\n# Consistent API responses\nreturn create_api_response(\n data=user_data,\n message=\"Operation successful\"\n)\n```\n\n### Validation\n```python\nfrom codefinal_shared import validate_login_data, validate_email_format\n\n# Validation that matches frontend Zod schemas\nvalidation_result = validate_login_data(email, password)\nif not validation_result['valid']:\n return create_error_response(\"Validation failed\", validation_result['errors'])\n```\n\n### Authentication\n```python\nfrom codefinal_shared import AuthTokenManager, TwoFactorAuthMixin\n\n# JWT token management\ntokens = AuthTokenManager.create_tokens_for_user(user)\n\n# Two-factor authentication\nclass CustomUser(AbstractUser, TwoFactorAuthMixin):\n def setup_2fa(self):\n return self.enable_two_factor()\n```\n\n## Features\n\n### \u2705 Type Consistency\nAll utilities match the shared TypeScript types exactly, ensuring frontend and backend stay in sync.\n\n### \u2705 Validation Matching\nPython validation functions mirror the Zod schemas from the frontend, providing identical validation logic.\n\n### \u2705 API Response Format\nConsistent API response structure matching `TypeScript ApiResponse` and `ApiError` interfaces.\n\n### \u2705 Authentication Utilities\nComplete JWT token management and two-factor authentication support.\n\n### \u2705 Django Integration\nDrop-in replacements for common Django patterns with enhanced type safety.\n\n## Available Utilities\n\n### Models\n- `UUIDMixin` - UUID primary key\n- `TimestampMixin` - created_at/updated_at fields \n- `AccountFieldsMixin` - Complete user account fields\n- `TenantAwareMixin` - Subscription level support\n- `SharedUserManager` - Consistent user creation\n\n### Serializers \n- `AccountSerializer` - User account serialization\n- `LoginRequestSerializer` - Login request validation\n- `LoginResponseSerializer` - Login response format\n- `PaginatedResponseSerializer` - Paginated API responses\n\n### Validation\n- `validate_email_format()` - Email validation matching frontend\n- `validate_password_strength()` - Password strength checking\n- `validate_login_data()` - Complete login validation\n- `DjangoFormValidator` - Django form integration\n\n### Authentication\n- `AuthTokenManager` - JWT token creation/management\n- `TwoFactorAuthMixin` - TOTP two-factor authentication\n- `authenticate_user()` - Complete authentication flow\n- `create_user_permissions_list()` - Permission management\n\n### Constants\n- `AccountRole` - User roles enum\n- `AccountStatus` - Account status enum \n- `SubscriptionLevel` - Subscription level enum\n- `ROLE_CHOICES`, `STATUS_CHOICES` - Django choices\n\n## Migration Guide\n\n### From Existing Django Project\n\n1. **Install the package**:\n ```bash\n pip install -e /path/to/packages/backend-utils\n ```\n\n2. **Update your models** to use shared mixins:\n ```python\n # Before\n class CustomUser(AbstractUser):\n id = models.UUIDField(primary_key=True, default=uuid.uuid4)\n role = models.CharField(max_length=100, choices=ROLE_CHOICES)\n \n # After \n from codefinal_shared import UUIDMixin, AccountFieldsMixin\n class CustomUser(AbstractUser, UUIDMixin, AccountFieldsMixin):\n pass # Fields are provided by mixins\n ```\n\n3. **Update serializers** to use shared formats:\n ```python\n # Before\n class UserSerializer(serializers.ModelSerializer):\n # Custom serialization logic\n \n # After\n from codefinal_shared import AccountSerializer\n class UserSerializer(AccountSerializer):\n # Inherits consistent serialization\n ```\n\n4. **Update views** to use shared utilities:\n ```python\n # Before\n def login_view(request):\n # Custom authentication logic\n \n # After\n from codefinal_shared import authenticate_user\n def login_view(request):\n return authenticate_user(email, password)\n ```\n\n## Benefits\n\n### \ud83c\udfaf **Type Safety**\nEnsures your Django models exactly match the TypeScript interfaces used in the frontend.\n\n### \ud83d\udd04 **Consistency** \nIdentical validation, serialization, and response formats between frontend and backend.\n\n### \ud83d\ude80 **Productivity**\nDrop-in utilities eliminate boilerplate code and reduce development time.\n\n### \ud83d\udee1\ufe0f **Reliability**\nShared validation logic prevents frontend/backend mismatches that cause bugs.\n\n### \ud83d\udcc8 **Scalability**\nEasily extend utilities as your application grows, with changes automatically reflected across projects.\n\n## License\n\nMIT License - matches the main CodeFinal project licensing. \n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Shared backend utilities for FinStack applications",
"version": "1.0.5",
"project_urls": {
"Bug Tracker": "https://github.com/FeatherShark/codefinal/issues",
"Documentation": "https://github.com/FeatherShark/codefinal/tree/feature/COD-141-shared-component-library/packages/backend-utils#readme",
"Homepage": "https://github.com/FeatherShark/codefinal/tree/feature/COD-141-shared-component-library/packages/backend-utils",
"Repository": "https://github.com/FeatherShark/codefinal/tree/feature/COD-141-shared-component-library"
},
"split_keywords": [
"finstack",
" django",
" authentication",
" shared",
" utilities",
" backend",
" api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1989d7670196a03714b6671914c9297202431e0df4ad0eaf5471f8ebb5f335b8",
"md5": "fe9fc228190d08f84cb465f5b21868f9",
"sha256": "57f9db3e51c1b3f8b348a8d079a3e3eac63e96f4661129206e0f21b5f8f3ca01"
},
"downloads": -1,
"filename": "finstack_backend-1.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe9fc228190d08f84cb465f5b21868f9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 18634,
"upload_time": "2025-09-02T19:35:11",
"upload_time_iso_8601": "2025-09-02T19:35:11.180149Z",
"url": "https://files.pythonhosted.org/packages/19/89/d7670196a03714b6671914c9297202431e0df4ad0eaf5471f8ebb5f335b8/finstack_backend-1.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "08bf3bf03342c42c335c1100d859b761bdb43eeee353dfc86f66fc3ec3d5906b",
"md5": "c137d616b0257a69db1e035c9d1aa34b",
"sha256": "ec9b932b71280994b821e8ad0f78439e9735b4352d82c832d0b2b1e753d7940c"
},
"downloads": -1,
"filename": "finstack_backend-1.0.5.tar.gz",
"has_sig": false,
"md5_digest": "c137d616b0257a69db1e035c9d1aa34b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 18342,
"upload_time": "2025-09-02T19:35:12",
"upload_time_iso_8601": "2025-09-02T19:35:12.015688Z",
"url": "https://files.pythonhosted.org/packages/08/bf/3bf03342c42c335c1100d859b761bdb43eeee353dfc86f66fc3ec3d5906b/finstack_backend-1.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-02 19:35:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FeatherShark",
"github_project": "codefinal",
"github_not_found": true,
"lcname": "finstack-backend"
}
JSON
