API

The primary sphobjinv API consists of two pairs of functions:

Also exposed are two re.compile() patterns, potentially useful in parsing decoded data only:

  • p_comments – Retrieves the #-prefixed comment lines
  • p_data – Retrieves all lines not prefixed by #

The normal workflow would be:

  1. Import the module; e.g.:

    >>> import sphobjinv as soi
    
  2. Read the desired file data (compressed or uncompressed) with readfile():

    >>> fd = soi.readfile('/path/to/file')
    
  3. Decode [or encode] the file data with decode() [or encode()]:

    >>> data = soi.decode(fd)
    
  4. Write the desired file with writefile(), or otherwise use the resulting bytes data:

    >>> len(soi.p_data.findall(data))   # e.g., retrieve the number of object entries
    6319
    
    >>> soi.writefile('/path/to/new/file', data)
    

Members

decode(bstr)

Decode a version 2 intersphinx objects.inv bytestring.

The #-prefixed comment lines are left unchanged, whereas the zlib-compressed data lines are uncompressed to plaintext.

Parameters:bstrbytes – Binary string containing an encoded objects.inv file.
Returns:out_bbytes – Decoded binary string containing the plaintext objects.inv content.
encode(bstr)

Encode a version 2 intersphinx objects.inv bytestring.

The #-prefixed comment lines are left unchanged, whereas the plaintext data lines are compressed with zlib.

Parameters:bstrbytes – Binary string containing the decoded contents of an objects.inv file.
Returns:out_bbytes – Binary string containing the encoded objects.inv content.
p_comments = re.compile(b'^#.*$', re.MULTILINE)

Bytestring regex pattern for comment lines in decoded objects.inv files

p_data = re.compile(b'^[^#].*$', re.MULTILINE)

Bytestring regex pattern for data lines in decoded objects.inv files

readfile(path, cmdline=False)

Read file contents and return as binary string.

Parameters:
  • pathstr – Path to file to be opened.
  • cmdlinebool – If False, exceptions are raised as normal. If True, on raise of any subclass of Exception, the function returns None.
Returns:

bbytes – Binary contents of the indicated file.

writefile(path, contents, cmdline=False)

Write indicated file contents (with clobber).

Parameters:
  • pathstr – Path to file to be written.
  • contentsbytes – Binary string of data to be written to file.
  • cmdlinebool – If False, exceptions are raised as normal. If True, on raise of any subclass of Exception, the function returns None.
Returns:

pstr – If write is successful, echo of the path input str is returned. If any Exception is raised and cmdline is True, None is returned.