flaxon 0.1.0__tar.gz

flaxon-0.1.0/.env.example

@@ -0,0 +1,211 @@
+# ============================================================
+# Flaxon Framework Environment Variables
+# ============================================================
+# Copy this file to .env and update the values for your environment
+# Never commit .env to version control!
+# ============================================================
+
+# ============================================================
+# Application Settings
+# ============================================================
+
+# Environment: development, testing, staging, production
+FLAXON_ENV=development
+
+# Debug mode: true or false
+FLAXON_DEBUG=true
+
+# Secret key for sessions and cryptographic operations
+# Generate with: python -c "import secrets; print(secrets.token_urlsafe(32))"
+FLAXON_SECRET_KEY=change-this-to-a-secure-random-string-in-production
+
+# Allowed hosts: comma-separated list
+FLAXON_ALLOWED_HOSTS=localhost,127.0.0.1
+
+# Maximum request body size in bytes (default: 10MB)
+FLAXON_MAX_BODY_SIZE=10485760
+
+# ============================================================
+# Database Settings (example with PostgreSQL)
+# ============================================================
+
+DATABASE_URL=postgresql://user:password@localhost:5432/flaxon
+DATABASE_POOL_SIZE=10
+DATABASE_MAX_OVERFLOW=20
+DATABASE_POOL_TIMEOUT=30
+DATABASE_ECHO=false
+
+# ============================================================
+# Redis Settings
+# ============================================================
+
+REDIS_URL=redis://localhost:6379/0
+REDIS_MAX_CONNECTIONS=10
+REDIS_SOCKET_TIMEOUT=5
+
+# ============================================================
+# Cache Settings
+# ============================================================
+
+CACHE_BACKEND=memory  # memory, redis, filesystem
+CACHE_DEFAULT_TTL=300  # seconds
+CACHE_MAX_SIZE=1000  # items (for memory backend)
+
+# ============================================================
+# Security Settings
+# ============================================================
+
+# CORS
+CORS_ALLOWED_ORIGINS=https://example.com,https://app.example.com
+CORS_ALLOW_CREDENTIALS=true
+CORS_MAX_AGE=600
+
+# Rate Limiting
+RATE_LIMIT_REQUESTS=120
+RATE_LIMIT_WINDOW=60  # seconds
+
+# Session
+SESSION_COOKIE_NAME=flaxon_session
+SESSION_COOKIE_SECURE=true
+SESSION_COOKIE_HTTPONLY=true
+SESSION_COOKIE_SAMESITE=lax
+SESSION_TTL=86400  # 24 hours in seconds
+
+# ============================================================
+# Email Settings (SMTP)
+# ============================================================
+
+SMTP_HOST=smtp.example.com
+SMTP_PORT=587
+SMTP_USERNAME=user@example.com
+SMTP_PASSWORD=your-password
+SMTP_USE_TLS=true
+SMTP_FROM=noreply@example.com
+
+# ============================================================
+# Logging
+# ============================================================
+
+LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR, CRITICAL
+LOG_FORMAT=json  # json, text
+LOG_FILE=/var/log/flaxon/app.log
+
+# ============================================================
+# Observability
+# ============================================================
+
+# OpenTelemetry
+OTEL_ENABLED=false
+OTEL_SERVICE_NAME=flaxon
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_TRACES_SAMPLER=parentbased_always_on
+
+# ============================================================
+# Performance
+# ============================================================
+
+# Worker count (for production)
+WORKERS=4
+
+# Timeouts (seconds)
+READ_TIMEOUT=30
+WRITE_TIMEOUT=30
+CONNECT_TIMEOUT=5
+
+# ============================================================
+# Third-Party Services
+# ============================================================
+
+# Example: AWS S3
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_REGION=us-east-1
+AWS_S3_BUCKET=flaxon-storage
+
+# Example: Firebase Cloud Messaging
+FCM_API_KEY=your-fcm-api-key
+FCM_SENDER_ID=your-sender-id
+
+# Example: Sentry
+SENTRY_DSN=https://your-dsn@sentry.example.com/1
+SENTRY_ENVIRONMENT=development
+SENTRY_SAMPLE_RATE=1.0
+
+# ============================================================
+# Development Settings
+# ============================================================
+
+# Auto-reload (development only)
+AUTO_RELOAD=true
+
+# Development server host
+DEV_HOST=127.0.0.1
+DEV_PORT=8000
+
+# ============================================================
+# Feature Flags
+# ============================================================
+
+FEATURE_WEBSOCKET_ENABLED=true
+FEATURE_TASKS_ENABLED=false
+FEATURE_OPENAPI_ENABLED=false
+FEATURE_ADMIN_ENABLED=false
+
+# ============================================================
+# Security Policies (Production)
+# ============================================================
+
+SECURITY_HEADERS_ENABLED=true
+CSP_ENABLED=false
+CSP_POLICY="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; font-src 'self'; connect-src 'self';"
+
+HSTS_ENABLED=false
+HSTS_MAX_AGE=31536000
+HSTS_INCLUDE_SUBDOMAINS=true
+HSTS_PRELOAD=false
+
+# ============================================================
+# Database Migration (if using Alembic)
+# ============================================================
+
+ALEMBIC_CONFIG=alembic.ini
+ALEMBIC_SCRIPT_LOCATION=migrations
+ALEMBIC_USE_ASYNC=true
+
+# ============================================================
+# JWT Authentication
+# ============================================================
+
+JWT_SECRET_KEY=change-this-to-a-secure-random-string
+JWT_ALGORITHM=HS256
+JWT_ACCESS_TOKEN_EXPIRE_MINUTES=15
+JWT_REFRESH_TOKEN_EXPIRE_DAYS=7
+JWT_TOKEN_TYPE=bearer
+
+# ============================================================
+# OAuth2 Providers
+# ============================================================
+
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+GOOGLE_REDIRECT_URI=https://example.com/auth/google/callback
+
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+GITHUB_REDIRECT_URI=https://example.com/auth/github/callback
+
+# ============================================================
+# File Storage
+# ============================================================
+
+STORAGE_BACKEND=local  # local, s3, gcs, azure
+STORAGE_LOCAL_PATH=./uploads
+STORAGE_URL_PREFIX=/uploads
+
+# S3 (if using)
+S3_ENDPOINT_URL=https://s3.amazonaws.com
+S3_ACCESS_KEY_ID=your-access-key
+S3_SECRET_ACCESS_KEY=your-secret-key
+S3_BUCKET_NAME=flaxon-storage
+S3_REGION=us-east-1
+S3_PUBLIC_URL=https://s3.amazonaws.com/flaxon-storage

