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/dev/sphobjinv/test/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 download of JSON files by URL is desirable, please submit an issue.

Usage

>>> cli_run('sphobjinv convert --help', head=4)
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.