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

Added 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'

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