Antithesis Python SDK

Overview

The Antithesis Python SDK enables you to integrate your Python applications with Antithesis and is available on Github here.

The Antithesis Python SDK is intended for use with Python 3.9.0 or higher. Contact us if you want to use a different version.

Functionality

Like our other SDKs, the Antithesis Python SDK offers three main types of functionality:

• The assertions module allows you to define test properties about your software or test template.
• The random module functions request structured and unstructured randomness from the Antithesis Platform.
• The lifecycle module functions inform the Antithesis Environment that particular test phases or milestones have been reached.

Assertion cataloging for Python is handled by the Antithesis Platform directly. You don’t need to do anything other than including assertions in your code.

We’ll also be releasing a Python instrumentor, a command-line tool which will provide coverage instrumentation for Python code. You can read more about the uses of coverage instrumentation here. Contact us if you’d like to be notified when this happens.

Using the SDK

The basic workflow for using the Antithesis Python SDK is:

1. Include the SDK in your dependencies:

  python -m pip install antithesis

2. Import the SDK into each python module that uses specific SDK functions:

  from antithesis.assertions import sometimes

3. Call SDK functions from your code - for example:

sometimes(
   x1 > x2, 
   "x1 is larger than x2 at some point", 
   {"x1": x1, "x2": x2, "y1": y1, "y2": y2}
  )

4. Run your Python project. For example, run python -m myapp.

5. Deploy your build into production, or into Antithesis to test.

SDK runtime behavior

When your code is run outside Antithesis, our SDK has sensible fallback behavior with minimal performance overhead. This enables you to have a single build of your software that runs both inside and outside Antithesis.

Functions in the assertions module and lifecycle module have 2 modes for local execution:

1. Default, where assert and lifecycle use local implementations of Antithesis functionality. However, the results will not be logged anywhere because no logfile has been specified.

   This mode is the default behavior, called when you run, for instance: python -m myapp.

2. Default with logging, which is the same as the above but logs output locally in a structured JSON format.

   This mode is selected at runtime by setting the environment variable ANTITHESIS_SDK_LOCAL_OUTPUT at program startup. This variable must be set to a filepath: a logfile will be created at this location. The file must be located inside an already-existing directory. You may supply either a relative or absolute path.For instance, set ANTITHESIS_SDK_LOCAL_OUTPUT=assertions_20240520.json python -m myapp for the example above.

Functions in the random module module always fall back upon the random.getrandbits(64) function for entropy when run outside of Antithesis.

Further reading

• Tutorial
• Assert (reference)
• Lifecycle (reference)
• Random (reference)