Skip to main content

fprime-fpp-python

Native Python bindings to the FPP compiler. Installed as fprime-fpp-python, imported as fpp.

The extension binds directly to the Rust FPP compiler via PyO3.

Installation

pip install fprime-fpp-python

An abi3 wheel, usable on CPython ≥ 3.10. Building from source needs Rust ≥ 1.85 and maturin.

Usage

import fpp

model = fpp.analyze(source="""
module M {
  array Arr = [4] U32
  constant answer = 6 * 7
}
""")

model.has_errors                             # False
for d in model.diagnostics:
    d.level                                  # fpp.DiagnosticLevel.Error
    print(d.display)                         # 'path:line:col: error: message'
    print(d)                                 # the compiler's console rendering

(unit,) = model.ast                          # one translation unit per input
(module,) = unit.members                     # fpp.ast.DefModule
[type(m).__name__ for m in module.members]   # ['DefArray', 'DefConstant']

arr = model.lookup("M.Arr")                                     # Symbol.ArrayType
arr.definition.resolved_type.array_size                         # 4
model.lookup("M.answer").definition.value.resolved_value.value  # 42

All inputs to one call are analyzed together. A bare string is a path, source= is text, and imports= — the counterpart of fpp-to-cpp -i — is analyzed the same way but is not part of what you asked about:

model = fpp.analyze(["MyComponent.fpp"], imports=["Fw/Fw.fpp"])
[u.uri for u in model.ast if u.is_source]    # ['MyComponent.fpp']

parse is the fast front end: it stops after include resolution, so you get syntax and nothing resolved.

tree = fpp.parse(["A.fpp", "B.fpp"])
[u.uri for u in tree.units]                  # ['A.fpp', 'B.fpp']

The syntax tree lives in the fpp.ast submodule — one class per grammar production, plus the AstNode base and the enums the grammar spells (fpp.ast.IntegerKind, fpp.ast.ComponentKind). fpp itself is the analysis: Model, Analysis, the symbol/type/value unions, and the semantic entities. The split is what lets both keep the compiler's own names, since three of them belong to each — fpp.Connection is the analyzed connection, fpp.ast.Connection the syntax it came from.

from fpp.ast import DefArray

isinstance(module.members[0], DefArray)      # True
type(module.members[0]).__module__           # 'fpp.ast'

Subclass fpp.AstVisitor — it takes AST nodes, but it is an entry point, so it stays in fpp beside analyze — and override visit_<type(node).__name__>. Traversal is deep by default: super() descends, omitting it prunes.

class Constants(fpp.AstVisitor):
    def __init__(self):
        self.values = {}

    def visit_DefConstant(self, node):
        self.values[node.name] = node.value.resolved_value.value
        super().visit_DefConstant(node)

consts = Constants()
consts.visit(model)                          # or a SyntaxTree, TransUnit, or node
consts.values                                # {'answer': 42}

Semantic types are closed unions.

match arr.definition.resolved_type:
    case fpp.Type.Array() as a:
        elt = a.anon_array.elt_type
        isinstance(elt, fpp.Type.PrimitiveInt) and elt.value == fpp.ast.IntegerKind.U32

Annotate with <Base>.Variant — fpp.Type.Variant, fpp.Value.Variant — rather than the base class. It is the closed union over the variants, so a type checker can tell you which case you forgot.

def describe(v: fpp.Value.Variant) -> str:
    match v:
        case fpp.Value.Integer():
            return f"integer {v.value}"
        case fpp.Value.String():
            return f"string {v.value}"
        ...
        case _:
            typing.assert_never(v)   # fails while any variant is unhandled

Findings of your own report like compiler errors: build a Diagnostic against any node's span, add child annotations and notes, and print it.

node = model.lookup("M.answer").definition
print(fpp.Diagnostic(
    "answer is unused", level=fpp.DiagnosticLevel.Warning,
    span=node.span,
    children=[fpp.DiagnosticMessage("delete it")],
))
#  --> mem.fpp:4:3
#   |
# 4 |   constant answer = 6 * 7
#   |   ^^^^^^^^^^^^^^^^^^^^^^^ answer is unused
#   |
#   = note: delete it

A check can raise its finding instead of returning it: fpp.DiagnosticError carries a Diagnostic, and everything on that diagnostic stays writable, so each handler on the way out can add the context it knows.

try:
    check_component(instance.component)
except fpp.DiagnosticError as error:
    error.diagnostic.add_note("in this instance", span=instance.node.span)
    raise

