Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
160 lines (107 loc) · 4.06 KB

DEVELOPMENT.md

File metadata and controls

160 lines (107 loc) · 4.06 KB
Raw

Development And Publishing

Prerequisites

Environment Setup

This project uses uv to manage dependencies. uv is pretty good at automatically sync-ing. But if you need to explicitly set everything up, try:

just install

This will create a virtualenv at ./.venv and install dependencies with uv.

Just Tasks

To list all Just tasks, run just --list:

Available recipes:
    build         # Build the package
    build-docs    # Build the documentation
    check         # Check type annotations with pyright
    clean         # Clean up loose files
    compile       # Generate locked requirements files based on dependencies in pyproject.toml
    default       # By default, run checks and tests, then format and lint
    docs          # Live generate docs and host on a development webserver
    format        # Format with black and isort
    install       # Install all dependencies
    lint          # Lint with flake8
    man           # Generate man page and open for preview
    mkdocs        # Run mkdocs
    publish       # Build the package and publish it to PyPI
    shell         # Open a bash shell with the venv activated
    sphinx TARGET # Run sphinx
    tag           # Tag the release in git
    test          # Run tests with pytest
    tox           # Run tests using tox
    update        # Update all dependencies
    upgrade       # Update all dependencies and rebuild the environment
    upload        # Upload built packages

Updating Modules

To update the modules being used, run:

just update

Interactive Environments

To activate the venv in a subshell:

just shell

To fire up an interactive console:

just console

Note that I haven't figured out how to auto-exec code on load - you'll need to import everything. The easiest thing may be to use full fat Jupyter, potentially with jpterm.

Development Loop

There are four main just tasks:

  • just format - format with black and isort
  • just check - check type annotations with pyright
  • just test - run tests with pytest
  • just lint - lint with flake8 and validate-pyproject

To run all four in a row, simply run just. Then, run individual checks until you're happy with it, and run just again to make sure all is well.

Cross-Version Tests with tox

I usually lean on github actions for checking the test matrix, but just tox should run them with tox. An avenue to explore may be acting smarter about installing versions of python listed in the test matrix.

Generating Docs

Docs for published projects are automatically generated by readthedocs, but you can also preview them locally by running:

just docs

This will use mkdoc's dev server - click the link, good to go. It even supports hot reload!

Publishing

Do a Final Check

Run just to do final checks.

Update the Changelog

Update the CHANGELOG.md file to detail the changes being rolled into the new version.

Update the Version in pyproject.toml

I do my best to follow semver when updating versions.

Add a Git Tag

I try to use git tags to tag versions - there's a just task:

just tag

Push the Tag to GitHub

git push origin main --tags

Check on GitHub Actions

This should trigger a GitHub Action which publishes to PyPI and creates a GitHub Release. Go to GitHub and make sure it worked.

Check on RTD

RTD should build automatically but I find there's a delay so I like to kick it off manually. Log into RTD, log in, then go to the pyee project page and build latest and stable.

(Optional) Announce on Social Media

It's not official, but I like to announce the release on Bluesky and Mastodon.

(Optional) Build and Publish Manually

If you want to publish the package manually, run:

just publish

This should automatically build the package and upload with uv.