rest-canvas 0.8.1__tar.gz

rest_canvas-0.8.1/LICENSE

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

rest_canvas-0.8.1/PKG-INFO

@@ -0,0 +1,382 @@
+Metadata-Version: 2.4
+Name: rest-canvas
+Version: 0.8.1
+Summary: OpenAPI-driven decorator library for easy predictable and safe REST API implementation in python
+Author: rklaus
+License-Expression: MIT
+Project-URL: Repository, https://gitlab.com/overflask/rest-canvas
+Project-URL: Tracker, https://gitlab.com/overflask/rest-canvas/-/issues
+Project-URL: Changelog, https://gitlab.com/overflask/rest-canvas/-/blob/main/CHANGELOG.md
+Keywords: openapi,rest,api,decorator,flask,django,validation,schema
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: prance>=25.4
+Requires-Dist: openapi-spec-validator>=0.7
+Provides-Extra: flask
+Requires-Dist: Flask>=2.0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: Django>=3.2; extra == "django"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: Flask>=2.0; extra == "dev"
+Requires-Dist: Django>=3.2; extra == "dev"
+Dynamic: license-file
+
+# REST Canvas
+
+OpenAPI-driven decorator library for REST API endpoints in Django and Flask.
+
+## Overview
+
+REST Canvas provides a decorator-based approach to building REST APIs that are automatically validated against OpenAPI specifications. It handles request validation, response formatting, pagination, sorting, filtering, and error handling based on your OpenAPI YAML files.
+
+## Features
+
+- **OpenAPI-driven**: All validation and behavior driven by OpenAPI specifications
+- **Framework-agnostic**: Works with Django, Flask, and standalone mode
+- **Automatic validation**: Path parameters, query parameters, and request body validation at startup
+- **Request-centric design**: All features accessible via unified Request object
+- **Feature declaration**: Declare endpoint capabilities with simple markers (Fields, Sort, Filter)
+- **Pagination support**: Both cursor-based and page-based pagination
+- **RCQL filtering**: REST Canvas Query Language for powerful filtering (e.g., `status==active&age>18`)
+- **Sort support**: Multi-field sorting with ascending/descending (e.g., `name,-createdAt`)
+- **Detail level selection**: Control response verbosity with field groups (e.g., `minimal`, `full`)
+- **Type safety**: Generic type hints for pagination: `Request[PagePagination]`
+- **Testing utilities**: Built-in MockRequest for testing view functions in isolation
+
+## Installation
+
+```bash
+# Install from Git (once published)
+pip install git+https://github.com/yourusername/rest-canvas.git
+
+# Or install in editable mode for development
+pip install -e .
+
+# With development dependencies
+pip install -e ".[dev]"
+
+# With Django
+pip install -e ".[django]"
+
+# With Flask
+pip install -e ".[flask]"
+```
+
+## Configuration
+
+REST Canvas is configured via the `Config` class, which allows you to customize behavior:
+
+```python
+from rest_canvas import RestCanvas
+from rest_canvas.core.config import Config
+from rest_canvas.core.log import LoggerConfig, LogToConsole
+from rest_canvas.core.log.logger_types import LogLevel
+
+# Basic usage - starts with Standalone adapter
+api = RestCanvas('openapi.yaml')
+
+# Custom configuration
+config = Config(
+    debug=True,                          # Enable debug mode
+    logger_config=LoggerConfig(
+        min_log_level=LogLevel.INFO,    # Set logging level
+        enabled=True,                    # Enable/disable logging
+        processors=[LogToConsole()]      # Custom log processors
+    )
+)
+api = RestCanvas('openapi.yaml', config=config)
+```
+
+### Configuration Options
+
+- **debug**: Enable debug mode for additional logging and validation (default: `False`)
+- **logger_config**: LoggerConfig instance for customizing logging behavior
+
+### Framework Adapter Selection
+
+REST Canvas always starts with the **Standalone adapter**. The adapter automatically switches when you register routes:
+
+```python
+# Flask - adapter switches when you call register_flask_routes()
+api = RestCanvas('openapi.yaml')
+api.register_flask_routes(app)  # Now using FlaskAdapter
+
+# Django - adapter switches when you call register_django_urls()
+api = RestCanvas('openapi.yaml')
+urlpatterns = api.register_django_urls()  # Now using DjangoAdapter
+
+# Standalone - no registration needed (default)
+api = RestCanvas('openapi.yaml')
+# Call endpoints directly - stays with StandaloneAdapter
+```
+
+**Note:** You cannot switch adapters once routes are registered. Calling `register_flask_routes()` or `register_django_urls()` more than once will raise a `RuntimeError`.
+
+## Quick Start
+
+### Flask Example
+
+```python
+from flask import Flask
+from rest_canvas import RestCanvas, Request, PagePagination, Sort, Filter
+
+app = Flask(__name__)
+
+# Initialize REST API with OpenAPI spec
+api = RestCanvas('openapi.yaml', mount_point='/api/v1')
+
+
+# Declare features in decorator, access via request object
+@api.endpoint('GET /users', Sort, Filter)
+def list_users(request: Request[PagePagination]):
+    """List users with pagination, sorting, and filtering."""
+    users = User.query.all()
+
+    # Filter with RCQL: ?filter=status==active&age>18
+    if request.filter:
+        users = apply_filter(users, request.filter)
+
+    # Sort: ?sort=name,-createdAt (ascending name, descending createdAt)
+    if request.sort:
+        users = apply_sort(users, request.sort)
+
+    # Pagination automatically populated from query params
+    users_page = users[request.pagination.offset:request.pagination.limit]
+    request.pagination.total = len(users)
+
+    return [user.to_dict() for user in users_page]
+
+
+# Auto-register all routes with Flask
+api.register_flask_routes(app)
+```
+
+### Django Example
+
+```python
+from rest_canvas import RestCanvas, Request, CursorPagination, DetailLevel
+
+# Initialize REST API
+api = RestCanvas('openapi.yaml', mount_point='/api/v1')
+
+
+@api.endpoint('GET /users/{userId}', DetailLevel)
+def get_user_by_id(request: Request, user_id: int):
+    """Get user by ID with detail level selection."""
+    user = User.objects.get(id=user_id)
+
+    # Return different fields based on request.detail_level
+    # Query: ?detailLevel=minimal
+    if request.detail_level == "minimal":
+        return {"id": user.id, "name": user.name}
+    else:
+        return user.to_dict()
+
+
+# In urls.py
+urlpatterns = api.register_django_urls()
+```
+
+### Key Features
+
+- **Request-centric design**: All features (pagination, sort, filter, detail_level) accessible via `request` object
+- **Feature declaration**: Declare features in decorator: `@api.endpoint('GET /path', Sort, Filter, DetailLevel)`
+- **Type-safe**: Generic type hints for pagination: `Request[PagePagination]`
+- **Automatic parsing**: Sort, filter, pagination, and detail level parameters parsed automatically
+- **OpenAPI validation**: Function signatures and features validated against OpenAPI spec at startup
+- **RCQL filtering**: Powerful query language with operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `=like=`
+- **Multi-field sorting**: Sort by multiple fields with direction: `?sort=name,-createdAt`
+- **Framework adapters**: Seamless adaptation for Flask, Django, and standalone modes
+
+## Development Status
+
+**Current Version**: 0.1.0 (Alpha)
+
+This library is in active development. Recent refactoring has established a modular, request-centric architecture.
+
+### Completed Features
+- ✅ OpenAPI-driven endpoint validation
+- ✅ Request-centric design with unified Request object
+- ✅ Framework adapters (Django, Flask, Standalone)
+- ✅ Feature declaration system (Sort, Filter, DetailLevel)
+- ✅ Pagination (Page-based and Cursor-based)
+- ✅ RCQL filtering with comparison and logical operators
+- ✅ Multi-field sorting with ascending/descending
+- ✅ Detail level (field group) selection
+- ✅ Automatic type coercion for query parameters
+- ✅ CamelCase to snake_case conversion
+- ✅ Testing utilities (MockRequest)
+
+### In Progress
+- 🔄 Additional ORM appliers for filtering and sorting
+- 🔄 Enhanced error messages and validation
+- 🔄 Documentation improvements
+
+## Requirements
+
+- Python >= 3.8
+- PyYAML >= 6.0
+- jsonschema >= 4.0
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -r requirements-dev.txt
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=rest_api_decorator --cov-report=html
+
+# Format code
+black .
+
+# Lint code
+flake8 rest_api_decorator tests
+
+# Type check
+mypy rest_api_decorator
+```
+
+## Testing Your Views
+
+The library provides `MockRequest` for testing your view functions in isolation:
+
+```python
+from rest_canvas.testing import MockRequest
+
+def test_list_users():
+    # Create mock request with pagination, sort, and filter
+    request = (MockRequest()
+        .with_page_pagination(page=1, size=10)
+        .with_sort('name,-createdAt')
+        .with_filter('status==active'))
+
+    # Call view function directly
+    result = list_users(request)
+
+    # Assert results
+    assert len(result) <= 10
+    assert request.pagination.total > 0
+
+def test_get_user_by_id():
+    # Create mock request for single resource with detail level
+    request = MockRequest().with_detail_level('minimal')
+
+    # Call view with path parameter
+    result = get_user_by_id(request, user_id=42)
+
+    # Assert minimal fields returned
+    assert 'id' in result
+    assert 'name' in result
+    assert 'email' not in result  # Not included in minimal
+```
+
+## Project Structure
+
+```
+rest_canvas/
+├── public/                # Public API surface
+│   ├── rest_canvas.py     # RestCanvas class (main entry point)
+│   ├── features.py        # Feature markers (DetailLevel, Sort, Filter)
+│   └── exceptions.py      # API exceptions
+├── core/                  # Core implementation
+│   ├── endpoint/          # Endpoint decorator and validation
+│   ├── request/           # Request wrapper and validation
+│   ├── open_api/          # OpenAPI spec loading and parsing
+│   ├── pagination/        # Page and cursor pagination
+│   ├── query/             # Query parameter parsing (sort, filter)
+│   ├── view/              # View function introspection
+│   ├── envelope/          # Response envelope formatting
+│   └── serializer.py      # Datetime serialization
+├── adapters/              # Framework adapters
+│   ├── django_adapter.py
+│   ├── flask_adapter.py
+│   └── standalone_adapter.py
+├── utils/                 # Utilities
+└── testing/               # Testing utilities (MockRequest)
+
+tests/
+├── unit/                  # Unit tests
+├── integration/           # Integration tests
+└── fixtures/              # Test fixtures and OpenAPI specs
+```
+
+## Key Concepts
+
+### RCQL (REST Canvas Query Language)
+
+RCQL provides a powerful filtering syntax using URL-friendly operators:
+
+```
+# Comparison operators
+?filter=status==active           # Equal
+?filter=age>18                   # Greater than
+?filter=age<=65                  # Less than or equal
+?filter=name=like=%john%         # Pattern matching
+
+# Logical operators (left-to-right evaluation)
+?filter=status==active&age>18    # AND
+?filter=role==admin|role==mod    # OR
+
+# Complex expressions
+?filter=status==active&age>18|premium==true
+```
+
+### Sort Syntax
+
+Multi-field sorting with direction control:
+
+```
+?sort=name              # Ascending by name
+?sort=-createdAt        # Descending by createdAt
+?sort=name,-createdAt   # Multiple fields
+```
+
+### Detail Levels
+
+Control response verbosity with field groups defined in your OpenAPI spec:
+
+```
+?detailLevel=minimal    # Only essential fields
+?detailLevel=full       # All fields including relations
+```
+
+## Architecture
+
+REST Canvas uses a **request-centric** design where all query features flow through a unified `Request` object:
+
+1. **Decorator declaration**: Features declared in `@api.endpoint()` decorator
+2. **Automatic parsing**: Query parameters parsed and validated at request time
+3. **Request population**: Parsed values populated in `request.sort`, `request.filter`, etc.
+4. **Type safety**: Generic type hints for pagination: `Request[PagePagination]`
+5. **Framework agnostic**: Same code works with Django, Flask, or standalone
+
+This design ensures your view functions remain clean, testable, and framework-independent.
+
+## License
+
+MIT License
+
+## Contributing
+
+This is currently an internal project. Contribution guidelines will be added once the library reaches beta status.
+
+## Support
+
+For issues and questions, please refer to the issue tracker (to be set up).