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-2022

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)

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
  • expandbool (optional) – Return data line with any uri or dispname abbreviations expanded

  • contractbool (optional) – Return data line with abbreviated uri and dispname

Returns

dlbytes (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

kwargsstr or bytes – Revised value(s) to use in the new instance for the passed keyword argument(s).

Returns

dobjDataObjBytes 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
Returns

ddict – 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.