Command-Line Usage: “suggest” Mode¶

The suggest subparser is used to query an inventory for objects fuzzy-matching a given search string. Fuzzy-matching is carried out via the fuzzywuzzy library, against the Restructured Text-like representation of each object exposed by SuperDataObj.as_rst:

>>> cli_run('sphobjinv suggest objects_attrs.inv instance')

:py:exception:`attr.exceptions.FrozenInstanceError`
:py:function:`attr.validators.instance_of`

The fuzzywuzzy match score and the index of the object within the inventory can be printed by passing the --score and --index options, respectively:

>>> cli_run('sphobjinv suggest objects_attrs.inv instance -s -i')  

  Name                                                  Score    Index
-----------------------------------------------------  -------  -------
:py:exception:`attr.exceptions.FrozenInstanceError`      90        9
:py:function:`attr.validators.instance_of`               90       23

If too few or too many matches are returned, the reporting threshold can be changed via --thresh:

>>> cli_run('sphobjinv suggest objects_attrs.inv instance -s -i -t 48')  

  Name                                                  Score    Index
-----------------------------------------------------  -------  -------
:py:exception:`attr.exceptions.FrozenInstanceError`      90        9
:py:function:`attr.validators.instance_of`               90       23
:std:doc:`license`                                       51       47
:py:function:`attr.filters.include`                      48       13

Remote objects.inv files can be retrieved for inspection by passing the --url flag:

>>> cli_run('sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/dev/sphobjinv/test/resource/objects_attrs.inv instance -u -t 48')  

Remote inventory found.

:py:exception:`attr.exceptions.FrozenInstanceError`
:py:function:`attr.validators.instance_of`
:std:doc:`license`
:py:function:`attr.filters.include`

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 suggest -u https://sphobjinv.readthedocs.io/en/v2.0rc1/cmdline.html compress')  

No inventory at provided URL.
Attempting "https://sphobjinv.readthedocs.io/en/v2.0rc1/cmdline.html/objects.inv" ...
Attempting "https://sphobjinv.readthedocs.io/en/v2.0rc1/objects.inv" ...
Remote inventory found.

:py:function:`sphobjinv.zlib.compress`
:py:function:`sphobjinv.zlib.decompress`

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 suggest --help', head=3)
usage: sphobjinv suggest [-h] [-a] [-i] [-s] [-t {0-100}] [-u] infile search

Fuzzy-search intersphinx inventory for desired object(s).

Positional Arguments

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

search¶: Search term for fuzzywuzzy matching

Flags

-h, --help¶: Display suggest help message and exit.

-a, --all¶: Display all search results without prompting, regardless of the number of hits. Otherwise, prompt if number of results exceeds sphobjinv.cmdline.SUGGEST_CONFIRM_LENGTH.

-i, --index¶: Display the index position within the Inventory.objects list for each search result returned.

-s, --score¶: Display the fuzzywuzzy match score for each search result returned.

-t, --thresh <#>¶: Change the fuzzywuzzy match quality threshold (0-100; higher values yield fewer results). Default is specified in sphobjinv.cmdline.DEF_THRESH.

-u, --url¶: Treat infile as a URL for download.