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

Generate Your Package with Cookiecutter

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

  2. In a terminal (e.g. Anaconda Prompt):

    1. Go to the parent directory of where you want to put the directory of your package, e.g. D:\GitHub\.

    2. cookiecutter https://github.com/francois-durand/package_helper_2.git

    3. 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]:
  3. Optionally, in your file manager, open the directory of your package: the whole file structure is now in there!

Some explanations now:

Open Your Project and Create a Virtual Environment (or not)

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:

  1. Choose "Open" and select the directory of your package.

  2. A prompt window named "Creating Virtual Environment" opens. If you want to create a virtual environment, validate with the default options. Otherwise, cancel.

  3. In the bottom right part of the window, you will probably see some background tasks running. Wait until they are finished.

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

Install Dev Requirements

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:

  1. Ensure you are in the directory of your package (e.g. D:\GitHub\my_toy_package).

  2. 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
  3. pip install -r requirements_dev.txt

Install Your Package in “Development Mode”

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

Check That Everything Is Working Locally

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

  2. Open the file cov/index.html (in your web browser). It displays what parts of your code are covered by the tests.

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

  4. Open the file build/index.html (in your web browser). It displays the html documentation of your project.

Create the GitHub Repo

In PyCharm:

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

  2. Menu VCS → Share project on GitHub.

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

Check your GitHub Actions

In GitHub:

  1. GitHub page of your package → Actions.

  2. 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").

GitHub Settings

On the GitHub page of your package:

  1. Tell GitHub Pages that the documentation files are in the "gh-pages" branch of your project:

    1. Settings → Pages → Source.

    2. Select "gh-pages".

    3. Select "/ (root)".

    4. Save.

  2. Configure Codecov:

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

    2. Back to GitHub: Settings → Secrets → New repository secret. Name: CODECOV_TOKEN. Value: paste the codecov token.

  3. Register your PyPI credentials as "secrets", so that GitHub can automatically publish your package on PyPI for you:

    1. Settings → Secrets.

    2. Select "New repository secret". Name: PYPI_USERNAME. Value: your PyPI username.

    3. Select "New repository secret". Name: PYPI_PASSWORD. Value: your PyPI password.

Your First Commit

In PyCharm, make a slight modification, e.g. in the file README.rst. Then commit/push:

  1. Menu Git → Commit.

  2. Enter a commit message.

  3. Commit and push.

  4. Push.

Check That Everything Is Working Online

  1. GitHub page of your package → Actions. Wait until your actions are finished.

  2. Check the documentation:

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

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

      1. PyPI: package or version not found (there will be the version number after your first release).

      2. Build: passing.

      3. Docs: passing.

      4. Codecov: with a percentage.

    3. In the table of contents: Reference → MyClass1. You should see the documentation of the first example of class provided by the template.

  3. On Check your test coverage::

    1. GitHub page of your package (main page) → near the bottom of the page, click on the Codecov badge.

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