FAST-OAD plugin template

Introduction

This template repository is dedicated to the development of FAST-OAD models, possibly packaged as a FAST-OAD plugin. These developments are explained in FAST-OAD documentation.

This README file explains how to use this template repository. Once your project is set up, you are invited to erase this content and write your own README file, suited to your project.

It is assumed that you know how to use Git, Python and FAST-OAD.

This template is designed to use Poetry (version 1.4.2 or above) for managing the development environment. Instructions below assume you have it already installed. You may adapt them if you don't want to use Poetry.

Note: In this document, any leading slash (/) in a path refers to project root.

Setting up your project

After copying the content of this repository and initiating your own Git repository, you should take the following steps:

Rename your plugin

In /src folder, rename the rename_me folder. It will be the name of your Python module.
In /pyproject.toml file:
- In tool.poetry section:
  - Use the new name of your Python module in the packages field.
  - Modify the name field with the name you want for your package (will be used in pip install, for instance).
- In tool.poetry.plugins."fastoad.plugins"section:
  - Use the name of your Python module in the packages field (right-hand of the equal sign).
  - Name your FAST-OAD plugin in the left-hand of the equal sign. Using the package name is recommended.

Install your working environment

Before creating your working environment, you may want to have a look at defined dependencies in /pyproject.toml file.
Typing poetry install in your terminal will create a virtual environment and install all defined dependencies in it.

Setup Git hooks

Simply run:

pre-commit install

(see below for more details)

Local development tools

This template repository contains various configuration files to ease development.

Here are tools that will work in your local development environment.

Pytest

Pytest is recommended for writing tests. The development environment is set with code coverage tools.

Pytest and its companions are configured in /pyproject.toml file.

It is recommended to have unit tests in tests folders next to tested code. Other kind of tests (integration, non-regression) should be in the /tests folder

Unit tests will be launched with simply:

pytest

To activate code coverage during unit testing, type:

pytest --cov

Other tests will be launched with

pytest tests

Jupyter notebooks can also be tested using:

pytest --nbval-lax -p no:python

Note: with --nbval-lax, as said in nbval documentation, pytest "runs notebooks and checks for errors, but only compares the outputs of cells with a #NBVAL_CHECK_OUTPUT marker comment". If you want nbval to check all cell outputs against already saved ones, you need to use --nbval as option.

Ruff

checks/corrects code style and automates the code formatting.

Kudos to Black and Flake8 that are very good tools. Yet, for a fresh start, Ruff seems the way to go, since it does the same job as these two, only much faster.

Ruff is configured in /pyproject.toml file.

Coupled with pre-commit (see below) and/or integrated with your IDE, it automates all the code formatting, and it is sooo good.

Note to PyCharm users: there is a ruff plugin.

pre-commit

pre-commit is used to set up Git hooks for Ruff.

pre-commit is configured in /.pre-commit-config.yaml file.

As already said, hooks are activated with:

pre-commit install

This operation has to be done only once in your development environment. Yet, you will have to do it again if the configuration file has been modified.

The installed hooks will interrupt the commit process if Ruff reformats a file or if it detects a mistake.

In case of interruption, simply check the Git output messages and see what happened.

If the interruption comes from reformatting, doing the commit again should work. The interruption simply allows you to check the reformatted files before doing so.

If the interruption comes from Ruff check, you will have to fix the identified mistake before doing your commit again. Running ruff check --fix might help for the simplest problems.

Online tools

This section could be expanded in the future with settings for Binder, Codacy, CodeClimate, Codecov and GitHub actions.

fast-aircraft-design/FAST-OAD_plugin_template