Tutorial Setup

Note

To follow along with this tutorial you’ll need a few things:

• Python 3.8+

• Node 18+ (hint use nvm)

• (Optional) GNU Make

Checkout the Code

The easiest way to follow along is to checkout the Cannula repo and open up the examples/tutorial folders. We have the code for each section as we add complexity to the application. You’ll want to start at part0 and move back and forth as needed until you have mastered GraphQL:

git clone git@github.com:rmyers/cannula.git
cd cannula/examples/tutorial

We like GNU Make and use Makefiles for all our projects as it simplifies setup especially for beginners. In this folder you’ll find a Makefile that has setup and help target:

make setup

Note

If you are on MacOS you may need to install the xcode command line tools:

xcode-select --install

This will create a virtualenv venv with all the dependencies we need installed:

aiosqlite==0.19.0         # Async version of sqlite
cannula==0.11.0           # The reason you are reading this
click==8.1.7              # Command line tool helper
fastapi[all]==0.108.0     # The main asgi application logic
greenlet==3.0.3           # For sqlalchemy async support
pydantic_settings==2.1.0  # Configurations via ENV variables
ruff==0.1.4               # For formatting the code
sqlalchemy==2.0.25        # For database table access
uvicorn==0.25.0           # Web server for asgi applications

# Testing Tools
pytest<8
pytest-asyncio
pytest-cov
pytest-httpx
pytest-mock

Create the initial application

We’ll call our application dashboard since we are not creative. This will just need the following stucture:

dashboard/
    core/
        app.py         # The FastAPI application
        config.py      # Configuration settings for the application
        database.py    # Database schema
    part1...n/         # Remaining sections of this tutorial
    templates/
        index.html
    __init__.py
    __main__.py        # Click commands to run tasks `python -m dashboard <command>`

We are going to use FastAPI since it is a very good ASGI application base. Since it does not have any actual webserver process, we will need to serve the application with uvicorn. Jinja2 is used for the templates so there is a little bit of setup we have to do in order to server the application.

To start up the application just run the command:

make run

Then open your browser and visit http://localhost:8000:(http://localhost:8000)

For this tutorial we have setup 100% unit test coverage. We feel like it is best to show by example, and the best developers write tests. Maintaining 100% coverage is easier if you start with full coverage. This can then be enforced with a single line fail_under = 100. What we really like about this is that it makes CI do the dirty work of scolding developers that do not write tests. Nobody likes that person on the team who constantly nit picks PR’s. It is best for that person to be a machine, one it is less personal, and two they can’t be bribed for a +1.

For our tests we are using pytest and a few plugins, the most important one being pytest-asyncio. This plugin makes it easy to write tests for our async handlers we have this set to auto mode in our configuration:

[tool:pytest]
asyncio_mode = auto
minversion = 6.0
addopts =
    -vvv
    --cov=dashboard
    --cov-report=term-missing
testpaths = tests

[coverage:report]
omit = dashboard/__main__.py
fail_under = 100
ignore_errors = True