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:

$ 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:

$ 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:

$ 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:

$ sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/master/tests/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:

$ 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

$ sphobjinv suggest --help
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 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.