sphobjinv

2.4 verified Mon Apr 27 auth: no python

Sphinx objects.inv Inspection/Manipulation Tool. Version 2.4 (requires Python >=3.10). Enables introspection and modification of Sphinx inventories, including conversion to/from JSON, HTML, and Text. Last release: v2.4 (2025-04-01). Release cadence: irregular.

pip install sphobjinv

Common errors

error KeyError: 'project' ↓

cause Trying to access inv.project before the inventory has been fully loaded (lazy load).

fix

Call inv.load() first, or access after invoking a property that triggers load: len(inv) or list(inv.objects).

error requests.exceptions.SSLError: HTTPSConnectionPool(host='...') ↓

cause Default requests SSL verification fails due to corporate proxy or custom CA.

fix

Set environment variable REQUESTS_CA_BUNDLE to the appropriate CA bundle path, or use a local file path for the inventory.

error ModuleNotFoundError: No module named 'sphobjinv.inv' ↓

cause Importing from obsolete module path.

fix

Use: from sphobjinv import Inventory

Warnings

breaking In v2.0, the API was overhauled: Inventory class replaced old inv module, many functions renamed. Code written for v1.x is not compatible. ↓

fix Use Inventory class from top-level sphobjinv. Refer to migration guide in docs.

gotcha Remote inventory URLs must be HTTPS. HTTP is blocked in v2.4 due to certifi enforcement; fails with requests.exceptions.SSLError if using custom CA or proxies. ↓

fix Set the environment variable REQUESTS_CA_BUNDLE to a custom CA bundle, or use a local file path instead of URL.

gotcha Inventory objects are lazily loaded from URL; iteration or len() triggers download and parsing. That may delay first access. ↓

fix Call inv.load() explicitly if you want tight control over download timing.

Imports

Inventory
wrong
```
from sphobjinv.inv import Inventory
```
correct
```
from sphobjinv import Inventory
```
Pre-v2.0 used a different module layout; now Inventory is directly importable from the top-level package.
DataObjStr
```
from sphobjinv import DataObjStr
```

Quickstart

Quick example: load a remote Sphinx objects.inv and inspect it.

from sphobjinv import Inventory

# Load a remote inventory (e.g., from Python docs)
url = "https://docs.python.org/3/objects.inv"
inv = Inventory(url=url)
print(f"Loaded {len(inv.objects)} objects from {inv.project}")

# Convert to JSON and print first object
data = inv.json()
print(data[:100])