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