This repository contains a small example application to showcase how to design a service in a reusable way, so that it can be consumed as both a CLI and a web service.
All of the core processing logic for this simple service is contained within src/arithmeticsvc/arithmetic.py
.
Note, this project uses Poetry for dependency management and environment isolation. I highly recommend you use Poetry for these purposes. If you are using
pip
, replace the initial install command withpip install
, and you can follow along by omitting thepoetry run
parts of the commands. The testing steps will not work, however, sincepip
does not install the test dependencies.
- Clone this repository
- Install dependencies with
poetry install
- Run the tests with
poetry run pytest
- Try out the CLI by running
poetry run arcli --help
.- Example:
poetry run arcli add 45 50
- With binary output:
poetry run arcli -o bin 12 5123
- Example:
- Try making calls to the server (while it's not running) with
poetry run arcli web --help
- You should get "ConnectError" issues
- Start up the web server with
poetry run fastapi dev src/arithmeticsvc/api.py
- By default, this will start up the server with
dec
output type. To start withhex
output type (for example), you can runARITHMETIC_OUTPUT_TYPE=hex poetry run fastapi dev src/arithmeticsvc/api.py
- By default, this will start up the server with
- In a different shell, make calls to the web server with
poetry run arcli web
- You can change the output type of the running service with
poetry run arcli web output
- Try calling the multiply API with
poetry run arcli web multiply 50 3
- You can change the output type of the running service with
If you're interested in giving a try to improve this basic app, try out some of the following exercises! Most can be done without having to fork the repository, but I recommend doing so to track the changes you've made in your own git history.
- Currently, only tests for the service itself are available. As an exercise, try adding tests for the CLI and the API by following the documentation for
typer
andfastapi
respectively. - The
ArithmeticService
naively computes with the values given. Can you think of a way that this service might produce errors? Find the spot where there is a bug in the server that would cause a runtime exception, and fix the bug! This can be done in many ways, so feel free to pick whichever way works best for you. - Expand the
ArithmeticService
to support more operations. - Add support for running the API with Docker! Write a Dockerfile
- As an extra challenge, write a
docker-compose.yaml
file that spins up the service. Test that you can access the container from the CLI!
- As an extra challenge, write a
- Currently, the
cli
bundles both the service and the web client. Try to separate the two by moving the web client to its own CLI, then try running the new CLI! - This repository doesn't have any automated testing involved in it. Fork this repository and try to write a Github Actions workflow to run the following tests and checks:
pytest
ruff
bandit
<-- Note! You will need to make sure it only scanssrc/
since thetests
diretory usesasserts
, which causes low-level security scan failuresmypy