Quickstart

Getting Started

Make sure that you have a working Python interpreter in version at least 3.8, git and poetry installed.

To install the template, run pip install fair-python-cookiecutter.

Now you can use the tool to generate a new Python project:

fair-python-cookiecutter YourProjectName

This will spawn an interactive prompt, where you have to provide some information and make some choices for your new software project. Don't worry, you can always adapt everything later on by hand. After this, your software project will be created in a new directory.

To save you some time answering the questions, we recommend that you create an empty repository in GitHub or GitLab of your choice (i.e., the location where you plan to push your new project).

If you already have created an empty remote repository or know exactly its future location, you can provide the URL, which already will provide many required inputs:

fair-python-cookiecutter --repo-url https://github.com/YourOrganization/YourProjectName

Your new project repository will also include a copy of a developer guide, containing more information about the structure and features of the generated project.

Please familiarize yourself with the generated structures, files and the contents of the developer guide. Feel free to either remove the guide afterwards, or keep (and possibly adjust) it as extended technical project documentation for yourself and other future project contributors.

You can find a demo repository generated from this template here.

Example Code

When you are creating your project, you are asked for several inputs. You can have an example CLI(Command Line Interface) and/or API(Application Programming interface) code within your new project.

Lets assume your project name is my-awesome-project.

You can run the CLI App with below command. For further usage, please check typer documentation.

poetry shell

# Run your CLI App
my-awesome-project-cli calculate add 5 2

You can run the API App with below command.

poetry shell

# Run the API program, it will be open for connection
my-awesome-project-api

Now, you can a tool to send a HTTP request for the API. You can open another terminal and run this command

# send a request that does the same thing as the CLI
curl 'http://localhost:8000/calculate/add?x=5&y=2'

For further usage of the API, please check fastAPI documentation.

Configuring the Template

If you intend to use the template a lot, e.g. if you want to use (an adaptation of) this template as the default way to start a Python project for yourself and/or others, you might want to configure some template variables in your ~/.cookiecutterrc. Here is an example cookiecutter configuration:

fair_python_cookiecutter:
    last_name: 'Carberry'
    first_name: 'Josiah'
    project_keywords: 'psychoceramics analytics'
    email: 'josiah.carberry@brown.edu'
    orcid: '0000-0002-1825-0097'
    affiliation: 'Brown University'
    copyright_holder: 'Brown University'
    license: 'MIT'

This information will be already pre-filled when you use the template, saving you some time and possibly avoiding possible mistakes from manual typing.

Modifying the Template

If you want to adjust it to your needs and likings (e.g. add, remove or substitute certain tools), you probably want to fork it to get your own copy. Then you can do the desired changes and use the URL of your template repository instead of this one to kickstart your projects.

However, if you think that your changes are of general interest and would improve this template for a majority of users, please get in touch and contribute or suggest an improvement!

In any case we are very happy to know about any similar or derivative templates, e.g. for more specific use-cases or based on other tool preferences.

Reusing Parts of the Template

If you already have an existing project where you would like to introduce things you like from this template, there are two main ways to do so:

1. move your code into a fresh repository based on this template
2. use parts of the template in your existing project structure

If your project currently has no sophisticated setup of tools or strong preferences about them, option 1 might be the simplest way to adopt the template. Your code then needs to be moved into the YOUR_PROJECT/src/YOUR_PACKAGE subdirectory.

On the other hand, if you already have a working setup that you do not wish to replace completely, you can take a look at

• the .pre-commit-config.yaml file to adopt some of the quality assurance tools listed there
• the CI pipelines defined in .github/workflows or .gitlab-ci.yml for automated tests and releases
• the mkdocs.yml and docs/ subdirectory to see how the project website works