flaxon-0.1.0/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to Flaxon will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Initial project structure
+- ASGI application with HTTP, WebSocket, and lifespan support
+- Flask-style route decorators with typed parameters
+- Request validation with declarative schemas
+- WebSocket support with room broadcasting
+- Jinax template integration (optional Jinja2)
+- Middleware: CORS, request ID, security headers, rate limiting
+- CLI commands: run, routes, doctor, new
+- Testing utilities: sync and async test clients
+- Debugger with development/production modes
+- Sensitive data redaction
+
+## [0.1.0] - 2026-07-22
+
+### Added
+- Initial alpha release
+- Core framework prototype
+- Example applications: hello_api, jinax_site, react_backend, android_backend
+- Comprehensive documentation
+
+### Known Limitations
+- WebSocket manager is in-memory only (single-process)
+- Rate limiter is in-memory only (single-process)
+- No OpenAPI generation yet
+- No official plugin system yet
+- No authentication/authorization modules yet

flaxon-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,60 @@
+
+---
+
+## CODE_OF_CONDUCT.md
+
+```markdown
+# Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+- Focusing on what is best for the overall community
+
+Examples of unacceptable behavior:
+
+- The use of sexualized language or imagery, and sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement Responsibilities
+
+Project maintainers are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team at conduct@flaxon.dev. All complaints will be
+reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

flaxon-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,139 @@
+# Contributing to Flaxon
+
+Thank you for your interest in contributing to Flaxon! 🎉
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## How to Contribute
+
+### Report a Bug
+
+1. Check if the bug is already reported in [Issues](https://github.com/flaxon/flaxon/issues)
+2. If not, create a new issue with:
+   - Clear title and description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Environment (OS, Python version, Flaxon version)
+
+### Suggest a Feature
+
+1. Check if the feature is already requested
+2. Create a feature request with:
+   - Clear description of the feature
+   - Why it's valuable
+   - Potential implementation approach
+
+### Submit Code
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/your-feature`
+3. Make your changes with tests
+4. Run the test suite: `pytest`
+5. Run linting: `ruff check .`
+6. Run type checking: `mypy .`
+7. Commit with clear messages
+8. Push and open a Pull Request
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/flaxon/flaxon.git
+cd flaxon
+
+# Create a virtual environment
+python -m venv .venv
+source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+# Install in development mode with all extras
+pip install -e ".[standard,dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=flaxon --cov-report=term-missing
+
+# Run linting
+ruff check .
+
+# Run type checking
+mypy .
+
+Code Style
+Follow PEP 8
+
+Use type hints for all function signatures
+
+Write docstrings for public APIs
+
+Keep functions focused and small
+
+Prefer async/await for I/O operations
+
+Linting Configuration
+Flaxon uses ruff for linting and formatting. Configuration is in ruff.toml.
+
+Type Checking
+Flaxon uses mypy for static type checking. Configuration is in mypy.ini.
+
+Testing
+Unit tests in tests/unit/ — Test individual components
+
+Integration tests in tests/integration/ — Test component interactions
+
+Security tests in tests/security/ — Test security properties
+
+Performance tests in tests/performance/ — Benchmark performance
+
+Writing Tests
+python
+# tests/unit/test_example.py
+from flaxon import Flaxon
+from flaxon.testing import TestClient
+
+def test_route():
+    app = Flaxon("test")
+
+    @app.get("/")
+    async def home():
+        return {"message": "hello"}
+
+    response = TestClient(app).get("/")
+    assert response.status_code == 200
+    assert response.json() == {"message": "hello"}
+Pull Request Process
+Update the CHANGELOG.md with your changes
+
+Update documentation if necessary
+
+Ensure all tests pass
+
+Get at least one maintainer review
+
+Squash commits before merging
+
+Release Process
+Update version in src/flaxon/__init__.py
+
+Update CHANGELOG.md
+
+Tag the release: git tag v0.1.0
+
+Push tags: git push --tags
+
+GitHub Actions will build and publish to PyPI
+
+Maintainers
+Aldane Hutchinson (@aldane)
+
+Questions?
+Open an issue for bugs or feature requests
+
+Join our Discord for community support
+
+Email: maintainers@flaxon.dev
+
+Thank you for contributing to Flaxon! 🚀

