django-nativemojo 0.1.15__py3-none-any.whl → 0.1.17__py3-none-any.whl

mojo/serializers/advanced/README.md

@@ -1,363 +0,0 @@
-# Advanced Django Model Serializer
-
-A comprehensive serialization library for Django models and QuerySets with support for multiple output formats, performance optimizations, and advanced configuration through `RestMeta.GRAPHS`.
-
-## Features
-
-- **RestMeta.GRAPHS Configuration**: Use declarative graph configurations for consistent serialization
-- **Multiple Output Formats**: JSON, CSV, Excel, HTML debug views
-- **Performance Optimizations**: Caching, select_related, streaming responses
-- **Nested Relationships**: Deep serialization of related models
-- **Custom Fields**: Support for methods, properties, and computed values
-- **Pagination & Sorting**: Built-in collection handling with pagination
-- **Localization**: Field-level formatting and localization
-
-## Quick Start
-
-### Basic Usage
-
-```python
-from mojo.serializers.advanced import AdvancedGraphSerializer, CollectionSerializer
-
-# Serialize a single model instance
-user = User.objects.get(pk=1)
-serializer = AdvancedGraphSerializer(user, graph="detail")
-data = serializer.serialize()
-
-# Serialize a QuerySet
-users = User.objects.all()
-serializer = CollectionSerializer(users, graph="list", size=25)
-response_data = serializer.serialize()
-
-# Create HTTP response
-response = serializer.to_response(request)
-```
-
-### RestMeta.GRAPHS Configuration
-
-Define serialization graphs in your Django models:
-
-```python
-class User(models.Model):
-    name = models.CharField(max_length=100)
-    email = models.EmailField()
-    profile = models.OneToOneField('Profile', on_delete=models.CASCADE)
-    posts = models.ForeignKey('Post', related_name='author')
-    created = models.DateTimeField(auto_now_add=True)
-
-    class RestMeta:
-        GRAPHS = {
-            "default": {
-                "fields": ["id", "name", "email", "created"],
-            },
-            "list": {
-                "fields": ["id", "name", "email"],
-                "extra": [
-                    ("get_full_name", "full_name"),  # Method with alias
-                    "post_count",  # Property or method
-                ]
-            },
-            "detail": {
-                "fields": ["id", "name", "email", "created"],
-                "extra": ["get_full_name", "is_active"],
-                "graphs": {
-                    "profile": "summary",  # Related object with sub-graph
-                    "posts": "list",       # Related QuerySet
-                }
-            },
-            "export": {
-                "fields": ["id", "name", "email", "created"],
-                "extra": [("profile.bio", "biography")],  # Nested field access
-            }
-        }
-
-    def get_full_name(self):
-        return f"{self.first_name} {self.last_name}"
-
-    @property
-    def post_count(self):
-        return self.posts.count()
-
-class Profile(models.Model):
-    user = models.OneToOneField(User, on_delete=models.CASCADE)
-    bio = models.TextField()
-    avatar = models.ImageField()
-
-    class RestMeta:
-        GRAPHS = {
-            "summary": {
-                "fields": ["bio"],
-                "extra": ["avatar_url"]
-            }
-        }
-
-    def avatar_url(self):
-        return self.avatar.url if self.avatar else None
-```
-
-## Advanced Usage
-
-### Multiple Output Formats
-
-```python
-from mojo.serializers.advanced import (
-    serialize, to_response, to_csv_response, to_excel_response
-)
-
-# Auto-detect format from request
-def user_list_view(request):
-    users = User.objects.all()
-    return to_response(users, graph="list", request=request)
-
-# Force specific formats
-def user_csv_export(request):
-    users = User.objects.all()
-    return to_csv_response(
-        users,
-        fields=["name", "email", "created"],
-        filename="users.csv",
-        request=request
-    )
-
-def user_excel_export(request):
-    users = User.objects.all()
-    return to_excel_response(
-        users,
-        graph="export",
-        filename="users.xlsx",
-        request=request
-    )
-```
-
-### Performance Optimizations
-
-```python
-# Automatic select_related for foreign keys
-users = User.objects.all()  # Will auto-add select_related('profile')
-serializer = AdvancedGraphSerializer(users, graph="detail", many=True)
-
-# Caching for repeated serialization
-cache = {}
-for user in users:
-    data = AdvancedGraphSerializer(user, graph="detail", cache=cache).serialize()
-
-# Streaming responses for large datasets
-def large_export(request):
-    large_queryset = User.objects.all()  # 100k+ records
-    return to_csv_response(
-        large_queryset,
-        fields=["name", "email"],
-        filename="all_users.csv",
-        stream=True  # Enables streaming
-    )
-```
-
-### Collection Serialization with Pagination
-
-```python
-from mojo.serializers.advanced import CollectionSerializer
-
-def paginated_users(request):
-    users = User.objects.all()
-
-    serializer = CollectionSerializer(
-        users,
-        graph="list",
-        size=request.GET.get('size', 25),
-        start=request.GET.get('start', 0),
-        sort=request.GET.get('sort', 'name'),
-        request=request
-    )
-
-    return serializer.to_response()
-
-# Response format:
-{
-    "data": [...],
-    "status": true,
-    "count": 1500,
-    "size": 25,
-    "start": 0,
-    "sort": ["name"],
-    "graph": "list",
-    "datetime": 1640995200
-}
-```
-
-### Custom Localization
-
-```python
-from mojo.serializers.advanced.formats.localizers import register_localizer
-
-# Register custom localizer
-@register_localizer('currency_eur')
-def format_euro(value, extra=None):
-    return f"€{value:.2f}"
-
-# Use in CSV/Excel export
-csv_response = to_csv_response(
-    Product.objects.all(),
-    fields=['name', 'price'],
-    localize={'price': 'currency_eur'},
-    filename='products.csv'
-)
-```
-
-### Response Helpers
-
-```python
-from mojo.serializers.advanced import (
-    rest_success, rest_error, rest_not_found, rest_permission_denied
-)
-
-def api_view(request):
-    try:
-        user = User.objects.get(pk=request.GET['id'])
-        data = serialize(user, graph="detail")
-        return rest_success(request, data)
-    except User.DoesNotExist:
-        return rest_not_found(request, "User not found")
-    except PermissionError:
-        return rest_permission_denied(request, "Access denied")
-    except Exception as e:
-        return rest_error(request, str(e))
-```
-
-## Configuration Options
-
-### Serializer Options
-
-```python
-serializer = AdvancedGraphSerializer(
-    instance=user,
-    graph="detail",           # Graph configuration to use
-    many=False,               # Whether serializing multiple objects
-    request=request,          # Django request for context
-    cache={},                 # Shared cache for performance
-    format="json"             # Output format hint
-)
-```
-
-### Collection Options
-
-```python
-serializer = CollectionSerializer(
-    queryset=users,
-    graph="list",             # Graph configuration
-    size=25,                  # Page size
-    start=0,                  # Start offset
-    sort="name,-created",     # Sort fields (- for descending)
-    format="json",            # Output format
-    request=request           # Django request
-)
-```
-
-### Export Options
-
-```python
-# CSV Export
-csv_response = to_csv_response(
-    queryset,
-    fields=['name', 'email'],     # Fields to include
-    filename='export.csv',        # Download filename
-    headers=['Name', 'Email'],    # Custom column headers
-    localize={'date': 'date|%Y-%m-%d'},  # Field localization
-    stream=True                   # Enable streaming for large datasets
-)
-
-# Excel Export
-excel_response = to_excel_response(
-    queryset,
-    fields=['name', 'email', 'created'],
-    filename='export.xlsx',
-    sheet_name='Users',
-    freeze_panes=True,           # Freeze header row
-    auto_width=True              # Auto-adjust column widths
-)
-```
-
-## Graph Configuration Reference
-
-### Field Types
-
-```python
-class RestMeta:
-    GRAPHS = {
-        "example": {
-            # Basic model fields
-            "fields": ["id", "name", "email"],
-
-            # Extra fields (methods, properties, computed values)
-            "extra": [
-                "method_name",                    # Simple method/property
-                ("method_name", "alias"),         # Method with alias
-                ("nested.field", "flat_name"),   # Nested field access
-            ],
-
-            # Related object graphs
-            "graphs": {
-                "foreign_key_field": "sub_graph_name",
-                "many_to_many_field": "list_graph",
-                "reverse_fk": "related_graph"
-            }
-        }
-    }
-```
-
-### Nested Field Access
-
-```python
-# Access nested fields with dot notation
-"extra": [
-    ("user.profile.bio", "biography"),
-    ("metadata.category.name", "category"),
-    ("settings.preferences.theme", "theme")
-]
-```
-
-## Performance Tips
-
-1. **Use select_related**: The serializer automatically applies `select_related()` for foreign keys in your graph
-2. **Enable caching**: Pass a shared cache dictionary when serializing multiple related objects
-3. **Stream large exports**: Set `stream=True` for CSV exports with >1000 records
-4. **Optimize graphs**: Keep graph configurations focused - avoid over-fetching data
-5. **Use pagination**: Always paginate large QuerySets with CollectionSerializer
-
-## API Reference
-
-### Core Classes
-
-- `AdvancedGraphSerializer`: Main serializer for single instances or lists
-- `CollectionSerializer`: Specialized serializer for QuerySets with pagination
-- `ResponseFormatter`: HTTP response handler for multiple formats
-
-### Format Handlers
-
-- `JsonFormatter`: Enhanced JSON serialization with ujson support
-- `CsvFormatter`: CSV export with streaming support
-- `ExcelFormatter`: Excel export with openpyxl
-- `ResponseFormatter`: Multi-format HTTP response handler
-
-### Convenience Functions
-
-- `serialize()`: Universal serialization function
-- `to_response()`: Quick HTTP response generation
-- `to_csv_response()`: CSV export response
-- `to_excel_response()`: Excel export response
-
-### Response Helpers
-
-- `rest_success()`, `rest_error()`: Status responses
-- `rest_not_found()`, `rest_permission_denied()`: Error responses
-- `get_cached_count()`: Cached QuerySet counting
-
-## Requirements
-
-- Django 3.2+
-- Python 3.8+
-- ujson (optional, for better JSON performance)
-- openpyxl (optional, for Excel export)
-
-## License
-
-This project is part of the Django Mojo framework.

