Blacksheep API template

Description

A template for Blacksheep-based API with the following features:

• Flexible package manager: hatch, poetry or pip
• Separated requirements.txt files for the app, for development and for documentation.
• Using environment variables for separated development and production execution
• Unit-testing setup with working autodiscovery in VSCode
• Swagger UI on /docs endpoint
• Path-based API versioning
• Class-based views and endpoints
• Response types based on dataclasses.dataclass
• Fast JSON serializer using orjson
• Async template rendering
• Built-in anti-forgery (commented out in server.py)
• MkDocs for documentation
  • Automated source code docstring extraction
  • API documentation from openapi.json - needs to be saved before
  • Clear structure

Usage

Even if using this template is possible with regular pip+virtualenv tool combination I kindly recommend to use hatch as a more powerful package and task management tool.

Once hatch is installed on your Linux (physical, WSL, Docker or VM) environment using this template is very simple. The main tasks are included into pyproject.toml so you only need the required command to perform these tasks:

• Start dev server

  hatch run serve

• Run tests

  hatch run test:test

• Run tests with coverage measurement

  hatch run test:test-cov

• Generate coverage report (lcov and xml, usable with coverage-gutters VSCode extension)

  hatch run test:cov

• Doc development with live reload

  hatch run doc:serve

• Build the docs into ./build/docs

  hatch run doc:build

• Format check (ruff)

  hatch fmt --check

• Formatting

  hatch fmt

• Build wheels and sdist packages

  hatch build

Debug setup

With VSCode use the following launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python Debugger: Server",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/src/app/server.py",
            "console": "integratedTerminal",
            //"args": "${command:pickArgs}",
            "env": {
                "APP_ENV": "dev",
                "PYTHONPATH": "${workspaceFolder}/src"
            }
        }
    ]
}

Contribution

Create your fork and submit pull-requests.