Skip to main content

​
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.
The SDK includes several other modules that you should never directly use in your code. Modules with names beginning with _ are internal tooling for the SDK.

​
Instrumentation

The Antithesis Platform includes an instrumentor package that, in the case of Python, handles assertion cataloging but not coverage instrumentation, please see Instrumentation for a more detailed explanation of the difference. Place directories, files, or symlinks to the code you want instrumented or cataloged in the directory /opt/antithesis/catalog/ within your container image. Antithesis will follow all symlinks while resolving the path to the cataloging directory. However, it will follow only one symlink deep into each item placed within /opt/antithesis/catalog/. That is, you should not symlink to a symlink.

​
Example cataloging directory:

> ln -s /usr/share/my_app /opt/antithesis/catalog 

> ls -lAh /opt/antithesis/catalog
lrwxrwxrwx  1 me users 4 Apr  8 17:32 /opt/antithesis/catalog -> /usr/share/my_app

> ls -lAh /opt/antithesis/catalog/
-rwxr-xr-x  1 me users  20K Apr  8 17:33 dotnet_file.dll
lrwxrwxrwx  1 me users 27 Apr  8 17:52 more_files -> /opt/my_project/java_files 
-rwxr-xr-x  1 me users  10K Apr  8 17:33 python_script.py

> ls -lA /opt/antithesis/catalog/more_files/
-rw-r--r--  1 me users  16K Apr  8 17:51 main.jar
lrwxrwxrwx  1 me users  16K Apr  8 17:51 my_other.jar -> /some/other/place.jar
Based on the example above, the following files would be instrumented:
  • dotnet_file.dll
  • python_script.py
  • main.jar
Ignored files:
  • my_other.jar - this will be ignored as we already encountered one symlink when traversing down from opt/antithesis/catalog/more_files.
Antithesis will recursively provide assertion cataloging for all .py files in this directory.
The instrumentor will, by default, act upon every language it supports in the cataloging directory: (Java , Python, JavaScript, .NET), not just Python.
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
  1. Import the SDK into each python module that uses specific SDK functions:
  from antithesis.assertions import sometimes
  1. 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}
  )
  1. Run your Python project. For example, run python -m myapp.
  2. 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