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
-
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
.
-
-e
,
--expand
¶
Expand any abbreviations in uri or dispname fields before writing to output; see here. Cannot be specified with
--contract
.