🔨 Installation

🙋‍♀️ User Installation Instructions

The packages are hosted on:

To include cpg-flow in your python project simply install either the latest stable version as layed out in the PyPi package page. =

This is as simple as running the following in your project python environment

pip install cpg-flow

For a specific version

pip install cpg-flow==0.1.2

We recommend making the appropriate choice for your individual project. Simply including cpg-flow in your dependency management system of choice will install the latest stable relase. But if neccessary you can pin the version. For example in your pyproject.toml file simply include the following:

dependencies = [
    "cpg-flow",         # latest OR
    "cpg-flow==0.1.2",  # pinned version
]

🛠️ Development Installation Instructions

These instructions are for contributors and developers on the cpg-flow project repository. Follow the following steps to setup your environment for development.

To install this project, you will need to have Python and uv installed on your machine:

We use uv for dependency management which can sync your environment locally with the following command:

# Install the package using uv
uv sync

However, to setup for development we recommend using the makefile setup which will do that for you.

make init-dev # installs pre-commit as a hook

📦 Upgrading Packages

To upgrade dependencies in your development environment:

Security Cutoff Date Required

Always use the --exclude-newer flag with a security cutoff date to exclude packages released in the last 7 days, reducing risk of vulnerable releases.

# Calculate cutoff date and upgrade packages
CUTOFF_DATE=$(python3 -c "from datetime import datetime, timedelta; print((datetime.now() - timedelta(days=7)).strftime('%Y-%m-%d'))")

# Upgrade all packages to their latest compatible versions
uv sync --upgrade --exclude-newer $CUTOFF_DATE

# OR upgrade a specific package
uv sync --upgrade-package <package-name> --exclude-newer $CUTOFF_DATE

The --exclude-newer flag helps avoid pulling very recent package versions that may contain vulnerabilities or haven't been thoroughly tested. Use a recent date (e.g., a few days or weeks ago) as a safety buffer.

After upgrading packages, ensure all tests pass and pre-commit hooks still work correctly.

🪝 Installing Pre-commit Hooks

Pre-commit hooks help maintain code quality by running checks before each commit. The make init-dev command installs these hooks automatically, but you can also install them manually:

# Install pre-commit hooks for standard checks
uv run pre-commit install

# Install commit message linting hook
uv run pre-commit install --hook-type commit-msg

To run pre-commit hooks manually on all files:

uv run pre-commit run --all-files

To install cpg-flow locally for testing the code as an editable dependency

make install-local

This will install cpg-flow a an editable dependency in your environment. However, sometimes it can be useful to test the package post-build.

make install-build

This will build and install the package as it would be distributed.

You can confirm which version of cpg-flow is installed by running

uv pip show cpg-flow

For an Editable package it should show the repo location on your machine under the Editable: key.

Name: cpg-flow
Version: 0.1.2
Location: /Users/whoami/cpg-flow/.venv/lib/python3.10/site-packages
Editable project location: /Users/whoami/cpg-flow
Requires: coloredlogs, cpg-utils, grpcio, grpcio-status, hail, ipywidgets, metamist, networkx, plotly, pre-commit, pyyaml
Required-by:

The build version (static until you rebuild) will look like the following.

Name: cpg-flow
Version: 0.1.2
Location: /Users/whoami/cpg-flow/.venv/lib/python3.10/site-packages
Requires: coloredlogs, cpg-utils, grpcio, grpcio-status, hail, ipywidgets, metamist, networkx, plotly, pre-commit, pyyaml
Required-by:

Tip

To try out the pre-installed cpg-flow in a Docker image, find more information in the Docker documentation.

🚀 Build

To build the project, run the following command:

make build

To make sure that you're actually using the installed build we suggest calling the following to install the build wheel.

make install-build