Radonirinaunimi / python-template

Python project template 🐍.

	pytemplate serves as a general template to start a python project. It aims to automate the development workflow: from packaging the code, generating documentation, versioning, deploying and releasing the package.

Description

The development workflow is based on the following steps:

Packaging 📦 The packaging of the distribution is managed by the Distribution Utilities (Disutils). This allows users (or developers) to easily install the package (or to simulate the installation by adding a symbolic link for easy debug) into a particular environment.

Continuous testing 🛠️ For stability, the modules of the packaged-library can be automatically tested using pytest. This helps prevent breaking the code when new features are added. These tests can be run as github-actions when the events are triggered (as will be detailed further). The coverage of the tests can then be assessed afterward; the more modules undergo testing the less likely bugs occur. Refer to the web documentation for further details on how to use pytest for testing.

Documentation 📚 The documentation of nodules is built using the following style with sphinx. To familiarize with sphinx, have a look at the following documentation.

Deploying docs and Publishing to PyPI 🚀 Finally, all of the above can be integrated within github using github actions CI/CD. This allows one to test the package at every push (for instance) and deploys the documentation. The follwoing documentation explains the syntax for writting a github action.

How to use this template

Setting up ⚙️

In order to use this template, first, click on use this template. Then, replace all mentions of package_name in the following files setup.py, Makefile, test_modules.yml, conf.py by the name of the package. The next step is to add the requierements the package is depending to requirements.txt. Essentially, these the only things one need to package the distribution. The package is now ready for installation by running the following:

python setup.py install [--user]

or alternatively (if you are a developer) by adding symbolic links which immediately reflects the changes after every save:

python setup.py develop [--user]

Checking, formatting and testing the code

Using static code analysis tools can be extremely helpful in terms of checking programming errors and enforcing coding standards. As an analysis tool, this template uses pylint which is highly customazable. The default configurations are given in the .pylintrc file. To check a given python file, it suffices to run:

pylint <python_file>.py

For an automated code formatting, one may also resort to black which is a very high efficient code formatter. Finally, the test of the modules can be performed using pytest. The test files can be put inside the tests. Then, to peform the tests, just run:

pytest <python_file>.py or pytest --cov=<package_name> tests/ (if you want to generare reports)

Writing and building documentation 📘

In order to adopt good practices for writing documentation, refer to the following short guidelines. As default, this template uses sphinx as a python documentation tool which (for a local build) requires the installation of sphinx and shpinx_rtd_theme. For a deep dive into the sphinx tool, have a look at this documentation.

In order to build the documentation in your local machine, go inside the doc folder and run the following command:

make html

and to view the rendered document, just run:

make view

Tagging versions 🎉

Semantic versioning is an important part in building packages. For the best practices in tagging versions, refer to the following documentation. As a version management tool, this templates uses bump2version whose configuration file is defined in .bumpversion.cfg. The current version is 0.1.0-dev, and in order to update if, run the following command:

bump2version minor # or major

For more details about the configuration of bump2version, head on to this github repository.

Automating pipeline with github actions 🛡️

Before pushing to the github , make sure to modify the actions in the workflows folder. Specifically, one must replace the value never in the branches entry. For instance, one can choose on: push to run the actions whenever a new implementation is pushed on any branches.

In order to deploy the documentation, the GITHUB_SECRETS must be replaced by your own secrets,

    - name: Deploy 🚀
      ...
        ACCESS_TOKEN: ${{ secrets.GITHUB_SECRETS }}

Check this documentation to learn how to generate github-tokens, and the following on how to add tokens to secrets. The PyPI token has to be generated from here by creating and account and added to the repository in the same way as for the documentation. Similarly, the Codecov token can be generated from here for a specific repository.

Useful links

Awesome python	github | webpage
All algorithms implemented in python	github
PyGithub: Typed interactions with the GitHub API v3	github | webpage

Projects using this template

With v.0.0.1 (as a proof of concept):

Package	Description
Timst	Image style transfer using pyTorch.
CheckPwd	Python package that checks if your credentials have been leaked to the web.