Develop

.github/workflows/ci.yaml

@@ -10,16 +10,17 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: '3.12'
+        python-version: '3.10'
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install uv
         uv venv
         uv pip install -e .[dev]
+        uv pip install -e .[optional]
     - name: Run tests
       run: |
-        uv run pytest
+        uv run tox
     - name: Run type checks
       run: |
         uv run mypy fastapi_assets

.gitignore

@@ -97,3 +97,6 @@ target/
 # Mkdocs
 /site/
 .env
+
+
+dump/

.python-version

@@ -1 +1 @@
-3.12
+3.10

MANIFEST.in

@@ -0,0 +1,30 @@
+include README.md
+include LICENSE.txt
+include pyproject.toml
+
+# Exclude common directories and files
+global-exclude *.pyc
+global-exclude *.pyo
+global-exclude *.egg-info
+global-exclude __pycache__
+global-exclude .pytest_cache
+global-exclude .mypy_cache
+global-exclude .ruff_cache
+global-exclude .tox
+global-exclude .venv
+global-exclude .vscode
+global-exclude .github
+global-exclude .git
+global-exclude .gitignore
+global-exclude *.egg
+
+# Exclude directories entirely
+prune build
+prune dist
+prune dump
+prune docs
+prune tests
+prune site
+
+# Include only site HTML for documentation (optional)
+recursive-include site *.html

README.md

@@ -1,3 +1,158 @@
 # FastAPI Assets
 
