Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/radonirinaunimi/python-template

Python project template 🐍.
https://github.com/radonirinaunimi/python-template

coverage development-workflow documentation python python-template sphinx template-repository unittest

Last synced: about 1 month ago
JSON representation

Python project template 🐍.

Awesome Lists containing this project

README 

        

  

    

      Logo

    

    

      

      

    

  

  

     

      


        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:  




```bash

python setup.py install [--user]

```

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

```bash

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:




```bash

pylint .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:




```bash

pytest .py or pytest --cov= 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:




```bash

make html

```

 and to view the rendered document, just run: 



```bash

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:




```bash

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,

 



```yaml

    - 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.