template-repo-python

This repository contains a fully-functional package structure including CI/CD workflows and (empty) tests.

Key Features • How To Use • Docs • Examples • Licence

Change all occurrences of FlorianMF and template-repo-python. They are used set here only to check that the code works.

Python Version	Platform	Unittests	NotebookTests

For more badges check https://github.com/badges/shields. You can as well copy the badge code directly from the actions tab in your GitHub repo.

Info about this template

Template Content

It's features include (but are not limited to):

• An already working package structure
• A working requirement handling
• Automatic PyPI releases
• Pre-Configured CI/CD (with Github Actions or CircleCI)
• Code coverage analysis
• Python Code Style Checks
• Issue and pull request templates

If you want to add something to this repo, please submit a PR. Contributions are very welcome.

Scripts

The script scripts/configure allows to replace the following in all files defined in the script:

• REPONAME : The name of your Git repository
• PACKAGE_NAME : The name of your package
• GITHUB_NAME : The name of GitHub account under which the repo is hosted
• AUTHOR_NAME : The name of author of the repo/package
• AUTHOR_EMAIL : The email of author of the repo/package
• MAINTAINER_NAME : The name of maintainer of the repo/package
• MAINTAINER_EMAIL : The email of maintainer of the repo/package

Inspiration

This template took inspiration from several repos, including:

• Justus Schock's template repo
• Pytorch Lightning
• Pytorch Lightning Bolts

---

What to maintain

---

Key Features

Describe the key features of your package.

How to Use

Step 0: Install locally

# clone project
git clone https://github.com/GITHUB_NAME/REPONAME.git

# install project
cd REPONAME
pip install .
pip install -r requirements/install.txt

Step 0: Install from remote

Simple installation from PyPI

pip install PACKAGE_NAME

From Conda

conda install PACKAGE_NAME -c conda-forge

Step 1: ...

Describe step 1

Python examples

Step 2: ...

Describe step 2

Python examples

---

Examples

Hello world

hello world example

Example category 2

example 1

example 2

---

Asking for help

If you have any questions please:

1. Read the docs.
2. Look it up in our forum (or add a new question)
3. Search through the issues.
4. Join our slack.
5. Ask on stackoverflow with the tag PACKAGE_NAME.

---

Licence

Please observe the LICENSE license that is listed in this repository.

BibTeX

If you want to cite the framework feel free to use this:

