Skip to main content

Runtime Conditions Python profiler

The profiler turns declarations in a Python codebase into a validated Runtime Conditions Profile. Your code imports generated binding distributions installed in the same Python environment as the profiler. The profiler finds those distributions through Python package metadata, reads their fixed binding resources, and analyzes your source without importing the bindings or running the application. Python 3.11 or newer is required.

Install

The profiler is published to PyPI as runtimeconditions-profiler. Install it into the same virtual environment as the binding distributions your workload imports, because it finds them through that environment's package metadata. Do not use pipx, which would give it an environment of its own.

PROFILE_ENV=/Users/alex/.venvs/orders-profile
PROJECT_DIR=/Users/alex/work/orders
python3 -m venv "$PROFILE_ENV"
"$PROFILE_ENV/bin/python" -m pip install \
  runtimeconditions-profiler \
  runtimeconditions-common-integrations \
  runtimeconditions-env-configuration

Keep PROFILE_ENV and PROJECT_DIR set in the same shell for the commands below. The bindings are resolved by name and version from PyPI, or from your organization's configured Python package index. runtimeconditions-common-integrations and runtimeconditions-env-configuration are the first-party ones; a binding for another extension comes from whoever publishes it.

A binding distribution must include Python distribution metadata and these four resources at the installed import package's fixed location: runtimeconditions.bindings.yaml, runtimeconditions.binding-model.yaml, runtimeconditions.extension.yaml, and runtimeconditions.binding-release.yaml. The profiler verifies their package ownership, identities, versions, digests, and dependency closure. Installing loose generated .py files does not provide that contract. No extensions repository checkout, local binding file path, editable install, or checkout-based PYTHONPATH is part of this workflow.

With the rc CLI, put the environment's bin directory on PATH (or set RC_PYTHON_PROFILER to the script) and run rc profile python generate ...; everything after python goes to this profiler unchanged.

Declare conditions in your workload

Use the API exported by your installed generated binding. For example, an organization's jobs binding might provide:

from acme_runtimeconditions_jobs import Command, Process, job

job(Command(value="sample"), Process())

The exact import, declaration functions, data classes, enum members, and fields come from the binding publisher. Declarations may use supported static values, collections, maps, optional fields, unions, aliases, and references across your project modules. A recognized declaration whose value cannot be determined statically produces a source-located error.

Verify bindings and generate a profile

Run the installed console script from the same environment. The project and output paths below are absolute paths to your workload, independent of where the profiler or binding packages were built:

"$PROFILE_ENV/bin/runtimeconditions-python-profiler" \
  profile verify-bindings --project "$PROJECT_DIR"

"$PROFILE_ENV/bin/runtimeconditions-python-profiler" \
  profile generate \
  --project "$PROJECT_DIR" \
  --name orders \
  --workload-uri https://services.example.com/orders \
  --workload-version 1.0.0 \
  --out "$PROJECT_DIR/runtimeconditions.profile.yaml"

verify-bindings lists the distributions found through workload imports, with the ones only a dependency of those marked (dependency); add --json for machine-readable output, where each package has a direct flag. profile generate uses the installed profiler's approved core schema and the verified extension definitions from the binding distributions. It validates the complete profile, including schemas from transitive dependencies, before atomically writing the YAML file. The profile lists extensions that directly contribute declarations; validation-only dependencies remain in the checked closure. An error exits nonzero and leaves an existing output file untouched. Omit --out to print the profile to standard output.

--workload-version is optional; without it the profile's workload has only its uri. The profile word is optional too, so runtimeconditions-python-profiler generate ... works, which lets the rc command pass its arguments straight through. --version --json prints the profiler's name, version, and the core profile schemas it emits, which rc checks before it runs the profiler.

The profile is written the way the Go, TypeScript, and Java profilers write it, so the same declarations give the same YAML in every language.

Extension IDs and remote resolution

Each Profile extensions item is a string containing the extension's required metadata.id. When metadata.version is present, the profiler appends it after a colon:

extensions:
  - https://extensions.example.com/runtimeconditions/jobs:1.2.3

metadata.id is required and metadata.version is optional. Profile references may be bare IDs or append any version string after a colon. The Python distribution name used by pip is separate from this extension identity. Profile consumers resolve the declared references and their transitive dependencies through their configured resolver.

During profile generation, this CLI validates the definitions packaged in the installed binding distributions. It does not fetch definitions directly from extension URIs. URI-only network resolution without an installed binding package is outside the current profiler command. No step requires an end user to pull the extensions repository or point the profiler at an extension file.

