Create Your Package#

Creating your package locally should take less than 5 minutes. Full deployment on the different websites (GitHub, Codecov, Pypi) will take a bit more time, but likely less than 20 minutes (maybe more the first time).

Before Starting: Decide What You Want#

PH3 will ask you some information. It is best to think ahead of the answers:

Name / email / github username. You should know the answer of these questions. If you do not want to re-renter them everytime you make a new project you can write a user config file.
Project Name. This is the name of your project in human language. It will be displayed in the documentation. You can (should?) use title case and spaces if you have multiple words. For example, Package Helper 3.
project-slug. This is where you store your package. It will typically be the name of the directory where you develop the package, and the name of your GitHub/PyPi repositories. The convention is to use lower case and dashes. Unless you have specific reasons, you should adopt a project slug consistent with your project name. For example, package-helper-3. Also, you should check that your project slug is not used inPyPI, even if you do not plan to use PyPI for the moment (e.g. to avoid any possible package collision).
package_name. This is the python name of your package. It will typically be the name of the subdirectory of your project that contains the actual code. The convention is to use lower case and underscores. Unless you have specific reasons, you should adopt a package name consistent with your project name/slug. For example, import package_helper_3 as ph.
Project description. One or two sentences that describes the purpose of your project. For example, “Package Helper 3 explains how to create, develop, and maintain a Python package with Poetry.”
Version. PH3 adopts the semantic versioning convention. As they suggest, we recommend to start your initial development release at 0.1.0.
Documentation theme. Decide the skin you want for your documentation: PyData or ReadTheDocs.
Command line interface (CLI). If your package is intended to be always executed from Python, you do not need to care about the CLI. If you intend to execute commands directly from a terminal (Anaconda Prompt, Bash, Windows Powershell, etc), some Python packages are here to help you. Two of the most popular ones are click (recommended) or argparse.
Dockerfile. Do you plan to deploy your package on docker?
License. Which open source license (if any) do you want for your package? Check https://choosealicense.com/ if you need advice.

Generate Your Package with Package Helper 3#

In a terminal (Anaconda Prompt, Bash, Windows Powershell, etc):

Go to the parent directory of where you want to put the directory of your package, e.g. D:\GitHub\, /home/login/git/.
Call Package Helper 3:

$ ph3

Answer the questions (see above for the meaning). If you leave a question blank, the default proposal (in parenthesis) will be used. Here is an example:

PS C:\Users\fabienma\git\github> ph3
  [1/12] full_name (Fabien Mathieu):
  [2/12] email (loufab@gmail.com):
  [3/12] github_username (balouf):
  [4/12] project_name (First Sandbox): My First PH3 Package
  [5/12] project_slug (my-first-ph3-package):
  [6/12] package_name (my_first_ph3_package):
  [7/12] project_description (Sandboxes are cool!): PH3 packages are quick to make!
  [8/12] version (0.1.0):
  [9/12] Select documentation_theme
    1 - PyData
    2 - ReadTheDocs
    Choose from [1/2] (1):
  [10/12] Select command_line_interface
    1 - No command-line interface
    2 - Click
    3 - Argparse
    Choose from [1/2/3] (1): 2
  [11/12] dockerfile [y/n] (n):
  [12/12] Select open_source_license
    1 - MIT license
    2 - GNU General Public License v3
    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):

Optionally, in your file manager, open the directory of your package: the whole file structure is now in there!

Install Your Project#

Developing a project and using a package are two different things, so you should install your package twice, once in a dedicated environment, one in your main space!

Install a dedicated environment#

In a terminal prompt, go to the project directory (named as project-slug) and enter:

$ poetry install

Wait for the installation to complete and you’re done!

You can test that your environment is well configured by launching a shell:

$ poetry shell

Your prompt should indicate the virtual environnment in parenthesis, for example:

(my-first-ph3-package-py3.11) C:\...\my-first-ph3-package>

If you choose a CLI, you can try and run the default script:

(my-first-ph3-package-py3.11) PS C:\...\my-first-ph3-package> my_first_ph3_package --help
Usage: my_first_ph3_package [OPTIONS]

  Console script for my-first-ph3-package.

Options:
  --help  Show this message and exit.

You can leave the virtual environment with the command

$ exit

Note that poetry will install your package in editable mode. That means that everytime you load the package inside the dedicated environment, the current version will be used, not the one from the installation time.

[Windows users]: `unable to load` error#

