abi3audit: Python ABI3 Compliance Auditor

Common errors

• abi3audit: command not found

  cause The `abi3audit` executable is not in your system's PATH, or the package was not installed correctly.
  fix Ensure `abi3audit` is installed via `pip install abi3audit` in the active Python environment. If using a virtual environment, ensure it is activated. Verify the executable's location and confirm your PATH includes the directory where pip installs scripts.

• Error: the following arguments are required: TARGET

  cause The `abi3audit` command was called without specifying a target (e.g., package name, wheel file, or shared object).
  fix Provide a target for the audit. For example, `abi3audit my-package-name`, `abi3audit my_package.whl`, or `abi3audit my_module.abi3.so`.

• Unsupported Python version: You are running Python X.Y, but abi3audit requires >=3.10

  cause The Python interpreter being used to run abi3audit (or from which it was installed) is an unsupported version.
  fix Activate a Python environment with version 3.10 or newer, or upgrade your Python installation. Uninstall and reinstall abi3audit in the correct environment.

• Could not find package 'nonexistent-package' on PyPI

  cause The specified package name does not exist on PyPI or is misspelled.
  fix Double-check the package name for typos or confirm its presence on PyPI. If it's a local file, ensure the path is correct.

• No ABI3 wheels found for package 'some-package'

  cause The specified package exists, but it does not publish any wheels explicitly tagged as `abi3` on PyPI for the Python versions abi3audit checks by default.
  fix This is often not an error with `abi3audit` itself, but an informational message. The package might not use the stable ABI, or its ABI3 wheels might not be discoverable under current criteria. Consider auditing a local wheel file if you suspect an ABI3 wheel exists but isn't found.

Warnings

• breaking Starting with version 0.0.26, abi3audit officially drops support for Python 3.9. Ensure your environment uses Python 3.10 or newer.
  Fix: Upgrade your Python environment to 3.10 or a later supported version (e.g., Python 3.11, 3.12, 3.13, 3.14). If Python 3.9 is required, you must use an older version of abi3audit, such as 0.0.25, and pin its version accordingly.
• gotcha The support for Python 3.9 has fluctuated. It was re-added in v0.0.25 but then dropped again in v0.0.26. This can lead to unexpected compatibility issues if you rely on specific minor versions.
  Fix: Always check the `requires_python` metadata and the release notes for abi3audit. For stability, explicitly pin the abi3audit version in your project (e.g., `abi3audit==0.0.25`) if you depend on a specific Python version that has had fluctuating support.
• gotcha When auditing bare `.abi3.so` shared objects, abi3audit cannot infer the intended minimum ABI3 version and defaults to the lowest known version (abi3-cp32). This might result in false positives for symbols stabilized in later Python versions.
  Fix: Whenever possible, audit entire wheels or PyPI packages (e.g., `abi3audit my_package.whl` or `abi3audit my-package`) rather than individual shared objects, as wheels contain the necessary metadata for accurate analysis.
• gotcha abi3audit is a best-effort tool and cannot detect dynamic ABI3 violations (e.g., C extensions calling `dlsym(3)` to invoke non-abi3 functions at runtime).
  Fix: Be aware of this limitation and combine `abi3audit` with other dynamic analysis tools if your C extensions utilize dynamic symbol loading.
• breaking Python 3.8 support was removed in version 0.0.18.
  Fix: Upgrade your Python environment to 3.9 or newer, or use an older version of abi3audit if Python 3.8 support is critical.

Install

• pip install abi3audit Install with pip

Imports

• abi3audit CLI

  import subprocess
  subprocess.run(['abi3audit', 'package_name'], check=True)

  abi3audit is primarily a command-line tool. While it has an internal Python API, direct programmatic imports like `from abi3audit import ...` are not the typical or officially supported way to interact with it for auditing tasks. It's best used by invoking its CLI via `subprocess`.

Quickstart

This quickstart demonstrates how to programmatically audit a PyPI package for ABI3 compliance using `abi3audit` via a subprocess call. The example audits 'numpy' and uses the `--verbose` flag for detailed output. It handles potential errors like `abi3audit` not being found or an audit failing.

import subprocess

# Audit a specific PyPI package for ABI3 compliance
# Replace 'numpy' with the actual package name you wish to audit.
# The '--verbose' flag provides detailed output.
package_to_audit = 'numpy'

try:
    print(f"Auditing {package_to_audit} for ABI3 compliance...")
    result = subprocess.run(
        ['abi3audit', package_to_audit, '--verbose'],
        capture_output=True,
        text=True,
        check=True
    )
    print("\nAudit Successful:\n")
    print(result.stdout)
except subprocess.CalledProcessError as e:
    print(f"\nAudit Failed for {package_to_audit}:\n")
    print(f"Stderr: {e.stderr}")
    print(f"Stdout: {e.stdout}")
except FileNotFoundError:
    print("Error: 'abi3audit' command not found. Is it installed and in your PATH?")