Repository files navigation

Opinionated cookiecutter template for creating a new Python library

Use this template on your own machine with cookiecutter, or create a brand new repository based on this template entirely through the GitHub web interface usingpython-lib-template-repository.

You'll need to havecookiecutter installed. I recommend pipx for this:

pipx install cookiecutter

Regularpip will work OK too.

Runcookiecutter gh:simonw/python-lib and then answer the prompts. Here's an example run:

cookiecutter gh:simonw/python-lib

lib_name []: python lib template demodescription []: Demonstrating https://github.com/simonw/python-libhyphenated [python-lib-template-demo]: underscored [python_lib_template_demo]: github_username []: simonwauthor_name []: Simon Willison

I strongly recommend accepting the suggested value for "hyphenated" and "underscored" by hitting enter on those prompts.

This will create a directory calledpython-lib-template-demo - the name you enter is converted to lowercase and uses hyphens instead of spaces.

Seehttps://github.com/simonw/python-lib-template-demo for the output of this example.

Having created the new structure from the template, here's how to start working on the library.

If your library is calledmy-new-library, you can start working on it like so:

cd my-new-library# Create and activate a virtual environment:python -m venv venvsource venv/bin/activate# Install dependencies so you can edit the project:python -m pip install -e'.[test]'# With zsh you have to run this again for some reason:source venv/bin/activate

You can run the default test for your library like so:

python -m pytest

This will execute the test intests/test_my_new_library.py.

You can initialize a Git repository for your library like this:

cd my-new-librarygit initgit add.git commit -m"Initial structure from template"# Rename the 'master' branch to 'main':git branch -m master main

Usehttps://github.com/new to create a new GitHub repository sharing the same name as your library, which should be something likemy-new-library.

Push yourmain branch to GitHub like this:

git remote add origin git@github.com:YOURNAME/my-new-library.gitgit push -u origin main

The template will have created a GitHub Action which runs your library's test suite against every commit.

The template also includes apublish.yml GitHub Actions workflow for publishing packages toPyPI, usingpypa/gh-action-pypi-publish.

To use this action, you need to create a PyPI account andconfigure a Trusted Publisher for this package.

Once you have created your account, navigate tohttps://pypi.org/manage/account/publishing/ and create a "pending publisher" for the package. Use the following values:

• PyPI Project Name: The name of your package
• Owner: Your GitHub username or organization - the "foo" ingithub.com/foo/bar
• Repsitory name: The name of your repository - the "bar" ingithub.com/foo/bar
• Workflow name:publish.yml
• Environment name:release

Now, any time you create a new "Release" on GitHub the Action will build your package and push it to PyPI.

The tag for your release needs to match theVERSION string at the top of yourpyproject.toml file. You should bump this version any time you release a new version of your package.

Updating this cookiecutter template while keeping thepython-lib-template-repository template repository working is a little bit complicated. Detailed notes inissue #6, but the short version is:

1. Any changes to the{{cookiecutter.hyphenated}}/.github/workflows/*.yml files need to be manually pushed to thepython-lib-template-demo repository, because GitHub Actions cannot update their own workflows.
2. Generated final versions of those workflows then need to be copied topython-lib-template-repository .github/workflows for the same reason.