sphobjinv.data

sphobjinv data classes for individual objects.

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

Author
Brian Skinn (bskinn@alum.mit.edu)
File Created
7 Nov 2017
Copyright
(c) Brian Skinn 2016-2018
Source Repository
http://www.github.com/bskinn/sphobjinv
Documentation
http://sphobjinv.readthedocs.io
License
The MIT License; see LICENSE.txt for full license terms

Members

class DataFields

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.

as_bytes

DataObjBytes version of instance.

as_str

DataObjStr version of instance.

dispname

Object default name in rendered documentation\(^\dagger\).

Possibly abbreviated; see here.

domain

Sphinx domain containing the object\(^\dagger\).

name

Object name, as recognized internally by Sphinx\(^\dagger\).

priority

Object search priority\(^\dagger\).

role

Sphinx role to be used when referencing the object\(^\dagger\).

uri

Object URI relative to documentation root\(^\dagger\).

Possibly abbreviated; see here.

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

SuperDataObj subclass generating str object data.

as_bytes

DataObjBytes version of instance.

as_str

DataObjStr version of instance.

dispname

Object default name in rendered documentation\(^\dagger\).

Possibly abbreviated; see here.

domain

Sphinx domain containing the object\(^\dagger\).

name

Object name, as recognized internally by Sphinx\(^\dagger\).

priority

Object search priority\(^\dagger\).

role

Sphinx role to be used when referencing the object\(^\dagger\).

uri

Object URI relative to documentation root\(^\dagger\).

Possibly abbreviated; see here.

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.

as_bytes

DataObjBytes version of instance.

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).

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.

dispname

Object default name in rendered documentation\(^\dagger\).

Possibly abbreviated; see here.

dispname_abbrev

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

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

dispname_contracted

Object display name, contracted with dispname_abbrev.

dispname_expanded

Object display name, with dispname_abbrev expanded.

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

d – dict – Object data
Raises:

ValueError – If both expand and contract are True
name

Object name, as recognized internally by Sphinx\(^\dagger\).

priority

Object search priority\(^\dagger\).

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()).

uri

Object URI relative to documentation root\(^\dagger\).

Possibly abbreviated; see here.

uri_abbrev

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

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

uri_contracted

Object relative URI, contracted with uri_abbrev.

uri_expanded

Object relative URI, with uri_abbrev expanded.