Development

Getting started

fastapi_aad_auth is a volunteer maintained open source project and we welcome contributions of all forms. The sections below will help you get started with development, testing, and documentation. We’re pleased that you are interested in working on fastapi_aad_auth. This document is meant to get you setup to work on fastapi_aad_auth and to act as a guide and reference to the development setup. If you face any issues during this process, please open an issue about it on the issue tracker.

Setup

fastapi_aad_auth is an extension component to fastapi to provide Azure Active Directory authentication, written in Python. To work on it, you'll need:

  • Source code: available on GitHub. You can use git to clone the

    repository:

    git clone https://github.com/djpugh/fastapi_aad_auth
cd fastapi_aad_auth

  • Python interpreter: We recommend using CPython. You can use this guide to set it up.

  • tox: to automatically get the projects development dependencies and run the test suite.

  • Azure Active Directory App Registration: We recommend following the configuration section in usage

Running tests

fastapi_aad_auth tests are written using the pytest test framework. tox is used to automate the setup and execution of fastapi_aad_auth tests.

To run tests locally execute:

tox -e test

This will run the test suite for the same Python version as under which tox is installed.

Integration tests

fastapi_aad_auth is very tightly coupled to Azure Active Directory, so most of the full tests follow manual testing of the testapp. This needs configuring with Azure Active Directory App Registrations (see Configuring the Azure Active Directory App Registration) and the testapp environment using a .env file (see Configuring the fastapi environment).

To run the testapp use tox (or directly with python tests/testapp/server.py:

tox -e testapp

This will run the test app for the same Python version as under which tox is installed.

Configuring the testapp

The testapp requires configuring (see Configuring the Azure Active Directory App Registration) for how to configure an appropriate App Registration on Azure. The app provides a really simple set of tests - the home page has no authentication, but if you have logged in, it will say "hello <email>", with your logged in email.

The api docs (swagger UI) is authentication limited, as is the simple api endpoint '/hello'.

Running linters

fastapi_aad_auth uses flake8 and extensions for managing linting of the codebase. flake8 performs various checks on all files in fastapi_aad_auth and uses tools that help follow a consistent code style within the codebase. To use linters locally, run:

tox -e lint

Note

Avoid using # noqa comments to suppress linter warnings - wherever possible, warnings should be fixed instead. # noqa comments are reserved for rare cases where the recommended style causes severe readability problems.

Building documentation

fastapi_aad_auth documentation is built using Sphinx. The documentation is written in reStructuredText. To build it locally, run:

tox -e docs

The built documentation can be found in the docs/html folder and may be viewed by opening index.html within that folder.

Release

We release through GitHub using an automated process to collate and test the releases.

Developing

Submitting pull requests

Submit pull requests against the master branch, providing a good description of what you're doing and why. You must have legal permission to distribute any code you contribute to fastapi_aad_auth and it must be available under the MIT License. Provide tests that cover your changes and run the tests locally first. fastapi_aad_auth supports multiple Python versions. Any pull request must consider and work on all these platforms.

Pull Requests should be small to facilitate review. Keep them self-contained, and limited in scope. Studies have shown that review quality falls off as patch size grows. Sometimes this will result in many small PRs to land a single large feature. In particular, pull requests must not be treated as "feature branches", with ongoing development work happening within the PR. Instead, the feature should be broken up into smaller, independent parts which can be reviewed and merged individually.

Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines or whitespace within lines. Such changes can be made separately, as a "formatting cleanup" PR, if needed.

Automated testing

All pull requests and merges to master branch are tested using Github actions (configured by .github/workflows/pipeline.yml file. You can find the status and results to the CI runs for your PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the specific builds in the form of "Details" links, in case the CI run fails and you wish to view the output.

Compatibility Requirements

We endeavour to support (and test) on multiple python versions, across the following matrix of os and python versions:

os:
  - ubuntu
  - windows
  - macos
py:
  - 3.6
  - 3.7
  - 3.8
  - 3.9