Continuous integration

The test workflow runs the complete tests/ suite on every pull request and push to main, using Python 3.11–3.14. It also supports manual runs. The suite runs in isolation using files in this repository.

To run the same suite locally from the profiler checkout:

python -m pip install '.[test]'
python -m pytest -q -ra

Build and check distributions (maintainers)

From the profiler source directory, use a separate build environment:

python3 -m venv .venv
.venv/bin/python -m pip install build
.venv/bin/python -m build
.venv/bin/python scripts/check_distributions.py dist/*.whl dist/*.tar.gz

The default build command creates a source distribution and builds the wheel from that archive. setuptools-scm derives local build versions from Git tags and commit state. The source archive records the resolved version in PKG-INFO, so installing it requires neither Git nor a version override. The check compares every runtime module and resource with the source, verifies the console entry point and runtime dependency metadata, and rejects missing resources, stale runtime files, and build output in the source archive. Run it against a fresh dist directory containing one release.

Both distributions contain the CLI implementation, the four binding validation schemas in schemas.json, and the pinned v0.4.0 core profile schema. Runtime dependencies are declared in pyproject.toml; generated bindings supply their own extension definitions. The source archive also includes the distribution checker, tests, and local test fixtures. This maintainer build needs no sibling repository. End users install the published package and their bindings as shown above.

Tagged GitHub Releases (maintainers)

Commit the release changes, then push a tag v<version> (for example v0.0.1). The tag is the source of the package version; no version file needs editing. The release workflow validates a canonical PEP 440 version without a local suffix, then passes that exact version to the build through SETUPTOOLS_SCM_PRETEND_VERSION_FOR_RUNTIMECONDITIONS_PROFILER. Both distribution metadata and installed-package checks must match it. Prerelease tags such as v0.2.0rc1 produce prerelease GitHub Releases.

The workflow builds the wheel and source archive once, runs strict Twine metadata validation and distribution-content checks, and records SHA256SUMS. Separate jobs install those exact files in fresh environments on Linux with Python 3.11–3.14 and on macOS and Windows with Python 3.12. Each job checks the installed CLI, package version, runtime dependencies, and schema resources outside the checkout. Logs and JSON results remain as Actions artifacts.

After every check passes, a job with contents: write verifies that the remote tag still points at the tested commit and attaches the wheel, source archive, and SHA256SUMS to the GitHub Release. A new release remains a draft until its assets are uploaded. An existing draft can be completed; retries verify any existing assets and refuse to replace different bytes. Released versions need new version numbers and tags for changed artifacts. The workflow uses the repository's GITHUB_TOKEN; no publication secret is needed for this step.

To reproduce a tagged release locally, use a fresh dist directory:

.venv/bin/python -m pip install -r requirements/release.txt
RELEASE_TAG=v0.0.1
.venv/bin/python scripts/release_artifacts.py check-tag "$RELEASE_TAG"
RELEASE_VERSION=${RELEASE_TAG#v}
SETUPTOOLS_SCM_PRETEND_VERSION_FOR_RUNTIMECONDITIONS_PROFILER="$RELEASE_VERSION" \
  .venv/bin/python -m build
.venv/bin/python -m twine check --strict dist/*.whl dist/*.tar.gz
.venv/bin/python scripts/check_distributions.py dist/*.whl dist/*.tar.gz \
  --expected-version "$RELEASE_VERSION"
.venv/bin/python scripts/release_artifacts.py checksums --dist-dir dist
.venv/bin/python scripts/smoke_install.py --dist-dir dist \
  --expected-version "$RELEASE_VERSION"

Build and test manually from GitHub

After pushing the workflow changes to the default branch, open Actions → Tagged Python release → Run workflow. Select the branch containing the changes to test, keep mode set to build-and-test, and enter release_tag, such as v0.0.1. This sets the test package version; the Git tag does not need to exist and the workflow does not create it. When dispatching at an existing tag, release_tag can be omitted to use that tag's version.

The manual run builds distributions, runs metadata/content validation and regression tests, and runs the same Linux, macOS, and Windows installed-package smoke checks as a tagged release. It retains distributions and evidence as Actions artifacts. GitHub Release creation and PyPI publication are skipped, including when PYPI_PUBLISH_ENABLED=true or the selected ref is a tag.

The equivalent CLI command is:

gh workflow run release.yml --repo runtimeconditions/python-rc-profiler \
  --ref main -f mode=build-and-test -f release_tag=v0.0.1

GitHub's Re-run jobs repeats the original commit. To test later changes, start a new manual run on the updated branch.

PyPI publication

The release workflow has a separate pypi job. It runs after the verified GitHub Release is published and only when the repository Actions variable PYPI_PUBLISH_ENABLED equals true. Keep that variable false while the PyPI organization runtimeconditions.io is awaiting approval.

The protected GitHub environment is pypi: deployments are restricted to tags matching v* and require approval from the repository's current sole maintainer, colinjlacy; administrator bypass is disabled. Self-review is allowed so that maintainer can approve their own tagged releases. Add another reviewer and prevent self-review if the maintainer team grows. Environment settings live in GitHub, independently of the workflow file.

The job downloads the published Release's wheel, source distribution, and SHA256SUMS; checks the tag's commit, package version, checksums, metadata, and contents against the tagged source; then copies only the two distributions into the upload directory. It does not rebuild them. Only this job has id-token: write; the pinned PyPA upload action uses Trusted Publishing and creates publication attestations. No PyPI password or API token is required. Existing PyPI versions are not silently skipped or overwritten.

Activate publishing after organization approval

  1. In PyPI, open Your organizations → runtimeconditions.io → Manage → Projects, and create runtimeconditions-profiler (or transfer that project into the organization if it already belongs to you). The PyPI organization name and the installable project name are separate.

  2. Open the project's Publishing settings and add this GitHub Trusted Publisher:

    Setting Exact value
    PyPI project runtimeconditions-profiler
    GitHub owner runtimeconditions
    GitHub repository python-rc-profiler
    Workflow filename release.yml
    Environment pypi

    Use just the workflow filename, without .github/workflows/. See the PyPI organization project instructions and Trusted Publisher setup.

  3. Set the repository Actions variable PYPI_PUBLISH_ENABLED to true. Future matching release tags will request pypi environment approval after all build and installed-package checks pass.

To publish a previously verified GitHub Release after activation, dispatch this same workflow at its existing release tag, for example:

gh workflow run release.yml --repo runtimeconditions/python-rc-profiler --ref v0.1.0 \
  -f mode=promote-pypi

The workflow must exist on the default branch and at that tag. The explicit promote-pypi mode skips building, smoke checks, and GitHub Release creation; it promotes the existing Release's assets. The environment reviewer should confirm the original tagged build and smoke jobs passed before approving this promotion. Dispatching at a branch cannot publish to PyPI. If an upload fails, retry the PyPI job or dispatch in promote-pypi mode at the same tag after fixing the cause; a partially published version requires inspection because PyPI files cannot be replaced.

TODO — external PyPI activation: After runtimeconditions.io is approved and activated, create the organization-owned project, register the exact Trusted Publisher above, and set PYPI_PUBLISH_ENABLED=true. The workflow and artifact promotion code are ready; publishing remains disabled until this setup is complete.

Metadata

Release files for runtimeconditions-profiler 0.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for runtimeconditions-profiler 0.5.0
File Size Uploaded Provenance Actions
runtimeconditions_profiler-0.5.0.tar.gz 79.9 kB With provenance Details for runtimeconditions_profiler-0.5.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for runtimeconditions-profiler 0.5.0
File Interpreter ABI Platform Actions
runtimeconditions_profiler-0.5.0-py3-none-any.whl Python 3 none any Details for runtimeconditions_profiler-0.5.0-py3-none-any.whl

Total release size: 127.1 kB

Release files / runtimeconditions_profiler-0.5.0.tar.gz

Download URL runtimeconditions_profiler-0.5.0.tar.gz
Size 79.9 kB
Tags Source
SHA-256 checksum
How to use checksums
b129a61c6b2571358bc50b7f1b4b56795e712598c5b891dbbd0b120f26f8cd14
BLAKE2b-256 checksum
How to use checksums
68cab737c8aaa76cff634becfaccfa14281461e8be02bdfd3d9caf4756f48f1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Release files / runtimeconditions_profiler-0.5.0-py3-none-any.whl

Download URL runtimeconditions_profiler-0.5.0-py3-none-any.whl
Size 47.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e029ea3cf6122ac76fa4bf202f0ec487ba63d7db8663ad77f83f688724d8b1d8
BLAKE2b-256 checksum
How to use checksums
509b9b936028c4c6ee4ab1320d775afb94ea27e688e58ed5a68bb48311e32142
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

Security for runtimeconditions-profiler 0.5.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for runtimeconditions_profiler-0.5.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page