Command-Line Usage: “convert” Subcommand

The convert subcommand is used for all conversions of “version 2” Sphinx inventory files among plaintext, zlib-compressed, and (unique to sphobjinv) JSON formats. The sphobjinv CLI can read and write inventory data from local files in any of these three formats, as well as read the standard zlib-compressed format from files in remote locations (see --url).

As of v2.1, the sphobjinv CLI can also read/write inventories at stdin/stdout in the plaintext and JSON formats; see below.

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: 22.1
# The remainder of this file is compressed using zlib.
attr py:module 0 index.html#module-$ -
attr.VersionInfo 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 internet, 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/main/tests/resource/objects_attrs.inv')

Attempting https://github.com/bskinn/sphobjinv/raw/main/tests/resource/objects_attrs.inv ...
  ... 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: 22.1
# The remainder of this file is compressed using zlib.
attr py:module 0 index.html#module-$ -
attr.VersionInfo 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')

Attempting https://docs.python.org/3/library/urllib.error.html#urllib.error.URLError ...
  ... no recognized inventory.
Attempting "https://docs.python.org/3/library/urllib.error.html/objects.inv" ...
  ... HTTP error: 404 Not Found.
Attempting "https://docs.python.org/3/library/objects.inv" ...
  ... HTTP error: 404 Not Found.
Attempting "https://docs.python.org/3/objects.inv" ...
  ... 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.

New in version 2.1: The URL at which a remote inventory is found is now included in JSON output:

>>> cli_run('sphobjinv convert json -qu https://docs.python.org/3/ objects.json')

>>> data = json.loads(Path('objects.json').read_text())
>>> data["metadata"]["url"]
'https://docs.python.org/3/objects.inv'

New in version 2.1: JSON and plaintext inventories can now be read from stdin and written to stdout, by using the special value - in the invocation. E.g., to print to stdout:

>>> cli_run('sphobjinv co plain objects_attrs.inv -')
# Sphinx inventory version 2
# Project: attrs
# Version: 22.1
# The remainder of this file is compressed using zlib.
attr py:module 0 index.html#module-$ -
attr.VersionInfo py:class 1 api.html#$ -
attr._make.Attribute py:class -1 api.html#attrs.Attribute -
...

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.

If passed as -, sphobjinv will attempt import of a plaintext or JSON inventory from stdin (incompatible with --url).

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.

If passed as -, or if omitted when infile is passed as -, sphobjinv will emit plaintext or JSON (but not zlib-compressed) inventory contents to stdout.

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 status message output, regardless of success or failure. Useful for scripting/automation. Implies --overwrite.

-u, --url: Treat infile as a URL for download. Cannot be used when infile is passed as -.

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