mojo/serializers/advanced/__init__.py

@@ -1,247 +0,0 @@
-"""
-Advanced Django Model and QuerySet Serializer
-
-This module provides comprehensive serialization capabilities for Django models and QuerySets
-with support for:
-
-- RestMeta.GRAPHS configuration
-- Multiple output formats (JSON, CSV, Excel, HTML)
-- Nested relationships and custom fields
-- Performance optimizations with caching and select_related
-- Pagination and sorting for collections
-- Streaming responses for large datasets
-- Localization and field formatting
-
-Main Classes:
-    AdvancedGraphSerializer: Serialize single model instances or lists
-    CollectionSerializer: Serialize QuerySets with pagination and sorting
-    ResponseFormatter: Handle HTTP responses in multiple formats
-
-Usage Examples:
-    # Serialize a single model instance
-    serializer = AdvancedGraphSerializer(user, graph="detail")
-    data = serializer.serialize()
-
-    # Serialize a QuerySet
-    serializer = CollectionSerializer(User.objects.all(), graph="list")
-    response = serializer.to_response(request)
-
-    # Export to CSV
-    csv_response = rest_csv(request, User.objects.all(), fields=['name', 'email'])
-"""
-
-from .serializer import (
-    AdvancedGraphSerializer,
-    CollectionSerializer,
-    serialize_model,
-    serialize_collection,
-    serialize_to_response,
-    timeit
-)
-
-from .formats import (
-    JsonFormatter,
-    CsvFormatter,
-    ExcelFormatter,
-    ResponseFormatter,
-    get_formatter
-)
-
-from .formats.json import (
-    to_json,
-    to_pretty_json,
-    to_compact_json,
-    ExtendedJSONEncoder
-)
-
-from .formats.csv import (
-    generate_csv,
-    generate_csv_stream,
-    serialize_to_csv
-)
-
-from .formats.excel import (
-    generate_excel,
-    serialize_to_excel,
-    create_multi_sheet_excel,
-    qsetToExcel  # Legacy compatibility
-)
-
-from .formats.response import (
-    rest_status,
-    rest_success,
-    rest_error,
-    rest_permission_denied,
-    rest_not_found,
-    rest_json,
-    rest_csv,
-    rest_excel,
-    rest_html,
-    get_cached_count,
-    get_request_elapsed,
-)
-
-from .formats.localizers import (
-    register_localizer,
-    get_localizer,
-    list_localizers,
-    apply_localizer,
-    localizer  # decorator
-)
-
-# Version info
-__version__ = "2.0.0"
-__author__ = "Django Mojo Team"
-
-# Public API
-__all__ = [
-    # Main serializer classes
-    'AdvancedGraphSerializer',
-    'CollectionSerializer',
-
-    # Format handlers
-    'JsonFormatter',
-    'CsvFormatter',
-    'ExcelFormatter',
-    'ResponseFormatter',
-
-    # Convenience functions
-    'serialize_model',
-    'serialize_collection',
-    'serialize_to_response',
-    'serialize_to_csv',
-    'serialize_to_excel',
-
-    # JSON utilities
-    'to_json',
-    'to_pretty_json',
-    'to_compact_json',
-    'ExtendedJSONEncoder',
-
-    # Export functions
-    'generate_csv',
-    'generate_csv_stream',
-    'generate_excel',
-    'create_multi_sheet_excel',
-
-    # Response helpers
-    'rest_status',
-    'rest_success',
-    'rest_error',
-    'rest_permission_denied',
-    'rest_not_found',
-    'rest_json',
-    'rest_csv',
-    'rest_excel',
-    'rest_html',
-
-    # Utilities
-    'get_cached_count',
-    'get_request_elapsed',
-    'get_formatter',
-    'timeit',
-
-    # Localizers
-    'register_localizer',
-    'get_localizer',
-    'list_localizers',
-    'apply_localizer',
-    'localizer',
-]
-
-
-# Convenience shortcuts for common use cases
-def serialize(instance, graph="default", many=None, request=None, format="json", **kwargs):
-    """
-    Universal serialization function that automatically chooses the right serializer.
-
-    :param instance: Model instance, QuerySet, or list of objects
-    :param graph: RestMeta graph name to use
-    :param many: Force many=True for lists (auto-detected for QuerySets)
-    :param request: Django request object
-    :param format: Output format ('json', 'csv', 'excel', 'response')
-    :param kwargs: Additional options
-    :return: Serialized data or HttpResponse (if format='response')
-    """
-    from django.db.models import QuerySet
-
-    # Auto-detect if we're dealing with a collection
-    if isinstance(instance, QuerySet):
-        if format == "response":
-            return CollectionSerializer(instance, graph=graph, request=request, **kwargs).to_response()
-        elif format in ["csv", "excel"]:
-            formatter = ResponseFormatter(request)
-            return formatter.format_response(instance, format, **kwargs)
-        else:
-            return CollectionSerializer(instance, graph=graph, request=request, **kwargs).serialize()
-
-    elif isinstance(instance, (list, tuple)) or many:
-        if format == "response":
-            return AdvancedGraphSerializer(instance, graph=graph, many=True, request=request, **kwargs).to_response()
-        elif format in ["csv", "excel"]:
-            formatter = ResponseFormatter(request)
-            return formatter.format_response(instance, format, **kwargs)
-        else:
-            return AdvancedGraphSerializer(instance, graph=graph, many=True, request=request, **kwargs).serialize()
-
-    else:
-        # Single instance
-        if format == "response":
-            return AdvancedGraphSerializer(instance, graph=graph, request=request, **kwargs).to_response()
-        elif format in ["csv", "excel"]:
-            formatter = ResponseFormatter(request)
-            return formatter.format_response([instance], format, **kwargs)
-        else:
-            return AdvancedGraphSerializer(instance, graph=graph, request=request, **kwargs).serialize()
-
-
-def to_response(instance, graph="default", request=None, **kwargs):
-    """
-    Shortcut to serialize and return HTTP response.
-
-    :param instance: Model instance, QuerySet, or list
-    :param graph: RestMeta graph name
-    :param request: Django request object
-    :param kwargs: Additional options
-    :return: HttpResponse
-    """
-    return serialize(instance, graph=graph, request=request, format="response", **kwargs)
-
-
-def to_csv_response(instance, fields=None, filename="export.csv", request=None, **kwargs):
-    """
-    Shortcut to export data as CSV response.
-
-    :param instance: QuerySet or list of objects
-    :param fields: Fields to include in CSV
-    :param filename: Download filename
-    :param request: Django request object
-    :param kwargs: Additional options
-    :return: HttpResponse with CSV file
-    """
-    formatter = ResponseFormatter(request)
-    return formatter.format_response(instance, "csv", fields=fields, filename=filename, **kwargs)
-
-
-def to_excel_response(instance, fields=None, filename="export.xlsx", request=None, **kwargs):
-    """
-    Shortcut to export data as Excel response.
-
-    :param instance: QuerySet or list of objects
-    :param fields: Fields to include in Excel
-    :param filename: Download filename
-    :param request: Django request object
-    :param kwargs: Additional options
-    :return: HttpResponse with Excel file
-    """
-    formatter = ResponseFormatter(request)
-    return formatter.format_response(instance, "excel", fields=fields, filename=filename, **kwargs)
-
-
-# Add shortcuts to __all__
-__all__.extend([
-    'serialize',
-    'to_response',
-    'to_csv_response',
-    'to_excel_response'
-])

mojo/serializers/advanced/formats/__init__.py

@@ -1,28 +0,0 @@
-"""
-Format handlers for advanced serialization.
-Supports JSON, CSV, Excel, and other output formats.
-"""
-
-from .json import JsonFormatter
-from .csv import CsvFormatter  
-from .excel import ExcelFormatter
-from .response import ResponseFormatter
-
-__all__ = [
-    'JsonFormatter',
-    'CsvFormatter', 
-    'ExcelFormatter',
-    'ResponseFormatter'
-]
-
-# Default formatters
-DEFAULT_FORMATTERS = {
-    'json': JsonFormatter,
-    'csv': CsvFormatter,
-    'excel': ExcelFormatter,
-    'xlsx': ExcelFormatter,
-}
-
-def get_formatter(format_type):
-    """Get formatter class for the specified format type."""
-    return DEFAULT_FORMATTERS.get(format_type.lower())