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 fromstdin
(incompatible with--url
).
-
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
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 inDEF_THRESH
.