> ## Python SDK

> Integrate Python applications with Antithesis using the Python SDK.

> Fetch the complete documentation index at: https://antithesis.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

---

## Overview

The Antithesis Python SDK enables you to integrate your Python applications with Antithesis and is available on Github [here](https://github.com/antithesishq/antithesis-sdk-python/).

The Antithesis Python SDK is intended for use with Python 3.9.0 or higher. If you want to use a different version, contact us at [support@antithesis.com](mailto:support@antithesis.com) or [ask on our Discord](https://discord.com/invite/antithesis).

### 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.

> **Note**

### Instrumentation

The Antithesis Platform includes an instrumentor package that, in the case of Python, handles *assertion cataloging* but not *coverage instrumentation*.

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:

```bash
> 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.

> **Note**

We'll also be releasing a Python instrumentor, a command-line tool which will provide *coverage instrumentation* for Python code. If you'd like to be notified when this happens, contact us at [support@antithesis.com](mailto:support@antithesis.com) or [ask on our Discord](https://discord.com/invite/antithesis).

### Using the SDK

The basic workflow for using the Antithesis Python SDK is:

1. Include the SDK in your dependencies:

```py
python -m pip install antithesis
```

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

```py
from antithesis.assertions import sometimes
```

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

```py
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 always fall back upon the [random.getrandbits(64)](https://docs.python.org/3/library/random.html#random.getrandbits) function for entropy when run outside of Antithesis.