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-2018

Source Repository

http://www.github.com/bskinn/sphobjinv

Documentation

http://sphobjinv.readthedocs.io

License

The MIT License; see LICENSE.txt for full license terms

Members

class HeaderFields

Enum for various inventory-level data items.

A subset of these Enum values is used in various Regex, JSON, and string formatting contexts within Inventory and schema.json_schema.

Count = 'count'

Number of objects contained in the inventory

Metadata = 'metadata'

The str value of this Enum member is accepted as a root-level key in a dict to be imported into an Inventory. The corresponding value in the dict may contain any arbitrary data. Its possible presence is accounted for in schema.json_schema.

The data associated with this key are ignored during import into an Inventory.

Project = 'project'

Project name associated with an inventory

Version = 'version'

Project version associated with an inventory

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 bytes plaintext contents of an objects.inv inventory.

zlib

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

fname_plain

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

fname_zlib

Object is the str 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

count

Count of objects currently in inventory.

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

Generate a plaintext objects.inv as 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.

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:

• expand – bool (optional) – Return strs with any uri or dispname abbreviations expanded
• contract – bool (optional) – Return strs with abbreviated uri and dispname values

Returns:

obj_l – list 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:

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

class SourceTypes

Enum for the import mode used in instantiating an Inventory.

Since Enum keys iterate in definition order, the definition order here defines the order in which Inventory objects attempt to parse a source object passed to Inventory.__init__() either as a positional argument or via the generic source keyword argument.

This order DIFFERS from the documentation order, which is alphabetical.

BytesPlaintext = 'bytes_plain'

Instantiation from a plaintext objects.inv bytes.

BytesZlib = 'bytes_zlib'

Instantiation from a zlib-compressed objects.inv bytes.

DictJSON = 'dict_json'

Instantiation from a dict validated against schema.json_schema.

FnamePlaintext = 'fname_plain'

Instantiation from a plaintext objects.inv file on disk.

FnameZlib = 'fname_zlib'

Instantiation from a zlib-compressed objects.inv file on disk.

Manual = 'manual'

No source; Inventory was instantiated with project and version as empty strings and objects as an empty list.

URL = 'url'

Instantiation from a zlib-compressed objects.inv file downloaded from a URL.