pypaginate 0.2.0__tar.gz

pypaginate-0.2.0/.gitignore

@@ -0,0 +1,95 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# UV
+.uv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Testing
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Linting
+.ruff_cache/
+
+# Documentation
+docs/_build/
+docs-sphinx/_build/
+site/
+v1docs/
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local configuration
+.env
+.env.local
+*.local
+
+# Node.js (MCP servers)
+node_modules/
+
+# Build artifacts
+*.manifest
+*.spec
+
+# Session artifacts (AI-generated planning docs)
+REFACTORING_PLAN.md
+REFACTORING_ROADMAP.md
+AUDIT_IMPLEMENTATION_PLAN.md
+AUDIT_R2_IMPLEMENTATION_PLAN.md
+DOCS_REFACTOR_PLAN.md
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt

pypaginate-0.2.0/CHANGELOG.md

@@ -0,0 +1,148 @@
+# Changelog
+
+All notable changes to this project 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]
+
+### Planned for v0.3.0
+- JSON Logic dict-to-FilterGroup parser for frontend integration
+- Django `__` filter format parser
+- `add_pagination(app)` zero-config FastAPI middleware
+- HATEOAS link generation
+- Additional ORM support (Beanie, Tortoise)
+
+---
+
+## [0.2.0] - 2025-XX-XX
+
+### Added
+
+#### Architecture
+- Hexagonal architecture with domain/engine/adapter layers
+- Protocol-based backends (`PaginationBackend`, `CursorBackend`, `FilterBackend`, `SortBackend`, `SearchBackend`)
+- Universal `paginate()` entry point with Elysia-style type inference
+- `SyncPipeline` and `AsyncPipeline` for composing filter + sort + search + paginate
+
+#### Pagination
+- `OffsetParams` / `OffsetPage` (replaces `PageParams` / `Page`)
+- `CursorParams` / `CursorPage` for cursor/keyset pagination
+- `OverflowStrategy` (EMPTY or CLAMP) for out-of-range pages
+- Custom count query via `SQLAlchemyBackend(session, count_query=...)`
+- Row deduplication via `SQLAlchemyBackend(session, unique=True)`
+- `SyncSQLAlchemyBackend` and `SyncSQLAlchemyCursorBackend` for sync sessions
+- Fast in-memory path (no backend allocation for list + OffsetParams)
+
+#### Filtering
+- 20 operators: eq, ne, gt, gte, lt, lte, in, not_in, contains, starts_with, ends_with, like, ilike, between, is_null, is_not_null, regex, empty, not_empty, exists
+- `FilterGroup` with `And()` / `Or()` builders for nested boolean groups (up to 5 levels)
+- Compiled predicate closures (compile once, evaluate N times)
+- `SQLAlchemyFilterBackend` for SQL WHERE clause generation
+- `OperatorRegistry` for extensible operator lookup
+
+#### Search
+- `SearchSpec` with `weights`, `fuzzy`, `threshold`, `min_length`, `max_results`
+- `FuzzyMode.EXACT`, `FuzzyMode.FUZZY` (partial_ratio), `FuzzyMode.TOKEN_SORT` (token_sort_ratio)
+- `SearchFieldMode.EXACT`, `PREFIX`, `CONTAINS`
+- Unicode normalization with accent removal
+- `SQLAlchemySearchBackend` for SQL LIKE/ILIKE search
+
+#### Sorting
+- `SortSpec` with `direction` and `nulls` (NullsPosition.FIRST / LAST)
+- Multi-key stable sorting
+- `SQLAlchemySortBackend` for SQL ORDER BY
+
+#### FastAPI Integration
+- `OffsetDep`, `CursorDep` (Annotated dependency types)
+- `FilterDep` with `FilterField()` for declarative filters
+- `SortDep` for `?sort=name,-age` query parsing
+- `SearchDep` for `?q=alice&search_fields=name,email` query parsing
+
+#### Performance
+- msgspec fast page construction (`pypaginate[fast]`)
+- Compiled field accessors, pre-normalized search tokens
+- `__slots__` on all stateful classes
+- Optional google-re2 for ReDoS safety (`pypaginate[security]`)
+- LIKE pattern string method dispatch (bypasses fnmatch/regex for common patterns)
+
+### Changed
+- Renamed `PageParams` to `OffsetParams`, `Page` to `OffsetPage`
+- Replaced `paginate_entities()` / `paginate_rows()` with universal `paginate()`
+- Replaced JSON Logic dict filters with typed `FilterSpec` / `FilterGroup`
+- Replaced `SearchOptions` with `SearchSpec`
+- Moved `FilterEngine` to `pypaginate.filtering.engine`
+- Moved `SortEngine` to `pypaginate.sorting.engine`
+- FastAPI deps use `Annotated` types instead of function-based `Depends`
+
+### Removed
+- `SqlPaginator`, `MemoryPaginator` (replaced by protocol backends)
+- `PaginationSnapshot` (direct page return)
+- `MemorySearchService`, `SqlSearchService` (replaced by `SearchEngine` + backends)
+- `SqlSortAdapter`, `SqlFilterAdapter` (replaced by SA backends)
+- `get_pagination_params()`, `PagedResponse` (replaced by `OffsetDep`, `OffsetPage`)
+- JSON Logic dict format (replaced by typed `FilterGroup`)
+- JMESPath array access (replaced by dot notation)
+
+---
+
+## [0.1.0] - 2025-01-30
+
+### Added
+
+#### Core Pagination
+- `Page[T]` generic response model with metadata (total, page, limit, pages)
+- `PageParams` dataclass for pagination parameters
+- Offset-based pagination with configurable page size
+- Keyset (cursor-based) pagination for large datasets using `sqlakeyset`
+
+#### Pagination Engines
+- `SqlPaginator` - SQLAlchemy-based pagination engine
+- `MemoryPaginator` - In-memory pagination for Python collections
+- `paginate_entities()` - High-level async pagination API
+
+#### Filtering
+- `FilterEngine` with JSON Logic support for complex queries
+- Predicate-based filtering system
+- Support for operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `like`, `ilike`, `is_null`, `startswith`, `endswith`
+- Logical operators: `and`, `or`, `not`
+
+#### Search
+- `SqlSearchService` for full-text search
+- Fuzzy matching with RapidFuzz integration
+- Configurable similarity thresholds
+- Accent-insensitive search option
+- Multi-field search support
+
+#### Sorting
+- `SortEngine` for sort operations
+- `SqlSortAdapter` for SQLAlchemy integration
+- Multi-column sorting support
+- Ascending/descending order
+
+#### FastAPI Integration
+- `get_pagination_params()` dependency for FastAPI
+- `PagedResponse` Pydantic model for OpenAPI documentation
+- Type-safe parameter extraction from query strings
+
+#### Developer Experience
+- Full type hints with mypy --strict compatibility
+- Comprehensive docstrings
+- Async/await support throughout
+
+### Technical Details
+- Python 3.11+ required
+- SQLAlchemy 2.0+ for database operations
+- Pydantic v2 for data validation
+- Optional RapidFuzz for fuzzy search
+
+---
+
+## Future Releases
+
+See the [Roadmap](https://pypaginate.readthedocs.io/contributing/roadmap/) for detailed planning of future versions.
+
+[Unreleased]: https://github.com/CybLow/pypaginate/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/CybLow/pypaginate/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/CybLow/pypaginate/releases/tag/v0.1.0

pypaginate-0.2.0/LICENSE

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

pypaginate-0.2.0/PKG-INFO

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: pypaginate
+Version: 0.2.0
+Summary: Universal pagination toolkit for Python — one function, any backend, auto-detects sync/async
+Project-URL: Homepage, https://github.com/CybLow/pypaginate
+Project-URL: Documentation, https://pypaginate.readthedocs.io
+Project-URL: Repository, https://github.com/CybLow/pypaginate
+Project-URL: Issues, https://github.com/CybLow/pypaginate/issues
+Project-URL: Changelog, https://github.com/CybLow/pypaginate/blob/main/CHANGELOG.md
+Author-email: CybLow <cyber_lolow@protonmail.com>
+Maintainer-email: CybLow <cyber_lolow@protonmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: async,cursor,database,fastapi,filtering,jsonlogic,keyset,orm,pagination,search,sqlalchemy
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Front-Ends
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: all
+Requires-Dist: fastapi>=0.95.0; extra == 'all'
+Requires-Dist: msgspec>=0.18.0; extra == 'all'
+Requires-Dist: rapidfuzz>=3.0.0; extra == 'all'
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'all'
+Provides-Extra: fast
+Requires-Dist: msgspec>=0.18.0; extra == 'fast'
+Provides-Extra: fastapi
+Requires-Dist: fastapi>=0.95.0; extra == 'fastapi'
+Provides-Extra: search
+Requires-Dist: rapidfuzz>=3.0.0; extra == 'search'
+Provides-Extra: security
+Requires-Dist: google-re2>=1.0; extra == 'security'
+Provides-Extra: sqlalchemy
+Requires-Dist: sqlalchemy[asyncio]>=2.0.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+# pypaginate
+
+**Universal pagination toolkit for Python -- one function, any backend, auto-detects sync/async.**
+
+[![CI](https://github.com/CybLow/pypaginate/actions/workflows/ci.yml/badge.svg)](https://github.com/CybLow/pypaginate/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/pypaginate.svg)](https://pypi.org/project/pypaginate/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pypaginate.svg)](https://pypi.org/project/pypaginate/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/CybLow/pypaginate/branch/main/graph/badge.svg)](https://codecov.io/gh/CybLow/pypaginate)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+
+pypaginate provides a single `paginate()` function that works with lists, SQLAlchemy queries (async and sync), and cursor-based pagination. The return type is automatically inferred from the params you pass in.
+
+## Features
+
+- **One function** -- `paginate()` handles lists, SQLAlchemy queries, sync and async
+- **Type-safe inference** -- `OffsetParams` returns `OffsetPage`, `CursorParams` returns `CursorPage`
+- **Filtering** -- 20 operators (eq, gte, contains, between, regex, etc.)
+- **Sorting** -- multi-column with direction and null placement control
+- **Search** -- full-text with optional fuzzy matching (RapidFuzz)
+- **FastAPI** -- `Annotated` dependencies for pagination, filtering, sorting, and search
+- **Cursor pagination** -- keyset/cursor-based pagination via sqlakeyset
+- **Pipeline** -- compose filter + sort + search + paginate in one call
+- **100% typed** -- mypy strict mode, Pydantic v2 models
+
+## Installation
+
+```bash
+# Core (in-memory pagination only)
+pip install pypaginate
+
+# With SQLAlchemy support
+pip install pypaginate[sqlalchemy]
+
+# With FastAPI integration
+pip install pypaginate[fastapi]
+
+# With fuzzy search (RapidFuzz)
+pip install pypaginate[search]
+
+# Everything
+pip install pypaginate[all]
+```
+
+Or with [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add pypaginate
+uv add pypaginate[all]
+```
+
+## Quick Start
+
+Paginate a list in 3 lines:
+
+```python
+from pypaginate import paginate, OffsetParams
+
+page = paginate([1, 2, 3, 4, 5], OffsetParams(page=1, limit=2))
+
+page.items       # [1, 2]
+page.total       # 5
+page.pages       # 3
+page.has_next    # True
+```
+
+## SQLAlchemy (Async)
+
+```python
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+from pypaginate import paginate, OffsetParams
+from pypaginate.adapters.sqlalchemy import SQLAlchemyBackend
+
+async def list_users(session: AsyncSession):
+    stmt = select(User).order_by(User.created_at.desc())
+    backend = SQLAlchemyBackend(session)
+
+    page = await paginate(stmt, OffsetParams(page=1, limit=20), backend=backend)
+
+    page.items       # list[User]
+    page.total       # int
+    page.has_next    # bool
+```
+
+For sync sessions, use `SyncSQLAlchemyBackend`:
+
+```python
+from sqlalchemy.orm import Session
+from pypaginate.adapters.sqlalchemy import SyncSQLAlchemyBackend
+
+def list_users(session: Session):
+    backend = SyncSQLAlchemyBackend(session)
+    page = paginate(select(User), OffsetParams(page=1, limit=20), backend=backend)
+```
+
+## Cursor Pagination
+
+For large datasets where offset-based pagination is inefficient:
+
+```python
+from pypaginate import paginate, CursorParams
+from pypaginate.adapters.sqlalchemy import SQLAlchemyCursorBackend
+
+async def scroll_users(session: AsyncSession, cursor: str | None = None):
+    stmt = select(User).order_by(User.id)
+    backend = SQLAlchemyCursorBackend(session)
+
+    page = await paginate(stmt, CursorParams(limit=20, after=cursor), backend=backend)
+
+    page.items            # list[User]
+    page.next_cursor      # str | None -- pass to next request
+    page.previous_cursor  # str | None
+    page.has_next         # bool
+```
+
+## FastAPI Integration
+
+pypaginate provides `Annotated` dependency types for clean FastAPI integration:
+
+```python
+from fastapi import FastAPI
+from pypaginate import paginate, OffsetPage
+from pypaginate.adapters.fastapi import OffsetDep
+
+app = FastAPI()
+
+@app.get("/users")
+async def list_users(params: OffsetDep) -> OffsetPage[dict]:
+    users = [{"name": "Alice"}, {"name": "Bob"}, {"name": "Charlie"}]
+    return paginate(users, params)
+```
+
+Available dependencies:
+
+| Dependency | Query Params | Produces |
+|---|---|---|
+| `OffsetDep` | `?page=1&limit=20` | `OffsetParams` |
+| `CursorDep` | `?limit=20&after=abc` | `CursorParams` |
+| `FilterDep` | (user-defined fields) | `list[FilterSpec]` |
+| `SortDep` | `?sort=name,-age` | `list[SortSpec]` |
+| `SearchDep` | `?q=alice&search_fields=name,email` | `SearchSpec` |
+
+### Declarative Filters
+
+```python
+from typing import Annotated
+from fastapi import Query
+from pypaginate.adapters.fastapi import FilterDep, FilterField
+
+class UserFilters(FilterDep):
+    name: str | None = FilterField(None, operator="contains")
+    age_min: int | None = FilterField(None, field="age", operator="gte")
+    status: str | None = FilterField(None, operator="eq")
+
+@app.get("/users")
+async def list_users(
+    params: OffsetDep,
+    filters: Annotated[UserFilters, Query()],
+):
+    # filters.to_specs() returns list[FilterSpec] for non-None fields
+    ...
+```
+
+### Sorting and Search
+
+```python
+from pypaginate.adapters.fastapi import OffsetDep, SortDep, SearchDep
+
+@app.get("/users")
+async def list_users(params: OffsetDep, sort: SortDep, search: SearchDep):
+    # sort: ?sort=name,-created_at  (- prefix = descending)
+    # search: ?q=alice&search_fields=name,email
+    ...
+```
+
+## Filtering
+
+Use `FilterSpec` to define filter conditions:
+
+```python
+from pypaginate import FilterSpec
+from pypaginate.filtering import FilterEngine, create_default_registry
+
+engine = FilterEngine(create_default_registry())
+
+users = [
+    {"name": "Alice", "age": 30, "status": "active"},
+    {"name": "Bob", "age": 25, "status": "inactive"},
+    {"name": "Charlie", "age": 35, "status": "active"},
+]
+
+# Simple equality
+active = engine.apply(users, [FilterSpec(field="status", value="active")])
+# [Alice, Charlie]
+
+# Multiple filters (AND by default)
+result = engine.apply(users, [
+    FilterSpec(field="age", operator="gte", value=30),
+    FilterSpec(field="status", value="active"),
+])
+# [Alice, Charlie]
+```
+
+### Nested Filter Groups
+
+```python
+from pypaginate import And, Or, FilterSpec
+
+# (status = active) AND (age >= 30 OR name contains "bob")
+group = And(
+    FilterSpec(field="status", value="active"),
+    Or(
+        FilterSpec(field="age", operator="gte", value=30),
+        FilterSpec(field="name", operator="contains", value="bob"),
+    ),
+)
+
+result = engine.apply(users, group)
+```
+
+### Available Filter Operators
+
+| Operator | Description | Example |
+|---|---|---|
+| `eq`, `ne` | Equality / inequality | `FilterSpec(field="status", value="active")` |
+| `gt`, `gte`, `lt`, `lte` | Comparisons | `FilterSpec(field="age", operator="gte", value=18)` |
+| `in`, `not_in` | Membership | `FilterSpec(field="role", operator="in", value=["admin", "user"])` |
+| `contains`, `starts_with`, `ends_with` | Text matching | `FilterSpec(field="name", operator="contains", value="ali")` |
+| `like`, `ilike` | SQL-style patterns | `FilterSpec(field="email", operator="like", value="%@gmail.com")` |
+| `between` | Range | `FilterSpec(field="price", operator="between", value=[10, 100])` |
+| `is_null`, `is_not_null` | Null checks | `FilterSpec(field="notes", operator="is_null")` |
+| `empty`, `not_empty` | Empty checks | `FilterSpec(field="tags", operator="not_empty")` |
+| `exists` | Field existence | `FilterSpec(field="id", operator="exists")` |
+| `regex` | Regex matching | `FilterSpec(field="code", operator="regex", value="^A\\d+")` |
+
+## Sorting
+
+```python
+from pypaginate import SortSpec, SortDirection
+
+from pypaginate.sorting import SortEngine
+
+engine = SortEngine()
+
+users = [
+    {"name": "Charlie", "age": 35},
+    {"name": "Alice", "age": 30},
+    {"name": "Bob", "age": 25},
+]
+
+sorted_users = engine.apply(users, [
+    SortSpec(field="age", direction=SortDirection.DESC),
+])
+# [Charlie (35), Alice (30), Bob (25)]
+```
+
+## Search
+
+```python
+from pypaginate import SearchSpec
+
+from pypaginate.search import SearchEngine
+
+engine = SearchEngine()
+
+users = [
+    {"name": "Alice Smith", "email": "alice@example.com"},
+    {"name": "Bob Johnson", "email": "bob@example.com"},
+]
+
+results = engine.apply(users, SearchSpec(
+    query="alice",
+    fields=("name", "email"),
+))
+# [Alice Smith]
+```
+
+Fuzzy search (requires `pypaginate[search]`):
+
+```python
+from pypaginate import SearchSpec, FuzzyMode
+
+results = engine.apply(users, SearchSpec(
+    query="alce",
+    fields=("name",),
+    fuzzy=FuzzyMode.FUZZY,
+    threshold=75,
+))
+```
+
+## Pipeline (Filter + Sort + Search + Paginate)
+
+Compose all operations in a single call:
+
+```python
+from pypaginate import OffsetParams, FilterSpec, SortSpec, SortDirection
+from pypaginate.engine.pipeline import SyncPipeline
+from pypaginate.engine.paginator import Paginator
+from pypaginate.adapters.memory import (
+    MemoryBackend,
+    MemoryFilterBackend,
+    MemorySortBackend,
+)
+
+pipeline = SyncPipeline(
+    Paginator(MemoryBackend()),
+    filter_backend=MemoryFilterBackend(),
+    sort_backend=MemorySortBackend(),
+)
+
+page = pipeline.execute(
+    users,
+    OffsetParams(page=1, limit=10),
+    filters=[FilterSpec(field="status", value="active")],
+    sorting=[SortSpec(field="name", direction=SortDirection.ASC)],
+)
+```
+
+For async (e.g., SQLAlchemy), use `AsyncPipeline` with `AsyncPaginator`.
+
+## Architecture
+
+```
+pypaginate/
+├── domain/        # Models, specs, enums, protocols (no deps)
+├── engine/        # Paginator, cursor paginator, pipeline
+├── filtering/     # In-memory filter engine + operators
+├── sorting/       # In-memory sort engine
+├── search/        # In-memory search engine
+└── adapters/
+    ├── memory/        # In-memory backends (filter, sort, search)
+    ├── sqlalchemy/    # SA backends (offset, cursor, filter, sort, search)
+    └── fastapi/       # Annotated dependencies (OffsetDep, FilterDep, etc.)
+```
+
+## Development
+
+```bash
+git clone https://github.com/CybLow/pypaginate.git
+cd pypaginate
+uv sync
+
+# Run all checks
+uv run ruff format . && uv run ruff check --fix . && uv run mypy src/ && uv run pytest
+
+# Individual commands
+uv run pytest                  # Tests
+uv run pytest --cov            # Coverage
+uv run ruff format .           # Format
+uv run ruff check --fix .      # Lint
+uv run mypy src/               # Type check
+```
+
+## Contributing
+
+Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Run tests and quality checks (`uv run pytest && uv run ruff check .`)
+4. Commit with conventional commits (`git commit -m 'feat: add amazing feature'`)
+5. Open a Pull Request
+
+## License
+
+MIT -- see [LICENSE](LICENSE) for details.