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
- Documentation
- 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.NOTHING, as_bytes=_Nothing.NOTHING)
SuperDataObj
subclass generatingbytes
object data.Two
DataObjBytes
instances will test equal if all ofname
,domain
,role
,priority
,uri
, anddispname
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.NOTHING, as_str=_Nothing.NOTHING)
SuperDataObj
subclass generatingstr
object data.Two
DataObjStr
instances will test equal if all ofname
,domain
,role
,priority
,uri
, anddispname
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
andDataObjStr
, to allow definition of common methods, properties, etc. all in one place.Where marked with \(^\dagger\),
DataObjBytes
instances will returnbytes
values, whereasDataObjStr
instances will returnstr
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
andDataObjStr
instances generate data lines asbytes
andstr
, respectively.Calling with both expand and contract as
True
is invalid.- Parameters
- Returns
dl –
bytes
(forDataObjBytes
) orstr
(forDataObjStr
) – 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 thestr
values of theDataFields
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\).
'-'
orb'-'
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
dict
s generated byjson_dict()
.- Parameters
kwargs –
str
orbytes
– Revised value(s) to use in the new instance for the passed keyword argument(s).- Returns
dobj –
DataObjBytes
orDataObjStr
– 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 ofsphobjinv.schema.json_schema
, to facilitate implementation ofInventory.json_dict()
.The
dict
s returned byDataObjBytes
andDataObjStr
both havestr
keys, but they havebytes
andstr
values, respectively. Thedict
keys are identical to thestr
values of theDataFields
Enum
members.Calling with both expand and contract as
True
is invalid.
- 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 foras_rst
(used withInventory.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\).
'$'
orb'$'
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.