-FastAPI Assets is a powerful validation and assertion toolkit designed specifically for FastAPI applications. It simplifies the process of validating file uploads and request metadata, ensuring that your application handles user input securely and efficiently.
+<div align="center">
+
+[![Python Versions](https://img.shields.io/badge/python-3.10%20--%203.14-blue)](https://www.python.org/downloads/)
+[![FastAPI](https://img.shields.io/badge/FastAPI-0.115.0%2B-green.svg)](https://fastapi.tiangolo.com)
+[![License](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE.txt)
+[![Code Style](https://img.shields.io/badge/Code%20Style-Ruff-black.svg)](https://github.com/astral-sh/ruff)
+
+A powerful validation and assertion toolkit for FastAPI applications.
+
+[Documentation](https://openverge.github.io/fastapi-assets/) · [Examples](./docs/examples.md) · [Contributing](./docs/CONTRIBUTING.md)
+
+</div>
+
+---
+
+## Overview
+
+**FastAPI Assets** is a comprehensive validation toolkit designed specifically for FastAPI applications. It simplifies the process of validating file uploads, request metadata, and HTTP parameters, ensuring that your application handles user input securely and efficiently.
+
+FastAPI Assets provides:
+
+- **File Validators** - Validate file uploads with size, MIME type, and filename checks
+- **Image Validators** - Specialized validation for image files (format, dimensions, aspect ratio)
+- **CSV Validators** - Validate CSV structure, encoding, columns, and row counts
+- **Request Validators** - Validate headers, query parameters, path parameters, and cookies
+- **Custom Validators** - Create custom validation logic with sync or async support
+- **Granular Error Messages** - Fine-grained error control for precise user feedback
+- **Type-Safe** - Full type hints and runtime type validation
+- **Light Weight** - Minimal dependencies; optional extras for specific features
+
+## Quick Start
+
+### Installation
+
+```bash
+# Basic installation
+pip install fastapi-assets
+
+# With image support (includes Pillow)
+pip install fastapi-assets[image]
+
+# With CSV support (includes pandas)
+pip install fastapi-assets[pandas]
+
+# With all optional features
+pip install fastapi-assets[image,pandas]
+```
+
+## Features
+
+### File Validators
+
+- **FileValidator** - General-purpose file validation
+  - File size validation (min/max with human-readable formats)
+  - MIME type validation with wildcard support
+  - Filename pattern validation
+  - Custom validator functions
+
+- **ImageValidator** - Specialized image validation
+  - Image format validation (JPEG, PNG, WebP, GIF, BMP, TIFF)
+  - Image dimension validation
+  - Aspect ratio validation
+  - Inherits all FileValidator features
+
+- **CSVValidator** - CSV file validation (requires pandas)
+  - CSV encoding validation
+  - Required/disallowed columns
+  - Row count validation
+  - Header-only validation option
+
+### Request Validators
+
+- **HeaderValidator** - HTTP header validation
+  - Pattern matching with regex
+  - Predefined formats (UUID4, email, Bearer token, etc.)
+  - Allowed values restriction
+  - Custom validators
+
+- **QueryValidator** - Query parameter validation
+  - Type conversion and validation
+  - Allowed values restriction
+  - Numeric range validation
+  - Pattern matching
+
+- **PathValidator** - Path parameter validation
+  - Type conversion
+  - Pattern matching
+  - Range validation
+
+- **CookieValidator** - Cookie value validation
+  - Pattern matching
+  - Required value validation
+  - Custom validators
+
+### Advanced Features
+
+- **Granular Error Messages** - Customize error messages for each validation type
+- **Custom Validators** - Add custom validation logic (sync or async)
+- **HTTP Status Codes** - Customize HTTP response codes per validator
+- **Type Safety** - Full type hints for IDE support and type checking
+
+## Documentation
+
+Comprehensive documentation is available at [https://openverge.github.io/fastapi-assets/](https://openverge.github.io/fastapi-assets/)
+
+- [Getting Started](./docs/getting-started.md) - Installation and basic usage
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+- [Examples](./docs/examples.md) - Practical usage examples
+- [Custom Validators](./docs/custom_validators.md) - Creating custom validation logic
+
+
+## Project Structure
+
+```
+fastapi-assets/
+├── fastapi_assets/
+│   ├── core/                    # Core validation framework
+│   │   ├── base_validator.py   # Abstract base validator
+│   │   └── exceptions.py        # Custom exceptions
+│   ├── validators/              # File validators
+│   │   ├── file_validator.py
+│   │   ├── image_validator.py
+│   │   ├── csv_validator.py
+│   │   └── utils.py
+│   └── request_validators/      # HTTP request validators
+│       ├── header_validator.py
+│       ├── query_validator.py
+│       ├── path_validator.py
+│       └── cookie_validator.py
+├── tests/                       # Comprehensive test suite
+├── docs/                        # Documentation
+└── pyproject.toml              # Project configuration
+```
+
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for guidelines.
+
+## Code of Conduct
+
+Please read [CODE_OF_CONDUCT.md](./docs/CODE_OF_CONDUCT.md) before contributing.
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE.txt](LICENSE.txt) file for details.
+
+
+
+---
+
+**FastAPI Assets** - Making FastAPI validation simple, secure, and intuitive.
+
+*Version 0.1.0* | *Last Updated: November 2025*
+
+

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,45 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, 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.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all project spaces, and it also applies when an individual is representing the project or its community in public spaces. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project maintainer using any of the [private contact addresses](https://github.com/dec0dOS/amazing-github-template#support). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 1.4, available at <https://www.contributor-covenant.org/version/1/4/code-of-conduct.html>
+
+For answers to common questions about this code of conduct, see <https://www.contributor-covenant.org/faq>

docs/CONTRIBUTING.md

@@ -0,0 +1,124 @@
+# Contributing to FastAPI Assets
+Thank you for your interest in contributing to FastAPI Assets! We welcome contributions from the community to help improve and expand this project. Whether you're fixing bugs, adding new features, or improving documentation, your contributions are valuable.
+
+## Reporting Bugs
+
+Before creating bug reports, check the issue list. When creating a bug report, include:
+
+- **Use a clear descriptive title**
+- **Describe the exact steps to reproduce the problem**
+- **Provide specific examples to demonstrate the steps**
+- **Describe the behavior you observed and what the problem is**
+- **Explain which behavior you expected to see instead**
+- **Include Python version, FastAPI Assets version, and OS information**
+- **Include relevant error messages and stack traces**
+
+## Suggesting Enhancements
+
+Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion, include:
+
+- **Use a clear descriptive title**
+- **Provide a step-by-step description of the suggested enhancement**
+- **Provide specific examples to demonstrate the steps**
+- **Describe the current behavior and expected behavior**
+- **Explain why this enhancement would be useful**
+
+## Pull Requests
+
+- Fill in the required template
+- Include appropriate test cases
+- Update documentation and examples
+- End all files with a newline
+
+## Development Setup
+
+### Prerequisites
+
+- Python 3.10 or higher
+- Git
+- pip
+
+### Setting Up Development Environment
+
+1. **Fork the repository**
+
+```bash
+# Go to the GitHub repository and click "Fork"
+```
+
+2. **Clone your fork**
+
+```bash
+git clone https://github.com/YOUR_USERNAME/fastapi-assets.git
+cd fastapi-assets
+```
+
+3. **Create a virtual environment**
+
+```bash
+python -m venv venv
+
+# Activate virtual environment
+# On Windows:
+venv\Scripts\activate
+# On Unix/macOS:
+source venv/bin/activate
+```
+
+4. **Install dependencies with development extras**
+
+```bash
+pip install -e ".[dev,image,pandas]"
+```
+
+5. **Create a feature branch**
+
+```bash
+git checkout -b feature/your-feature-name
+```
+
+## Development Workflow
+
+### Code Style
+
+FastAPI Assets uses:
+- **Ruff** for linting and formatting
+- **MyPy** for type checking
+- **Pytest** for testing
+
+### Running Linting
+
+```bash
+ruff check fastapi_assets tests
+ruff format fastapi_assets tests
+```
+
+### Running Type Checks
+
+```bash
+mypy fastapi_assets
+```
+
+### Running Tests
+
+```bash
+pytest
+pytest --cov=fastapi_assets
+pytest tests/test_file_validator.py -v
+```
+
+## Making Changes
+
+1. Create a feature branch
+2. Make your changes with type hints and docstrings
+3. Format your code with ruff
+4. Run tests to ensure everything passes
+5. Run type checks with mypy
+6. Commit with clear messages following conventional commits
+7. Push to your fork
+8. Create a pull request
+
+## Code of Conduct
+
+By participating in this project, you agree to abide by the Contributor Covenant Code of Conduct.
+