@misc{ARTICLE_NAME,
 title={TITLE},
 author={AUTHOR_NAME},
 journal={GitHub. Note: https://github.com/GITHUB_NAME/REPONAME},
 volume={VOLUME},
 year={YEAR}
}

You should modify everything in CAPS.

---

What to change

To customize this repo, you need to have a look at the following chapters.

Directory-Name

You might want to customize your package-name.

To do this, you simply have to rename the REPONAME directory to whatever you want.

Make sure, to also change the PACKAGE_NAME in the setup.py, or you won't be able to install your package anymore!

Main/Master branch

This template repo uses main as name for the principal branch. If you still use master, change all occurrences of main to master.

Python Package Metadata

To customize your python package, you just have to change your setup.py file.

The minimal setup looks like this:

setup(
    name='PACKAGE_NAME',
    version=_version,
    packages=find_packages(),
    url='https://github.com/GITHUB_NAME/REPONAME',
    test_suite="unittest",
    long_description=readme,
    long_description_content_type='text/markdown',
    install_requires=requirements,
    tests_require=["coverage"],
    python_requires=">=3.6",
    author="AUTHOR_NAME",
    author_email="AUTHOR_EMAIL",
    license=license,
)

This includes the default information and must be adjusted to your needs:

• name provides the package-name you can later import
• version provides the package-version (which will currently be extracted from your package's __init__.py, but be also set manually)
• packages is a list defining all packages (and their sub-packages and the sub-packages of their sub-packages and so on...), that should be installed. This is automatically extracted by find_packages, which also accepts some sub-packages to ignore (besides some other arguments).
• url specifies the packages homepage (in this case the current GitHub repo); You might want to change it to your repos homepage.
• test_suite defines the test-suite to use for your unittests. In this repo template, we'll python's built-in framework unittest, but you can change this too; Just make sure to also change this, when we get to CI/CD.
• long_description does what it sayes: It provides a long description of your package. Currently this is parsed from your README.md
• long_description_content_type defines your description type; I set it to markdown in most cases
• install_requires is a list containing all your package requirements. They are automatically parsed from a requirements.txt file
• tests_require does the same thing for your unittests.
• python_requires specifies the python version, your package can be installed to (here it's been set to python 3.5 or above, since this is what I usually use). Depending on the version you specify here, you might not be able to use all of python's latest features
• author and author_email specify who you are.
• license specifies the license you want to release your code with. This is parsed from a LICENSE file.

There are still many other options to include here, but these are the most basic ones.

Unittests

If you want to add/change some unit-tests, you should do this in a new python file starting with test_. Here is a good introduction on how to write unittests with the unittest framework. After you added these tests, you may run them with either coverage run -m unittest or python -m unittest.

They are basically doing the same, but coverage additionally checks, how many of your code-lines are currently covered by your tests.

The unittests are also automatically triggered within CI/CD

Specifying Codecov

The .codecov.yml file specifies, how coverage should behave, how to calculate the coverage (i.e. what files to include for line counting) etc.

Requirements

If you want to add new requirements, simply add them to the requirements/install.txt file. Special requirements for testing or docs building can be set here and here.

Packaging on PyPI

If you plan to release your package on PyPI, ship wheels for it, you might need the MANIFEST.in file, since it specifies (among other things), which files to include and which to exclude from your binaries.

Setup.cfg

The setup.cfg file defines the rules for flake8 and pycodestyle syntax checking, versioneer, coverage, building wheel and the metadata which shall be included.

Gitignore

The .gitignore file is a real life saver. It prevents files and directories that match certain patterns from being added to your git repository, when you push new stuff to it. You may append more specific patterns here.

CI/CD

This repository uses GitHub Actions and/or CircleCI as CI/CD.

Choose which one you want to use. Maybe both? Modify the .yaml files to your will, erase them or add new ones.

YAML-Specifications

The files inside the folders .github/workflows and .circleci specify the CI/CD behavior. Currently, are run:

• Style Check according to PEP8 with automatic fixing and committing.
• unittests for Python 3.6, 3.7 and 3.8 on Linux, Windows and Mac.
• tests of the notebooks for Python 3.6, 3.7 and 3.8 on Linux, Windows and Mac.
• Build Docs to generate the html versions of the .rst files in the source folder
• PyPI Release to automatically publish the package on pyPI.
• Issue and pr Labeling to automatically label issues and pull requests. You can define your custom here.
• Team Labeling to automatically pull requests based on the team in which the user is. The teams can be defined here.
• Stale Checker for issues and pull requests.
• Greetings for first issues and pr and automatic labeling are also implemented.
• Rebase to autom. rebase the branch of a pull request when commenting /rebase.
• Install package to autom. check if the created package can be build.
• #TODO add code-formatting.yml
• #TODO add ci-testing.yml
• #TODO add docker-builds.yml

You may add additional GitHub actions. Check out the marketplace for actions created by the community.

For the moment several of these workflows are disabled. Remove the line if: false or replace the condition if you want to use these workflows.

Docker

If you want to use GitHub and CircleCi workflows for Docker you need to do the following here and here:

• Replace DOCKER_AUTHOR_NAME with your name on Docker
• Replace DOCKER_REPONAME with the name of your package on Docker

Your should also modify the Dockerfiles in the subdirs of the dockers folder to create your personal Docker workflows.

Badges and logo

You can adapt the badges to your will. You can maintain the above, the links to GitHub will automatically modified when running scripts/configure.py. See here.

To modify the logo simply place a new one in formats .svg and .png here.

Documentation

The documentation is build using Sphinx. The resulting html files are in the build folder.

You should modify the conf.py to fit your needs. Especially it's part on extracting lines from the README has to be adapted in order to use the getting_started.rst.

Next rewrite the .rst file in the source folder.

If you need some guidelines on how to use the .rst files, run the build_docs script and read the built html files.