This section is adapted from: https://cookiecutter-pypackage.readthedocs.io/en/latest/tutorial.html. Creating your package should take less than 5 minutes with the minimal options (cookiecutter + PyCharm), and less than 30 minutes if you use all the goodies (Virtual environment, GitHub, etc).
Your project will need a project name (e.g. My Toy Package) and a project slug (typically
my_toy_package
). Before starting,
check that your project slug is not used in PyPI,
even if you do not plan to use PyPI for the moment.
In a terminal (e.g. Anaconda Prompt):
Go to the parent directory of where you want to put the directory of your package, e.g.
D:\GitHub\
.
cookiecutter https://github.com/francois-durand/package_helper_2.git
Answer the questions. Here is an example (some explanations follow):
full_name [François Durand]: François Durand
email [fradurand@gmail.com]: fradurand@gmail.com
github_username [francois-durand]: francois-durand
project_name [Python Boilerplate]: My Toy Package
project_slug [my_toy_package]:
project_short_description [Python Boilerplate contains all the boilerplate
you need to create a Python package.]: My Toy Package is a beautiful package.
version [0.1.0]:
Select main_git_branch_name:
1 - main
2 - master
Choose from 1, 2 (1, 2) [1]:
use_pytest [y]:
use_codecov [y]:
Select command_line_interface:
1 - No command-line interface
2 - Click
3 - Argparse
Choose from 1, 2, 3 (1, 2, 3) [1]:
create_author_file [y]:
Select open_source_license:
1 - GNU General Public License v3
2 - MIT license
3 - BSD license
4 - ISC license
5 - Apache Software License 2.0
6 - Not open source
Choose from 1, 2, 3, 4, 5, 6 (1, 2, 3, 4, 5, 6) [1]:
Some explanations now:
main_git_branch_name
:
your choice must be consistent with the settings of your git application. It is the name of your default
branch in your git projects. If you do not know, it is probably "master", but there is a current tendency
to call it "main" instead and this will probably become standard in a near future.
use_pytest
: there are
essentially three ways to do unit tests in Python: unittest (the standard solution), pytest (the
recommended test package) and doctest (where tests are integrated in the docstrings). If you are new to
testing, I suggest using doctest. But even so, pytest is useful to configure your tests (as we will do a
bit later). For this reason, in all cases, I suggest to answer yes.
use_codecov
: you use Codecov
to assess the coverage of your code by your tests. I suggest answering yes anyway, even if you
do not plan to use Codecov for the moment.
Click
and Argparse
allow you
to easily call your program with unix-style command, e.g.
python my_program.py --help
.
You can choose either of them without harm, even if you do not use it for the moment. But personally,
I answer no.
create_author_file
: I
suggest to answer yes.
A virtual environment is essentially a Python installation dedicated to your project, with its own versions of the third-party packages. It ensures that if you reuse this project several months later, it will still work… However, it can be difficult to use in conjunction with Jupyter Notebook. If using Jupyter is important, I suggest that you do not use virtual environments.
In PyCharm:
Choose "Open" and select the directory of your package.
A prompt window named "Creating Virtual Environment" opens. If you want to create a virtual environment, validate with the default options. Otherwise, cancel.
In the bottom right part of the window, you will probably see some background tasks running. Wait until they are finished.
In the bottom right part of the window, the interpreter should be indicated: something like "Python X.X (your_package)". If "No Interpreter" appears instead, click on it and select the desired interpreter (virtual environment or not).
The file requirements_dev.txt
contains the list of the third-party packages that you need for development, such as
sphinx
or
pytest
, but
that the end-user does not need when using your package.
In PyCharm's terminal:
Ensure you are in the directory of your package (e.g.
D:\GitHub\my_toy_package
).
Ensure that your virtual environment is activated: there should be
(venv)
at the beginning of
the line. If not:
Windows: venv\Scripts\activate
Linux: source venv/bin/activate
pip install -r requirements_dev.txt
This way, your package behaves as if it were installed, but any change you make will have effect immediately.
In PyCharm's terminal, you should still be in the directory of your package. Do:
python setup.py develop
In PyCharm: menu Run → Run → All Tests. It runs all the tests of the project. If you are
new to testing, you can take example from the classes provided by the template, such as
my_class_1.py
.
Open the file cov/index.html
(in your web browser). It displays what parts of your code are covered by the tests.
In PyCharm: menu Run → Run → Generate docs. It generates the html documentation of your project.
The template provides examples of classes, such as the file
my_class_1.py
.
You can use them as models if you are new to Sphinx documentation.
Open the file
build/index.html
(in your web browser). It displays the html documentation of your project.
In PyCharm:
From the file README.rst
of your package, copy the short description sentence, e.g.: "My Toy Package is a beautiful package."
(you will paste it in the form below).
Menu VCS → Share project on GitHub.
Fill in the form and validate, e.g.:
New repository name: my_toy_package
Remote name: origin
Description: My Toy Package is a beautiful package.
Accept to add all the files as proposed by PyCharm.
In a browser, you can go to your GitHub account to check that everything is there.
In GitHub:
GitHub page of your package → Actions.
Check that the actions are successes (it may take several minutes). The "build" action runs the tests of the package. The "docs" actions builds the documentation, and publishes it online if the branch is your default git branch ("main" or "master").
On the GitHub page of your package:
Tell GitHub Pages that the documentation files are in the "gh-pages" branch of your project:
Settings → Pages → Source.
Select "gh-pages".
Select "/ (root)".
Save.
Configure Codecov:
On Codecov's website, log in with your GitHub account. On your main page: Not yet setup → select your project (you may have to wait for syncing before it appears). Then copy the Codecov token.
Back to GitHub: Settings → Secrets → New repository secret. Name:
CODECOV_TOKEN
. Value:
paste the codecov token.
Register your PyPI credentials as "secrets", so that GitHub can automatically publish your package on PyPI for you:
Settings → Secrets.
Select "New repository secret". Name:
PYPI_USERNAME
.
Value: your PyPI username.
Select "New repository secret". Name:
PYPI_PASSWORD
.
Value: your PyPI password.
In PyCharm, make a slight modification, e.g. in the file
README.rst
.
Then commit/push:
Menu Git → Commit.
Enter a commit message.
Commit and push.
Push.
GitHub page of your package → Actions. Wait until your actions are finished.
Check the documentation:
GitHub page of your package (main page) → near the bottom of the page, follow the link to your documentation. Check that the documentation is there.
In the table of contents, click on the first page (e.g. My Toy Package). Depending on your initial choice of options, you should have up to four badges:
PyPI: package or version not found (there will be the version number after your first release).
Build: passing.
Docs: passing.
Codecov: with a percentage.
In the table of contents: Reference → MyClass1. You should see the documentation of the first example of class provided by the template.
GitHub page of your package (main page) → near the bottom of the page, click on the Codecov badge.
You can navigate in your project to see what parts of the code are covered by the tests.
If you wish, you are now ready to release your first version (cf. below).