API

The primary sphobjinv API consists of two pairs of functions:

• readfile() / writefile() – Read/write files from/to disk as bytes, for proper behavior of zlib (de)compression.
• encode() / decode() – Encode/decode the object data read from disk.

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:bstr – bytes – Binary string containing an encoded objects.inv file. Returns:out_b – bytes – 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:bstr – bytes – Binary string containing the decoded contents of an objects.inv file. Returns:out_b – bytes – 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:

• path – str – Path to file to be opened.
• cmdline – bool – If False, exceptions are raised as normal. If True, on raise of any subclass of Exception, the function returns None.

Returns:

b – bytes – Binary contents of the indicated file.

writefile(path, contents, cmdline=False)

Write indicated file contents (with clobber).

Parameters:

• path – str – Path to file to be written.
• contents – bytes – Binary string of data to be written to file.
• cmdline – bool – If False, exceptions are raised as normal. If True, on raise of any subclass of Exception, the function returns None.

Returns:

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