Windows users may see an error when they try the poetry shell command. This is usually due to the fact that you use a Powershell terminal, which by default has limited execution policies. Two options here (adapted from https://support.enthought.com/hc/en-us/articles/360058403072-Windows-error-activate-ps1-cannot-be-loaded-because-running-scripts-is-disabled-UnauthorizedAccess-):

Don’t use Powershell. The old-fashioned Command Prompt does not rise the error.
Elevate your Powershell rights by running the following command in a Powershell terminal:

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy Unrestricted

Install on your default Python distribution#

Right now, your Python package is only available in its dedicated environment. To use it more broadly (e.g. if you want to run Jupyter Notebooks, combine it with other packages, etc…):

Use a terminal prompt outside your dedicated environment (exit if you are within the dedicated environment);
Go to the project directory and install your package:

$ pip install -e .

The -e option means that you will install the package in editable mode, like for the dedicated environment.

The . (dot) tells that the package to install is in the working directory.

Your package is now available outside your dedicated environment! For example, if you chose a CLI:

PS C:\>my_first_ph3_package
Replace this message by putting your code into my_first_ph3_package.cli.main
See click documentation at https://click.palletsprojects.com/

You can also try to open the Notebook your-project-slug/docs/tutorials/tutorial.ipynb and check that the calls to the package are working fine.

Try Your Project with PyCharm#

To open your project:

Inside PyCharm, you can choose “Open” and select the directory of your project (project-slug).
Alternatively, if you installed PyCharm with context menu, you can right-click the directory in your favorite file manager and select “Open folder as PyCharm project”

In the bottom right part of the window, you will probably see some background tasks running. Wait until they are finished. In particular, wait until PyCharm discovered your dedicated environment, e.g. when <No interpreter> is replaced by something like Python 3.11 (my-first-ph3-package) (it is usually displayed in the lower right corner).

Note: Some users reported that PyCharm sometimes fails to locate the dedicated environment. If that happens, try to open (in PyCharm) the main Python file of the project, PyCharm should then propose to use the environment in a banner.

Run tests and documentation locally#

In PyCharm: menu Run → Run → All Tests. It runs all the tests of the project. PH3 provides in its template examples that you can re-use if you are new to testing (e.g. in 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.

Go GitHub#

First thing to do is create the GitHub repo of your project. In PyCharm:

From the file pyproject.toml of your package, copy the description value, e.g. “PH3 packages are quick to make!” in the example above. You will paste it in the form below.
Menu Version Control → Share project on GitHub.
Fill in the form and validate, e.g.:

New repository name: my_toy_package
Remote name: origin
Description: PH3 packages are quick to make!

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 repo visibility: GitHub repos can be private or public. Some features like publishing your documentation on GitHub pages are only available on public repos unless you have a paid account. If you set up your repo to private, you can switch visibility to public on the settings menu (the Danger Zone down the screen).

Check GitHub actions#

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. Default PH3 triggers are:
  - When something is pushed on the default branch (“main” or “master”).
  - When there is a pull request.
  - At 5:30 am the 1st and 15th of each month.
- The “docs” actions builds the documentation when something is pushed. It publishes it online if the branch is your default git branch (“main” or “master”).
- The “release” action should not have been triggered at this point. It will run when you release a version to publish it on PyPi.

Declare your documentation#

Tell GitHub Pages that the documentation files are in the “gh-pages” branch of your project:

Settings → Pages → Build and deployment
Check that Source is “deploy from a branch”.
Branch → “gh-pages”, “/ (root)”.
Save.

Test on a first commit#

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

From the VC menu, choose Commit (or Ctrl+k).
Enter a commit message, click on Commit.
From the VC menu, choose Push (or Ctrl+Shift+K).
Click on Push.

Then check that everything is working online:

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 five badges:
  - PyPI: package or version not found (there will be the version number after your first release).
  - Build: passing.
  - Docs: passing.
  - License: the license you choose.
  - 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.
Check your test coverage:
- 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 Make a Release).

Time to Code!#

Replace the toy code provided by PH3 with your actual code.
Add/remove dependencies according to your needs.
Right click on PyCharm’s project tree to create new modules (i.e. Python files) and (sub)packages (directories with a __init__.py file).
If you manually copy files in your project, don’t forget to add them to Git.
Keep in mind that your project is not just your source code
- Update your documentation:
  - Check that your reference section is consistent with your actual package.
  - Update your documentation notebooks if you have some.
  - Check the sphinx warnings when you build the documentation.
- Update your tests:
  - Update your docstrings.
  - Update your tests directory.
  - Check your coverage.