Overview:

- [https://docs.pex-tool.org/index.html](https://docs.pex-tool.org/index.html)
  - tldr - [https://docs.pex-tool.org/whatispex.html#whatispex](https://docs.pex-tool.org/whatispex.html#whatispex)
  - PEP 441 - [https://peps.python.org/pep-0441/](https://peps.python.org/pep-0441/)
- self-contained python virtual environments
  - basically zip files with a shebang (`#!/usr/bin/env python`) and a `__main__.py` file
  - shebang is the `#!` character sequence at the beginning of a script in a Unix-like operating system that specifies the interpreter to be used for executing the script (the script can therefore be run as an executable)
- this builds on top of python zip applications defined in PEP 441
  - python has ability to execute directories or ZIP-format archives as scripts since version 2.6
  - `__main__.py` must be in the root directory of the archive, with extension `.pyz` will be associated with such files (and the python launcher will recognise this)
  - the standard library defines a zipapp module for working with these archives
  - [https://github.com/python/cpython/blob/main/Lib/zipapp.py](https://github.com/python/cpython/blob/main/Lib/zipapp.py)
- can bundle the interpreter too - using scies [https://docs.pex-tool.org/scie.html](https://docs.pex-tool.org/scie.html) from science and python standalone builds [https://github.com/astral-sh/python-build-standalone](https://github.com/astral-sh/python-build-standalone) from astral
- PEX files are simple release primitives (build, copy and paste, run anywhere; for example, upload to blob, download, run cli locally)

Case studies:

- Pinterest - [https://medium.com/pinterest-engineering/building-a-python-monorepo-for-fast-reliable-development-be763781f67](https://medium.com/pinterest-engineering/building-a-python-monorepo-for-fast-reliable-development-be763781f67)
- Dagster - [https://dagster.io/blog/fast-deploys-with-pex-and-docker](https://dagster.io/blog/fast-deploys-with-pex-and-docker)
- Pants - [https://www.pantsbuild.org/blog/2022/08/02/optimizing-python-docker-deploys-using-pants#multi-stage-build-leveraging-2-pexs](https://www.pantsbuild.org/blog/2022/08/02/optimizing-python-docker-deploys-using-pants#multi-stage-build-leveraging-2-pexs)
- [https://chrismati.cz/posts/uv-pex-monorepo/](https://chrismati.cz/posts/uv-pex-monorepo/)
  - [https://github.com/chrismatix/uv-pex-monorepo/blob/main/scripts/build_pex.sh](https://github.com/chrismatix/uv-pex-monorepo/blob/main/scripts/build_pex.sh)

Usage (build and run):

- install all dependencies and transitive dependencies (the wheel files)
  - either resolved via PEX (using a `requirements.txt` file) or building the wheelhouse manually (using `pip download`)
- reference a python interpreter (or embed a standalone python build)
  - based on the environment and python version, specify the relevant specifiers for `abi` + `platform` + `python-version`

```shell
# set env variables
export SSL_CERT_FILE: "/etc/ssl/certs/ca-certificates.crt"
export UV_INDEX_URL="https://nexus.ny1.ninetyone.com/repository/pypy-all/simple"
export UV_NATIVE_TLS=true
export UV_INSECURE_HOST="nexus.ny1.ninetyone.com"

# create temp wheelhouse directory
mkdir -p temp/wheelhouse

# build package wheel to wheelhouse
uv build --wheel -o temp/wheelhouse/

# build package depdendency wheels to wheelhouse
uv export --format requirements-txt --no-hashes --no-emit-project --output-file temp/requirements.txt
uv run python -m pip download -r temp/requirements.txt \
  --only-binary :all: \
  --platform manylinux_2_17_x86_64 --platform manylinux_2_28_x86_64 --platform manylinux2014_x86_64 \
  --python-version 312 \
  --abi cp312 --abi abi3 \
  --dest temp/wheelhouse \
  --index-url="${PIP_INDEX_URL}" \
  --trusted-host="${PIP_TRUSTED_HOST}"

# build PEX file from wheelhouse
uv tool run --python 3.12 pex \
  temp/wheelhouse/*.whl \
  --use-pip-config \
  --no-transitive \
  --interpreter-constraint "CPython==3.12.*" \
  --python-shebang '#!/usr/bin/env python3.12' \
  --script uvicorn \
  --script streamlit \
  --script dagster \
  --output-file ai.pex \
  --sources-dir=.
  # --scie-python-version "3.12.7" \
  # --scie eager \
  # --scie-pbs-stripped \

# run PEX file
uv run ai.pex main:app --host 0.0.0.0 --port 6152 
```

Inside a PEX file:

- unzip the pex file:

```shell
.bootstrap
.deps
__pex__
__main__.py
PEX-INFO
```

```json
{
  "bootstrap_hash": "069ebec6124b79045e73d503453010e23c852f0d",
  "build_properties": { "pex_version": "2.59.1" },
  "code_hash": "da39a3ee5e6b4b0d3255bfef95601890afd80709",
  "deps_are_wheel_files": false,
  "distributions":
    {
      "Brotli-1.1.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl": "5f2f1915d5065e7e6e7a4351a2ea2557aeb9c2335cf61d74a66c4be670e8bf8c",
      "PyJWT-2.10.1-py3-none-any.whl": "17bcf7fd145ef9dade0c112aa7aab551f1425112c3ca92694a3ff237595ce91f",
      "ai-0.9.1-py3-none-any.whl": "f466759b3f58cdf473b882307e3c8d704762a37fbafbb5a657bb6a7d9b2494e4",
    },
  "emit_warnings": true,
  "entry_point": "uvicorn.main:main",
  "excluded": [],
  "ignore_errors": false,
  "includes_tools": false,
  "inherit_path": "false",
  "inject_args": [],
  "inject_env": {},
  "inject_python_args": [],
  "interpreter_constraints": [],
  "max_install_jobs": 1,
  "overridden": [],
  "pex_hash": "d0ee458b14516defda574819605c914a3d8722c0",
  "pex_path": "",
  "pex_paths": [],
  "requirements": ["ai==0.9.1"],
  "strip_pex_env": true,
  "venv": false,
  "venv_bin_path": "false",
  "venv_copies": false,
  "venv_hermetic_scripts": true,
  "venv_site_packages_copies": false,
  "venv_system_site_packages": false,
}
```

Cookbook:

- long running processes
  - [https://docs.pex-tool.org/recipes.html#long-running-pex-applications-and-daemons](https://docs.pex-tool.org/recipes.html#long-running-pex-applications-and-daemons)
  - use [https://github.com/dvarrazzo/py-setproctitle](https://github.com/dvarrazzo/py-setproctitle) to alter process title when debugging running processes
- environment variables
  - [https://docs.pex-tool.org/api/vars.html](https://docs.pex-tool.org/api/vars.html)

Using PEX files as release primitives deployments

- my heuristics
  - for all tests
    - you want corrrectness and speed
  - for routers
    - ensure the signature is valid (ie the underlying methods and attributes are called correctly)
  - for clients (external APIs)
    - use mocks and autospec
    - ensure the signature is valid (ie the underlying methods and attributes are called correctly)
  - for clients (databases)
    - use sqlite in the session manager, then setup and teardown relevent test cases
  - for business logic that use clients
    - use (verified) fake clients that follow a protocol
      - enforce contract verification tests between the fake objects and the real objects
    - ensure the behaviour is valid (ie the inputs and outputs match expectations)

- [https://martinfowler.com/articles/mocksArentStubs.html](https://martinfowler.com/articles/mocksArentStubs.html)
  - dummy objects (passed around but never used)
  - fake objects (working implementation with some shortcut ie in-memory database)
  - stubs (provide canned answers to specific calls)
  - spies (stubs that record usage information)
  - mocks (objects pre-programmed with expectations)

- [https://pythonspeed.com/articles/verified-fakes/](https://pythonspeed.com/articles/verified-fakes/)
  - testing external services; slow, or fake and uncertain
  - use test doubles
    - this ensures you match the signaure but not the behaviour
    - example
      - `MessageService → TwitterClient`
      - `Tests → MessageService → TwitterClient`
      - `Tests → MessageService → FakeTwitterClient`
  - use verified fakes (when the API is slow or you want to test frequently)
    - two tests, once against the real client and once against the fake client (contract verification tests)
    - example
      - `TwitterContractTests → TwitterClient`
      - `TwitterContractTests → FakeTwitterClient`

- [https://www.b-list.org/weblog/2023/dec/08/mock-python-httpx/](https://www.b-list.org/weblog/2023/dec/08/mock-python-httpx/)
  - make testing easier
    - dependency injection helps with this

[https://hynek.me/articles/what-to-mock-in-5-mins/](https://hynek.me/articles/what-to-mock-in-5-mins/)
- don't mock what you don't own
- avoid the need to use multiple layers of mocks and patches, or worry about the orderings and references, brittle when module paths are refactored
- ensure determinism in results using stubs
  - [https://github.com/alex/pretend](https://github.com/alex/pretend)
- you may have business logic tests, but spend lots of time with boilerplate trying to mimic a client whose API may change ay any time, are you even testing what you want to test

- [https://nedbatchelder.com/blog/202202/why_your_mock_still_doesnt_work.html](https://nedbatchelder.com/blog/202202/why_your_mock_still_doesnt_work.html)
  - mocks are dangerous
    - you can call any method or access any attribute and they will return another mock
    - this can silence errors if patch ordering is incorrect or if methods and attributes don't exist
  - use `spec=True` and `autospec=True` (which recursively applies to any new mocks from the original mock)

```python
from unittest.mock import patch

@patch("httpx.Client")
def test_httpx(mock_client):
    mock_client.fake_method_that_doesnt_exist()  # passes
    mock_client.another_fake_thing()  # passes
    mock_client.xyz.abc()  # passes
    print("All fake methods accepted! 😱")
```

Luke Miloszewski

Featured Posts

Featured Projects