Python Package Example

This package was created by generally following the Packaging Python Projects with the addition of some pipenv setup to manage virtual environments.

How this package was created

1. Install pipenv, build, and twine if not already installed.
2. create directory structure for the package like that below, where examplepackagefb1258 is replaced with your package's name. This name must be uniquely yours when uploaded to PyPI. Better to avoid hyphens or underline characters (- or _) in the package name, as these can create problems when importing. The parent directory name (the repository name) - python-package-example in this case - is not relevant to the package name.

python-package-example/
  |____README.md
  |____LICENSE
  |____pyproject.toml
  |____tests
  |____src
    |____examplepackagefb1258
      |______init__.py
      |______main__.py
      |____wisdom.py

3. Make __init__.py an empty file.
4. Enter the text of a copyright license of your choosing into LICENSE.
5. Add settings in pyproject.toml suitable for a setuptools-based build and add metadata fields to this file - see the example in this repository.
6. Put your own custom module code into src/examplepackagefb1258/wisdom.py or whatever filename(s) you choose for the module(s) that live within your package.
7. Optionally add a __main__.py file to the package directory, if you want to be able to run the package as a script from the command line, e.g. python -m examplepackagefb1258.
8. Build the project by running python -m build from the same directory where the pyproject.toml file is located.
9. Verify that the built .tar archive has the files you expect your package to have (including any important non-code files) by running the command: tar --list -f dist/examplepackagefb1258-0.0.7.tar.gz, where examplepackagefb1258-0.0.7 is replaced with your own package name and version.
10. Create an account on TestPyPI where one can upload to a test repository instead of the production PyPI repo.
11. Create a new API token on TestPyPI with the "Scope" set to “Entire account”. Save a copy of the token somewhere safe.
12. Upload your package to the TestPyPI repository using twine, e.g. twine upload -r testpypi dist/*
13. twine will output the URL of your package on the PyPI website - load that URL in your web browser to see your packaged published - make sure the README.md file looks nice on the web site.

Every time you change the code in your package, you will need to rebuild and reupload it to PyPI. You will need to build from a clean slate and update the version number to achieve this:

1. delete the autogenerated dist directory
2. delete the autogenerated src/*.egg-info directory
3. update the version number in pyproject.toml and anywhere else it is mentioned (do a find/replace)
4. build the package again with python -m build
5. upload the package again with twine upload -r testpypi dist/*

Repeat as many times as necessary until the package works as expected. Once complete, upload to the real PyPI instead of the TestPyPI repository.

If updating version numbers is tedious, you may consider using bumpver - a tool that can automate some parts of updating version numbers.

How to install and use this package

Try installing and using your package in a separate Python project:

1. Create a pipenv-managed virtual environment and install the latest version of your package installed: pipenv install -i https://test.pypi.org/simple/ examplepackagefb1258==0.0.7. (Note that if you've previously created a pipenv virtual environment in the same directory, you may have to delete the old one first. Find out where it is located with the pipenv --venv command.)
2. Activate the virtual environment: pipenv shell.
3. Create a Python program file that imports your package and uses it, e.g. from examplepackagefb1258 import wisdom and then print(wisdom.get()) (replace wisdom and get() with any module name and function that exists in your package) .
4. Run the program: python3 my_program_filename.py.
5. Exit the virtual environment: exit.

Try running the package directly:

1. Create and activate up the pipenv virtual environment as before.
2. Run the package directly from the command line: python3 -m examplepackagefb1258. This should run the code in the __main__.py file.
3. Exit the virtual environment.

How to run unit tests

Simple example unit tests are included within the tests directory. To run these tests...

1. Install pytest in a virtual environment.
2. Run the tests from the main project directory: python3 -m pytest.
3. Tests should never fail. Any failed tests indicate that the production code is behaving differently from the behavior the tests expect.

Pro tip

While working on the package code, and verifying it behaves as expected, it can be helpful to install the package in "editable" mode so that changes to the package are immediately updated in the virtual environment.

• To do this, run pipenv install -e . from the main project directory.

Continuous integration

This project has a continuous integration workflow that builds and runs unit tests automatically with every push of the code to GitHub.