# 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(*values)

  `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 `dict`s 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 `dict`s 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.