# sphobjinv.inventory

`sphobjinv` data class for full inventories.

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

Author

  Brian Skinn (brian.skinn@gmail.com)

File Created

  7 Dec 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 Inventory(source=None, plaintext=None, zlib=None, fname_plain=None, fname_zlib=None, dict_json=None, url=None, count_error=True)

  Entire contents of an objects.inv inventory.

  All information is stored internally as `str`, even if imported from a `bytes` source.

  All arguments except count_error are used to specify the source from which the `Inventory` contents are to be populated. At most ONE of these source arguments may be other than `None`.

  The count_error argument is only relevant to the dict_json source type.

  Equality comparisons between `Inventory` instances will return `True` if `project`, `version`, and all contents of `objects` are identical, even if the instances were created from different sources:

      >>> inv1 = soi.Inventory(
      ...     url="https://sphobjinv.readthedocs.io/en/latest/objects.inv"
      ... )
      >>> inv2 = soi.Inventory(inv1.data_file())
      >>> inv1 is inv2
      False
      >>> inv1 == inv2
      True

  Changed in version 2.1: Previously, an `Inventory` instance would compare equal only to itself.

  source

  > The `Inventory` will attempt to parse the indicated source object as each of the below types in sequence, except for url.

  > This argument is included mainly as a convenience feature for use in interactive sessions, as invocations of the following form implicitly populate source, as the first positional argument:

  >     >>> inv = Inventory(src_obj)

  > In most cases, for clarity it is recommended that programmatic instantiation of `Inventory` objects utilize the below format-specific arguments.

  plaintext

  > Object is to be parsed as the UTF-8 `bytes` plaintext contents of an objects.inv inventory.

  zlib

  > Object is to be parsed as the UTF-8 `bytes` zlib-compressed contents of an objects.inv inventory.

  fname_plain

  > Object is the `str` or `Path` path to a file containing the plaintext contents of an objects.inv inventory.

  > Changed in version 2.1: Previously, this argument could only be a `str`.

  fname_zlib

  > Object is the `str` or `Path` path to a file containing the zlib-compressed contents of an objects.inv inventory.

  > Changed in version 2.1: Previously, this argument could only be a `str`.

  dict_json

  > Object is a `dict` containing the contents of an objects.inv inventory, conforming to the JSON schema of `schema.json_schema`.

  > If count_error is passed as `True`, then a `ValueError` is raised if the number of objects found in the `dict` does not match the value associated with its count key. If count_error is passed as `False`, an object count mismatch is ignored.

  url

  > Object is a `str` URL to a zlib-compressed objects.inv file. Any URL type supported by `urllib.request` SHOULD work; only http: and file: have been directly tested, however.

  > No authentication is supported at this time.

  Members

  property count

    Count of objects currently in inventory.

  data_file(*, expand=False, contract=False)

    Generate a plaintext objects.inv as UTF-8 `bytes`.

    `bytes` is used here as the output type since the most common use cases are anticipated to be either (1) dumping to file via `sphobjinv.fileops.writebytes()` or (2) compressing via `sphobjinv.zlib.compress()`, both of which take `bytes` input.

    Calling with both expand and contract as `True` is invalid.

    Parameters:

      - expand – `bool` (optional) – Generate `bytes` with any `uri` or `dispname` abbreviations expanded

      - contract – `bool` (optional) – Generate `bytes` with abbreviated `uri` and `dispname` values

    Returns:

      b – `bytes` – Inventory in plaintext objects.inv format

    Raises:

      ValueError – If both expand and contract are `True`

  header_preamble = '# Sphinx inventory version 2'

    Preamble line for v2 objects.inv header

  header_project = '# Project: {project}'

    Project line `str.format()` template for objects.inv header

  header_version = '# Version: {version}'

    Version line `str.format()` template for objects.inv header

  header_zlib = '# The remainder of this file is compressed using zlib.'

    zlib compression line for v2 objects.inv header

  json_dict(expand=False, contract=False)

    Generate a flat `dict` representation of the inventory.

    The returned `dict` matches the schema of `sphobjinv.schema.json_schema`.

    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` values

    Returns:

      d – `dict` – Inventory data; keys and values are all `str`

    Raises:

      ValueError – If both expand and contract are `True`

  objects

    `list` of `DataObjStr` representing the data objects of the inventory. Can be edited directly to change the inventory contents. Undefined/random behavior/errors will result if the type of the elements is anything other than `DataObjStr`.

  property objects_rst

    `list` of objects formatted in a `str` reST-like representation.

    The format of each `str` in the `list` is given by `data.SuperDataObj.rst_fmt`.

    Returns:

      obj_l – `list` of `str` – Inventory object data in reST-like format

  project

    `str` project display name for the inventory (see here).

  source_type

    `SourceTypes` `Enum` value indicating the type of source from which the instance was generated.

  suggest(name, *, thresh=50, with_index=False, with_score=False)

    Suggest objects in the inventory to match a name.

    `suggest()` makes use of the edit-distance scoring library `fuzzywuzzy` to identify potential matches to the given name within the inventory. The search is performed over the `list` of `str` generated by `objects_rst()`.

    thresh defines the minimum `fuzzywuzzy` match quality (an integer ranging from 0 to 100) required for a given object to be included in the results list. Can be any float value, but best results are generally obtained with values between 50 and 80, depending on the number of objects in the inventory, the confidence of the user in the match between name and the object(s) of interest, and the desired fidelity of the search results to name.

    This functionality is provided by the ‘suggest’ subparser of the command-line interface.

    Parameters:

      - name – `str` – Object name for `fuzzywuzzy` pattern matching

      - thresh – `float` – `fuzzywuzzy` match quality threshold

      - with_index – `bool` – Include with each matched name its index within `Inventory.objects`

      - with_score – `bool` – Include with each matched name its `fuzzywuzzy` match quality score

    Returns:

      res_l – `list`

      If both with_index and with_score are `False`, members are the `str` `SuperDataObj.as_rst()` representations of matching objects.

      If either is `True`, members are `tuple`s of the indicated match results:

      with_index == True: (as_rst, index)

      with_score == True: (as_rst, score)

      with_index == with_score == True: (as_rst, score, index)

  version

    `str` project display version for the inventory (see here).