flaxon-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+
+---
+
+## LICENSE
+
+```markdown
+MIT License
+
+Copyright (c) 2026 Aldane Hutchinson and Flaxon Contributors
+
+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.

flaxon-0.1.0/MANIFEST.in

@@ -0,0 +1,45 @@
+# Include all Python source files
+include pyproject.toml
+include README.md
+include LICENSE
+include CHANGELOG.md
+include CONTRIBUTING.md
+include CODE_OF_CONDUCT.md
+include SECURITY.md
+include SUPPORT.md
+include ROADMAP.md
+include .env.example
+
+# Include package data
+recursive-include src/flaxon *.py
+recursive-include tests *.py
+
+# Include examples
+recursive-include examples *.py
+recursive-include examples *.html
+recursive-include examples *.json
+recursive-include examples *.md
+
+# Include documentation
+recursive-include docs *.md
+recursive-include docs *.rst
+recursive-include docs *.png
+recursive-include docs *.svg
+
+# Include static assets if any
+recursive-include src/flaxon/py.typed
+
+# Exclude unnecessary files
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude __pycache__
+global-exclude .git
+global-exclude .github
+global-exclude .venv
+global-exclude .pytest_cache
+global-exclude .mypy_cache
+global-exclude .ruff_cache
+global-exclude .coverage
+global-exclude *.log
+global-exclude .DS_Store
+global-exclude *.egg-info