![Python build & test](https://github.com/nyu-software-engineering/python-package-example/actions/workflows/build.yaml/badge.svg)

# Python Package Example

This package was created by generally following the [Packaging Python Projects](https://packaging.python.org/en/latest/tutorials/packaging-projects/) with the addition of some [pipenv setup](https://packaging.python.org/en/latest/tutorials/managing-dependencies/) to manage virtual environments.

## How this package was created

1. [Install pipenv](https://packaging.python.org/en/latest/tutorials/managing-dependencies/#managing-dependencies), [build](https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives), and [twine](https://packaging.python.org/en/latest/key_projects/#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](https://pypi.org/). 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](https://choosealicense.com/) 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](https://test.pypi.org/) where one can upload to a test repository instead of the production PyPI repo.
11. Create a [new API token](https://test.pypi.org/manage/account/#api-tokens) on TestPyPI with the "Scope" set to “Entire account”. Save a copy of the token somewhere safe.
12. [Upload your package](examplepackagefb1258) 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](https://pypi.org/project/bumpver/#configuration-setup) - a tool that can automate some parts of updating version numbers.

## How to install and use this package

Try [installing and using your package](https://packaging.python.org/en/latest/tutorials/packaging-projects/#installing-your-newly-uploaded-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.)
1. Activate the virtual environment: `pipenv shell`.
1. 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) .
1. Run the program: `python3 my_program_filename.py`.
1. 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.
1. Run the tests from the main project directory: `python3 -m pytest`.
1. 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.