Development

A Cargo workspace member of fpp-tools. The node wrappers and the recording walk are expanded by fpp_python_macros from checked-in declarations (src/ast/defs.rs, src/sem/defs.rs); the core (pipeline, ir_core, lower_core, noderef, model, visitor, diagnostics) is hand-written.

Those declarations and the two stubs are generated and checked in. Change the generator or the macro, never the file, and re-run make. CI fails on drift.

maturin develop            # build + install into the active venv
pytest tests/              # run the tests

make nightly               # one-time: the nightly the bindgen's rustdoc needs
make                       # regenerate the declarations, then the stubs
make help                  # the individual codegen targets

The bindgen reflects fpp_analysis from rustdoc JSON, whose schema is unstable, so the nightly is pinned exactly — in fpp_python_bindgen/nightly-toolchain alongside the rustdoc-types pin in its Cargo.toml. Bump the two together. FPP_BINDGEN_TOOLCHAIN overrides the toolchain for a one-off run.

Metadata

Release files for fprime-fpp-python 4.0.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 fprime-fpp-python 4.0.0
File Size Uploaded Provenance Actions
fprime_fpp_python-4.0.0.tar.gz 669.2 kB With provenance Details for fprime_fpp_python-4.0.0.tar.gz

Built distributions (wheels)

Table of built distributions (wheels) for fprime-fpp-python 4.0.0
File Interpreter ABI Platform Actions
fprime_fpp_python-4.0.0-cp310-abi3-win_amd64.whl CPython 3.10 abi3 Windows x86-64 Details for fprime_fpp_python-4.0.0-cp310-abi3-win_amd64.whl
fprime_fpp_python-4.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl CPython 3.10 abi3 Linux glibc 2.17+ x86-64 Details for fprime_fpp_python-4.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
fprime_fpp_python-4.0.0-cp310-abi3-macosx_11_0_arm64.whl CPython 3.10 abi3 macOS 11.0+ ARM64 Details for fprime_fpp_python-4.0.0-cp310-abi3-macosx_11_0_arm64.whl

Total release size: 8.1 MB

Release files / fprime_fpp_python-4.0.0.tar.gz

Download URL fprime_fpp_python-4.0.0.tar.gz
Size 669.2 kB
Tags Source
SHA-256 checksum
How to use checksums
de886b3c7e7aa7e9259ec4f35852e6d7577c9333cb23e56fe6968e233dc9dca8
BLAKE2b-256 checksum
How to use checksums
87cf8b9a742342594b19e892f5798324cf63010bc538decb1c50e49d4f049d6d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 27, 2026.

Transparency log

Release files / fprime_fpp_python-4.0.0-cp310-abi3-win_amd64.whl

Download URL fprime_fpp_python-4.0.0-cp310-abi3-win_amd64.whl
Size 2.5 MB
Tags CPython 3.10 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
b2eff075c4d33ab44317b4474d9b322f8c918cd986f017059fc721d28e14d027
BLAKE2b-256 checksum
How to use checksums
5a6ad7295dde251c5740c32f98a44b29f500ce5c109783d31e9f96ed15b72742
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 27, 2026.

Transparency log

Release files / fprime_fpp_python-4.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL fprime_fpp_python-4.0.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 2.6 MB
Tags CPython 3.10 Linux glibc 2.17+ x86-64 abi3
SHA-256 checksum
How to use checksums
fd5ace058f865301b144dfa533863c048c1d4f4c65324044145f8cf718c27b08
BLAKE2b-256 checksum
How to use checksums
ea06251fde60ee42df83404f4d071b220beb8ebcd9aad9a9a4b19e58719b2b08
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 27, 2026.

Transparency log

Release files / fprime_fpp_python-4.0.0-cp310-abi3-macosx_11_0_arm64.whl

Download URL fprime_fpp_python-4.0.0-cp310-abi3-macosx_11_0_arm64.whl
Size 2.4 MB
Tags CPython 3.10 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
902cd1bbe5df86bfbd0586456bc36a486cf5c3451ae462d0557144c35bfc1143
BLAKE2b-256 checksum
How to use checksums
6d81629ddb4fa5eba95fd20d14938d0e97caddac6a6d5d7c124ef13a871e66e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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 Oct 27, 2026.

Transparency log

Security for fprime-fpp-python 4.0.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

All 4 files in this release have been uploaded with provenance metadata.

Select from 4 files

Attestation for fprime_fpp_python-4.0.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 Oct 27, 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.

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