Python Plugin SDK Initial Release
Written by Julian Lanson
Posted on April 2, 2025
The Hipcheck team is pleased to announce the initial release of our Python plugin SDK, version 0.2.1!
📖 Hipcheck Plugin Background
As you may be aware, last year Hipcheck transitioned its analysis subsystem to a plugin-based design. When analyzing a target repo, all of the analyses Hipcheck runs are now structured as plugins that are fetched, started, and queried by Hipcheck core. Not only does this allow users to control by configuration which set of analyses they want to run, but users can now develop and publish their own data sources or top-level Hipcheck analyses. Since all plugins use the same communication protocol, Hipcheck core treats user-defined plugins no differently than those maintained by the Hipcheck team.
Plugins expose one or more endpoints that can be queried. During analysis, Hipcheck core queries the top-level analyses (specified by the user) by providing the analysis target. As part of their endpoint logic, plugins may in turn query other plugins that they have specified as dependencies. One of the appealing aspects of Hipcheck's modular plugin design is that every query endpoint just outputs data; we use our policy expression language to let users define how that data becomes a pass-fail determination. That means any endpoint's output can be either a top-level analysis, or raw input to a higher-level plugin. We think this composability will be one of the strengths of the Hipcheck plugin ecosystem.
🐍 The Python Plugin SDK
Hipcheck core communicates with plugins over gRPC using a protobuf-defined
protocol. Due to message size limits, there is a certain amount of complex logic
involved in fragmenting and de-fragmenting messages on either side of the gRPC
connection. There are also the matters of turning .proto file definitions into
class/struct definitions, and of managing multiple concurrent "query" sessions
between Hipcheck and a given plugin.
Naturally, we don't want everyone writing plugins (including us!) to have to implement all this logic themselves each time. Late last year we released the Rust Hipcheck SDK for writing plugins, upon which (currently) all of our officially maintained plugins depend. The SDK handles all of the communication and startup messiness, and lets the author focus on the important stuff - the business logic of the query endpoints.
While we on the Hipcheck team are all happy writing Rust and Rust's popularity seems to increase steadily, in order to drastically expand the universe of people able and willing to write Hipcheck plugins, we decided to implement a second SDK in a more established language. We decided on Python for its ubiquity, rapid development pace, and large ecosystem of existing tools. Python being an interpreted and duck-typed language is very unlike Rust, and would also serve as a good stress test of our protocol logic.
Over the past couple of months we've been working on implementing the Python
plugin SDK, and we are now proud to announce that we have reached feature parity
with the Rust SDK. We are marking 0.2.1 as the first usable release of the
Python SDK on PyPI (we had an older version on PyPI already just to claim the
package name). News of the Python SDK has already been met with excitement from
colleagues who have said they have Python tools they'd love to slot into
Hipcheck plugins, but having to interface with Rust was too big a barrier.
Note that this is not a 1.0.0 release - we still have some minor augmentations
to the .proto protocol spec in the works. We think changes to the user-facing
API of the SDK will slight, but plugin authors should be prepared and should not
take this as a commitment to a stable API.
🏁 Getting Started
If you'd like to get started with the Python SDK: