sphobjinv.data

sphobjinv data classes for individual objects.

sphobjinv is a toolkit for manipulation and inspection of Sphinx objects.inv files.

Author

Brian Skinn (brian.skinn@gmail.com)

File Created

7 Nov 2017

Copyright

(c) Brian Skinn 2016-2025

Source Repository

https://github.com/bskinn/sphobjinv

Documentation

https://sphobjinv.readthedocs.io/en/stable

License

Code: MIT License

Docs & Docstrings: CC BY 4.0 International License

See LICENSE.txt for full license terms.

Members

class DataFields(value, names=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Enum for the fields of objects.inv data objects.

DispName = 'dispname': Default display name for the object in rendered documentation when referenced as :domain:role:`name`

Domain = 'domain': Sphinx domain housing the object

Name = 'name': Object name, as recognized internally by Sphinx

Priority = 'priority': Object search priority

Role = 'role': Full name of Sphinx role to be used when referencing the object

URI = 'uri': URI to the location of the object’s documentation, relative to the documentation root

class DataObjBytes(name, domain, role, priority, uri, dispname, as_str=NOTHING, as_bytes=NOTHING)

SuperDataObj subclass generating bytes object data.

Two DataObjBytes instances will test equal if all of name, domain, role, priority, uri, and dispname are equal between them.

>>> obj = soi.DataObjBytes(
...     name=b"foo",
...     domain=b"py",
...     role=b"method",
...     priority=b"1",
...     uri=b"$",
...     dispname=b"-",
... )
>>> obj == obj
True
>>> obj == obj.evolve(name=b"quux")
False

Changed in version 2.1: Previously, attempts to compare instances resulted in a RecursionError.

class DataObjStr(name, domain, role, priority, uri, dispname, as_bytes=NOTHING, as_str=NOTHING)

SuperDataObj subclass generating str object data.

Two DataObjStr instances will test equal if all of name, domain, role, priority, uri, and dispname are equal between them.

>>> obj = soi.DataObjStr(
...     name="foo",
...     domain="py",
...     role="method",
...     priority="1",
...     uri="$",
...     dispname="-",
... )
>>> obj == obj
True
>>> obj == obj.evolve(name="quux")
False

Changed in version 2.1: Previously, attempts to compare instances resulted in a RecursionError.

class SuperDataObj

Abstract base superclass defining common methods &c. for data objects.

Intended only to be subclassed by DataObjBytes and DataObjStr, to allow definition of common methods, properties, etc. all in one place.

Where marked with $^\dagger$, DataObjBytes instances will return bytes values, whereas DataObjStr instances will return str values.

abstract property as_bytes: DataObjBytes version of instance.

property as_rst

str reST reference-like object representation.

Typically will NOT function as a proper reST reference in Sphinx source (e.g., a role of function must be referenced using :func: for the py domain).

abstract property as_str: DataObjStr version of instance.

data_line(*, expand=False, contract=False)

Compose plaintext objects.inv data line from instance contents.

The format of the resulting data line is given by data_line_fmt. DataObjBytes and DataObjStr instances generate data lines as bytes and str, respectively.

Calling with both expand and contract as True is invalid.

Parameters:

expand – bool (optional) – Return data line with any uri or dispname abbreviations expanded
contract – bool (optional) – Return data line with abbreviated uri and dispname

Returns:

dl – bytes (for DataObjBytes) or str (for DataObjStr) – Object data line

Raises:

ValueError – If both expand and contract are True

data_line_fmt = '{name} {domain}:{role} {priority} {uri} {dispname}': Helper str for generating plaintext objects.inv data lines. The field names MUST match the str values of the DataFields members.

abstract property dispname

Object default name in rendered documentation$^\dagger$.

Possibly abbreviated; see here.

abstract property dispname_abbrev

Abbreviation character(s) for display name$^\dagger$.

'-' or b'-' for version 2 objects.inv files.

property dispname_contracted: Object display name, contracted with dispname_abbrev.

property dispname_expanded: Object display name, with dispname_abbrev expanded.

abstract property domain: Sphinx domain containing the object$^\dagger$.

evolve(**kwargs)

Create a new instance with changes applied.

This helper method provides a concise means for creating new instances with only a subset of changed data fields.

The names of any kwargs MUST be keys of the dicts generated by json_dict().

Parameters:: kwargs – str or bytes – Revised value(s) to use in the new instance for the passed keyword argument(s).
Returns:: dobj – DataObjBytes or DataObjStr – New instance with updated data

json_dict(*, expand=False, contract=False)

Return the object data formatted as a flat dict.

The returned dict is constructed such that it matches the relevant subschema of sphobjinv.schema.json_schema, to facilitate implementation of Inventory.json_dict().

The dicts returned by DataObjBytes and DataObjStr both have str keys, but they have bytes and str values, respectively. The dict keys are identical to the str values of the DataFields Enum members.

Calling with both expand and contract as True is invalid.

Parameters:

expand – bool (optional) – Return dict with any uri or dispname abbreviations expanded
contract – bool (optional) – Return dict with abbreviated uri and dispname

Returns:

d – dict – Object data

Raises:

ValueError – If both expand and contract are True

abstract property name: Object name, as recognized internally by Sphinx$^\dagger$.

abstract property priority: Object search priority, as handled internally by Sphinx$^\dagger$.

abstract property role: Sphinx role to be used when referencing the object$^\dagger$.

rst_fmt = ':{domain}:{role}:`{name}`': str.format() template for generating reST-like representations of object data for as_rst (used with Inventory.suggest()).

abstract property uri

Object URI relative to documentation root$^\dagger$.

Possibly abbreviated; see here.

abstract property uri_abbrev

Abbreviation character(s) for URI tail$^\dagger$.

'$' or b'$' for version 2 objects.inv files.

property uri_contracted: Object-relative URI, contracted with uri_abbrev.

property uri_expanded: Object-relative URI, with uri_abbrev expanded.