Quickstart Guide

Requirements

Install pipx:

python -m pip install --user pipx
python -m pipx ensurepath

Install cruft:

pipx install cruft[pyproject]

Install Poetry:

pipx install poetry

Install Nox and nox-poetry:

pipx install nox
pipx inject nox nox-poetry

pipx is preferred, but you can also install with pip install --user.

It is recommended to set up Python 3.10, 3.11 and 3.12 using pyenv.

Creating a project

Generate a Python project:

cruft create https://github.com/statisticsnorway/ssb-pypitemplate.git --checkout=2024.9.10

Cruft downloads the template and asks you a series of questions about project variables. Further details can be found in the Creating a project section of the user guide.

Change to the root directory of your new project, and create a Git repository:

git init
git add .
git commit

Installing the environment

Install the virtual environment using the command:

poetry update

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

If you want to run the tests with a non-default python version:

nox --force-python 3.11

Continuous Integration

GitHub

  1. Sign up at GitHub.

  2. Create an empty repository for your project.

  3. Follow the instructions to push an existing repository from the command line.

PyPI

  1. Sign up at PyPI.

  2. Go to the Account Settings on PyPI, select Publishing, and set up a new pending publisher as described on Creating a PyPI Project with a Trusted Publisher.

  3. Use the following information for the new pending publisher:

    • PyPI Project name: Name of the GitHub repo.

    • Owner: GitHub organization name or GitHub username that owns the repository.

    • Repository name: Name of the GitHub repo.

    • Workflow name: release.yml

    • Environment: Leave empty.

TestPyPI

  1. Sign up at TestPyPI.

  2. Go to the Account Settings on TestPyPI, select Publishing, and set up a new pending publisher as described on Creating a PyPI Project with a Trusted Publisher.

  3. Use the following information for the new pending publisher:

    • PyPI Project name: Name of the GitHub repo.

    • Owner: GitHub organization name or GitHub username that owns the repository.

    • Repository name: Name of the GitHub repo.

    • Workflow name: release.yml

    • Environment: Leave empty.

GitHub Pages

  1. Log in to GitHub.

  2. Select Settings, Pages and set Source to “GitHub Actions” below the Build and Deployment heading.

GitHub Pages should then work out of the box. The pages are deployed to
<github username>.github.io/<repo name> or
<github organization>.github.io/<repo name>.

SonarCloud

  1. Log in to SonarCloud with your GitHub account.

  2. Click the plus-sign at upper right and select Analyze new project, select your organization and the new repo to analyze, and then click the Set Up button.

  3. Set new code to be based on Number of days and 60 days (suggestion). And then click the Create project button.

  4. Select Administration, Analysis Method and choose method: With GitHub Actions.

  5. Follow the description to add a GitHub repository secret for the SONAR_TOKEN.

  6. That’s it. The next time a pull request is opened or a branch or merged to main on GitHub, the code will be analysed by SonarCloud.

Releasing

Releases are triggered by a version bump on the default branch. It is recommended to do this in a separate pull request:

  1. Switch to a branch.

  2. Bump the version using poetry version.

  3. Commit and push to GitHub.

  4. Open a pull request.

  5. Merge the pull request.

The Release workflow performs the following automated steps:

  • Build and upload the package to PyPI.

  • Apply a version tag to the repository.

  • Publish a GitHub Release.

Release notes are populated with the titles and authors of merged pull requests. You can group the pull requests into separate sections by applying labels to them, like this:

Pull Request Label

Section in Release Notes

breaking

💥 Breaking Changes

enhancement

🚀 Features

removal

🔥 Removals and Deprecations

bug

🐞 Fixes

performance

🐎 Performance

testing

🚨 Testing

ci

👷 Continuous Integration

documentation

📚 Documentation

refactoring

🔨 Refactoring

style

💄 Style

dependencies

📦 Dependencies