Quickstart Guide¶
Requirements¶
Install Cookiecutter:
$ pipx install cookiecutter
Install Poetry by downloading and running get-poetry.py:
$ python get-poetry.py
Install Nox:
$ pipx install nox
pipx is preferred, but you can also install with pip install --user
.
It is recommended to set up Python 3.6, 3.7, and 3.8 using pyenv.
Creating a project¶
Generate a Python project:
$ cookiecutter gh:cjolowicz/cookiecutter-hypermodern-python \
--checkout="2020.5.15"
Change to the root directory of your new project, and create a Git repository:
$ git init
$ git add .
$ git commit
Running¶
Run the command-line interface from the source tree:
$ poetry install
$ poetry run <project>
Run an interactive Python session:
$ poetry install
$ poetry run python
Testing¶
Run the full test suite:
$ nox
List the available Nox sessions:
$ nox --list-sessions
Install the pre-commit hooks:
$ nox -s pre-commit -- install
Continuous Integration¶
GitHub¶
Sign up at GitHub.
Create an empty repository for your project.
Follow the instructions to push an existing repository from the command line.
PyPI¶
Sign up at PyPI.
Go to the Account Settings on PyPI, generate an API token, and copy it.
Go to the repository settings on GitHub, and add a secret named
PYPI_TOKEN
with the token you just copied.
TestPyPI¶
Sign up at TestPyPI.
Go to the Account Settings on TestPyPI, generate an API token, and copy it.
Go to the repository settings on GitHub, and add a secret named
TEST_PYPI_TOKEN
with the token you just copied.
Dependabot¶
Sign up at Dependabot.
Install their GitHub app.
Read the Docs¶
Sign up at Read the Docs.
Import your GitHub repository, using the button Import a Project.
Install the GitHub webhook, using the button Add integration on the Integrations tab in the Admin section of your project on Read the Docs.
Releasing¶
Bump the version using poetry version. Push to GitHub.
Publish a GitHub Release.
GitHub Action triggers the PyPI upload.
Release notes are pre-filled with titles and authors of merged pull requests.
Use labels to group the pull requests into sections:
Pull Request Label |
Section in Release Notes |
---|---|
|
💥 Breaking Changes |
|
🚀 Features |
|
🔥 Removals and Deprecations |
|
🐞 Fixes |
|
🐎 Performance |
|
🚨 Testing |
|
👷 Continuous Integration |
|
📚 Documentation |
|
🔨 Refactoring |
|
💄 Style |
|
📦 Dependencies |
GitHub creates the bug
, enhancement
, and documentation
labels for you.
Dependabot creates the dependencies
label.
Create the remaining labels on the Issues tab of your GitHub repository,
when you need them.