12rambau / pypackage

The skeleton of a python package

Pypackage

The skeleton of a python lib embeding what I like:

• pre-commit hooks (prettier, ruff, black)
• nox unit tests (doc, pytest, mypy)
• a documentation structure based on Sphinx using the pydata-sphinx-theme
• a complete github folder (README, LICENSE, etc...)
• an automated citation file
• github actions (test, coverage, mypy, lint)
• ready to publish on pipy
• ready to publish on readthedocs
• ready to link to codecov

Demonstration

The package end result is demonstrated in the pypackage-skeleton repository.

Usage

1. Define a project name. It can be anything with any normal character (w+) like "Python Project".
2. Init an empty github repository with the slug name of your project. A slug should only use lower case characters and replace all spaces with - like "python-project".
3. Enable the repository on codecov and add a CODECOV_TOKEN github action env variable.
4. Start a new readthedocs project hooked to the repository. in the admin tick the "build on PR" option.

5. In your local computer start the project by running the following code. Set the same names as in the github repository.

   Note

   You will need to install 2 extra python libs if it's not already done, copier and jinja2-time.

   pip install copier jinja2-time

   copier copy --trust gh:12rambau/pypackage <python-project>

6. Go to the folder and init the git project:

   cd python-project
   git init

7. Run nox tests to see if everything is working. This command will run the 4 nox sessions.

   nox

8. Install pre-commits:

   pre-commit install

9. Push to distant repository following Github instructions

   git add .
   git commit -m "build: initial commit"
   git remote add origin [e-mail]:<username>/<python-project>.git
   git branch -M main
   git push -u origin main

10. Once you are ready to make a release (or a pre-release to lock the name), Create a new project on pipy by running the first push yourself using version number 0.0.0:

    python -m build
    twine upload dist/**

11. Modify the lib as you see fit

12. Update version with commitizen tools:

    cz bump

13. Add a token to a new github action env variable PYPI_PASSWORD from your pypi profile. limit the scope to this repository only.
14. Start a new release in github and let actions do the rest
15. The generated package will automatically detect new releases of the template and create update PR. To allow this workflow to work, one needs to give "Read and write permissions" to Workflow and Actions in the "Manage access" tab of the repository settings. One should also "Allow GitHub Actions to create an approve pull requests".