Kwik

⚠️ Pre-Release Software Warning

Kwik v1.0 has been released and is ready for production use. The internal APIs, data structures, and framework interfaces are now stable. While not guaranteed, we strive to maintain backward compatibility following semantic versioning principles.

Documentation: https://davide.mezzogori.com/kwik/

Fast, batteries-included, business-oriented, opinionated REST APIs framework

Acknowledgments

Python 3.12+

Kwik stands on the shoulder of a couple of giants:

• FastAPI: for the underlying REST API server.
• Pydantic: for the data validation and serialization.
• SQLAlchemy: for the ORM part.

Installation

$ pip install kwik

or

$ uv add kwik

It will install Kwik and all its dependencies.

Development

Setup

# Clone the repository
git clone https://github.com/dmezzogori/kwik.git
cd kwik

# Install dependencies using uv
uv sync

# Start development server with hot reload
kwik

Testing

# Run all tests with coverage (testcontainers automatically manages PostgreSQL)
pytest --cov=src/kwik --cov-report=term-missing

# Run tests in parallel (faster)
pytest -n auto

# Run specific test file
pytest tests/crud/test_crud_users.py

# Run only unit tests (skip integration tests)
pytest -m "not integration"

Note: Tests use testcontainers to automatically manage the PostgreSQL database. No manual database setup required (just docker).

Code Quality

# Run linter and formatter
ruff check
ruff format

Documentation

# Start documentation website locally
cd docs
docker compose up

# Access at http://localhost:8000

Listing queries (DX)

• Unified dependency kwik.dependencies.ListQuery combines pagination, sorting, and filtering for list endpoints.
• Query params supported:
  • skip and limit for pagination (stable default ordering by primary key when no sort is provided)
  • sorting as comma-separated fields with optional direction, e.g. ?sorting=name:asc,id:desc
  • filter_key and value for simple equality filters, e.g. ?filter_key=is_active&value=true
• Example endpoint:
  • def list_users(q: ListQuery, context: UserContext) -> Paginated[UserProfile]: total, data = crud_users.get_multi(context=context, **q) return {"total": total, "data": data}
• Invalid filter/sort fields return HTTP 400 with a clear message.

Contributing

1. Create a feature branch (git checkout -b feature/your-feature-name)
2. Make your changes following the existing code style
3. Add tests for new functionality
4. Run tests and ensure they pass
5. Run linting and fix any issues
6. Commit your changes (git commit -am '<Your commit message>')
7. Push to the branch (git push origin feature/your-feature-name)
8. Create a Pull Request

License

This project is licensed under the terms of the MIT license.