Command-Line Usage: “convert” Mode

The convert subparser is used for all conversions of “version 2” Sphinx inventory files among plaintext, zlib-compressed, and (unique to sphobjinv) JSON formats. Currently, the sphobjinv CLI can read inventory data from local files in any of these three formats, as well as the standard zlib-compressed format from files in remote locations (see --url). At the moment, the only output method supported is writing to a local file, again in all three formats.

Note

If reading from stdin or writing to stdout would be useful to you, please leave a note at #74 so I can gauge interest.

Basic file conversion to the default output filename is straightforward:

>>> Path('objects_attrs.txt').is_file()
False
>>> cli_run('sphobjinv convert plain objects_attrs.inv')

Conversion completed.
'...objects_attrs.inv' converted to '...objects_attrs.txt' (plain).


>>> print(file_head('objects_attrs.txt', head=6))
# Sphinx inventory version 2
# Project: attrs
# Version: 17.2
# The remainder of this file is compressed using zlib.
attr.Attribute py:class 1 api.html#$ -
attr.Factory py:class 1 api.html#$ -

A different target filename can be specified, to avoid overwriting an existing file:

>>> cli_run('sphobjinv convert plain objects_attrs.inv', inp='n\n')
File exists. Overwrite (Y/N)? n


Exiting...

>>> cli_run('sphobjinv convert plain objects_attrs.inv objects_attrs_foo.txt')

Conversion completed.
'...objects_attrs.inv' converted to '...objects_attrs_foo.txt' (plain).

If you don’t provide an output file extension, the sphobjinv defaults (.inv/.txt/.json) will be used.

If you want to pull an input file directly from the Web, use --url (note that the base filename is not inferred from the indicated URL):

>>> cli_run('sphobjinv convert plain -u https://github.com/bskinn/sphobjinv/raw/master/tests/resource/objects_attrs.inv')

Remote inventory found.

Conversion completed.
'https://github.com/b[...]ce/objects_attrs.inv' converted to '...objects.txt' (plain).


>>> print(file_head('objects.txt', head=6))
# Sphinx inventory version 2
# Project: attrs
# Version: 17.2
# The remainder of this file is compressed using zlib.
attr.Attribute py:class 1 api.html#$ -
attr.Factory py:class 1 api.html#$ -

The URL provided MUST have the leading protocol specified (here, https://).

It is not necessary to locate the objects.inv file before running sphobjinv; for most Sphinx documentation sets, if you provide a URL to any page in the docs, it will automatically find and use the correct objects.inv:

>>> cli_run('sphobjinv convert plain -ou https://docs.python.org/3/library/urllib.error.html#urllib.error.URLError')

No inventory at provided URL.
Attempting "https://docs.python.org/3/library/urllib.error.html/objects.inv" ...
Attempting "https://docs.python.org/3/library/objects.inv" ...
Attempting "https://docs.python.org/3/objects.inv" ...
Remote inventory found.

Conversion completed.
'...objects.inv' converted to '...objects.txt' (plain).

sphobjinv only supports download of zlib-compressed objects.inv files by URL. Plaintext download by URL is unreliable, presumably due to encoding problems. If processing of JSON files by API URL is desirable, please submit an issue.

Usage

$ sphobjinv convert --help
usage: sphobjinv convert [-h] [-e | -c] [-o] [-q] [-u]
                         {zlib,plain,json} infile [outfile]

Convert intersphinx inventory to zlib-compressed, plaintext, or JSON formats.
...

Positional Arguments

mode

Conversion output format.

Must be one of plain, zlib, or json

infile

Path (or URL, if --url is specified) to file to be converted.

outfile

(Optional) Path to desired output file. Defaults to same directory and main file name as input file but with extension .inv/.txt/.json, as appropriate for the output format. A bare path is accepted here, using the default output file name/extension.

Flags

-h, --help

Display convert help message and exit.

-o, --overwrite

If the output file already exists, overwrite without prompting for confirmation.

-q, --quiet

Suppress all output to stdout, regardless of success or failure. Useful for scripting/automation. Implies --overwrite.

-u, --url

Treat infile as a URL for download.

-e, --expand

Expand any abbreviations in uri or dispname fields before writing to output; see here. Cannot be specified with --contract.

-c, --contract

Contract uri and dispname fields, if possible, before writing to output; see here. Cannot be specified with --expand.