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.
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.
The script scripts/configure
allows to replace the following in all files defined in the script:
REPONAME
: The name of your Git repositoryPACKAGE_NAME
: The name of your packageGITHUB_NAME
: The name of GitHub account under which the repo is hostedAUTHOR_NAME
: The name of author of the repo/packageAUTHOR_EMAIL
: The email of author of the repo/packageMAINTAINER_NAME
: The name of maintainer of the repo/packageMAINTAINER_EMAIL
: The email of maintainer of the repo/package
This template took inspiration from several repos, including:
Describe the key features of your package.
# clone project
git clone https://github.com/GITHUB_NAME/REPONAME.git
# install project
cd REPONAME
pip install .
pip install -r requirements/install.txt
Simple installation from PyPI
pip install PACKAGE_NAME
From Conda
conda install PACKAGE_NAME -c conda-forge
Describe step 1
Python examples
Describe step 2
Python examples
If you have any questions please:
- Read the docs.
- Look it up in our forum (or add a new question)
- Search through the issues.
- Join our slack.
- Ask on stackoverflow with the tag PACKAGE_NAME.
Please observe the LICENSE license that is listed in this repository.
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.
To customize this repo, you need to have a look at the following chapters.
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 thesetup.py
, or you won't be able to install your package anymore!
This template repo uses main
as name for the principal branch. If you still use master, change all occurrences of main
to master
.
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 importversion
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 byfind_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 frameworkunittest
, 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 yourREADME.md
long_description_content_type
defines your description type; I set it to markdown in most casesinstall_requires
is a list containing all your package requirements. They are automatically parsed from arequirements.txt
filetests_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 featuresauthor
andauthor_email
specify who you are.license
specifies the license you want to release your code with. This is parsed from aLICENSE
file.
There are still many other options to include here, but these are the most basic ones.
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
The .codecov.yml
file specifies, how coverage should behave, how to calculate the coverage (i.e. what files to include for line counting) etc.
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.
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.
The setup.cfg
file defines the rules for flake8 and pycodestyle syntax checking, versioneer, coverage, building wheel and the metadata which shall be included.
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.
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.
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
andMac
. - tests of the notebooks for Python 3.6, 3.7 and 3.8 on
Linux
,Windows
andMac
. Build Docs
to generate the html versions of the.rst
files in thesource
folderPyPI Release
to automatically publish the package on pyPI.Issue and pr Labeling
to automatically label issues and pull requests. You can define your customhere
.Team Labeling
to automatically pull requests based on the team in which the user is. The teams can be definedhere
.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.
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.
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.
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.