Command-Line Usage: “suggest” Mode

The suggest subcommand 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 usually 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.

New in version 2.1: The sphobjinv CLI can now read JSON and plaintext inventories from stdin by passing the special - argument for infile:

$ sphobjinv suggest -s - valid < objects_attrs.txt
 
 
  Name                                     Score 
----------------------------------------  -------
:py:function:`attr.get_run_validators`      90   
:py:function:`attr.set_run_validators`      90   
:py:function:`attr.validate`                90   
:py:function:`attr.validators.and_`         90   
:py:function:`attr.validators.in_`          90   
:std:label:`api_validators`                 90   
:std:label:`examples_validators`            90

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

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

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

-u, --url

Treat infile as a URL for download. Cannot be used when infile is passed as -.