sphobjinv.inventory

sphobjinv data class for full inventories.

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

Author

Brian Skinn (bskinn@alum.mit.edu)

File Created

7 Dec 2017

Copyright

(c) Brian Skinn 2016-2020

Source Repository

https://github.com/bskinn/sphobjinv

Documentation

https://sphobjinv.readthedocs.io/en/latest

License

The MIT 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.

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.

fname_zlib

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

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
Returns

bbytes – 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
Returns

ddict – 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.

Calling with both expand and contract as True is invalid.

Parameters
Returns

obj_llist of str – Inventory object data in reST-like format

Raises

ValueError – If both expand and contract are True

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 powerful pattern-matching 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
Returns

res_llist

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