h-cookiecutter-pypackage

A Cookiecutter project template for creating Hypothesis-style Python packages. Automates the creation and updating of all our Python package project tooling and scaffolding: Makefile, tox.ini, setup.py, GitHub Actions, etc.

Usage

You will need

• Cookiecutter (pip install cookiecutter, brew install cookiecutter or sudo apt install cookiecutter)

Creating a new project

To create a new project from this template:

$ cookiecutter gh:hypothesis/h-cookiecutter-pypackage

Publishing to PyPI

Once your package is up and running the following behaviour is in place:

• All pushes will be run through the full set of tests and linting
• Only successful tagged builds will be published to PyPI
  • To do this run make release

I ran make release but it went wrong!

If a release fails to build then just run the command again.

This will skip a version number, but that's ok. If you want to you can also delete the failed release tag from Github.

The first time

When you merge a pull request into master, if the package passes all tests, coverage, format and linting requirements, GitHub Actions will automatically build it and uploaded it to https://pypi.org/.

For this to work you'll need to setup an API key for the project.

Build a package and upload it to PyPI

• Run: make initialrelease
• Type in a release message for the intial release
• Run: tox -e initialrelease --run-command "twine upload -u eng@list.hypothes.is -p <PASSWORD_HERE> dist/*"

Create an API key in PyPI

• Login to https://pypi.org/
• Go to Your projects and select Manage on the correct project
  • Settings > Create a token for project-name-here
  • Use the project name as the name
  • Set the scope to the same project
  • COPY THE KEY NOW! - You won't get another opportunity

You may want to add some other personal accounts as owners so that we do not have a single account as maintainer.

Add the key to Github as a secret

• Go to https://github.com/ and find the correct project
• Go to Settings > Secrets > Add a new secret
• Use "PYPI_TOKEN" as the name
• Paste the API key in as the value
• Press Add secret

Hacking

Installing h-cookiecutter-pypackage in a development environment

You will need

• Git

• pyenv Follow the instructions in the pyenv README to install it. The Homebrew method works best on macOS. On Ubuntu follow the Basic GitHub Checkout method.

Clone the git repo

$ git clone https://github.com/hypothesis/h-cookiecutter-pypackage.git

This will download the code into a h-cookiecutter-pypackage directory in your current working directory. You need to be in the h-cookiecutter-pypackage directory for the rest of the installation process:

$ cd h-cookiecutter-pypackage

Run the tests

$ make test

That's it! You’ve finished setting up your h-cookiecutter-pypackage development environment. Run make help to see all the commands that're available for linting, code formatting, packaging, etc.