Command-Line Usage: “suggest” Subcommand
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
------------------------------------------------
Cannot infer intersphinx_mapping from a local objects.inv.
------------------------------------------------
Project: attrs
Version: 22.1
129 objects in inventory.
------------------------------------------------
3 results found at/above current threshold of 75.
:py:exception:`attr.exceptions.FrozenInstanceError`
:py:exception:`attrs.exceptions.FrozenInstanceError`
:py:function:`attrs.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
------------------------------------------------
Cannot infer intersphinx_mapping from a local objects.inv.
------------------------------------------------
Project: attrs
Version: 22.1
129 objects in inventory.
------------------------------------------------
3 results found at/above current threshold of 75.
Name Score Index
------------------------------------------------------ ------- -------
:py:exception:`attr.exceptions.FrozenInstanceError` 90 26
:py:exception:`attrs.exceptions.FrozenInstanceError` 90 56
:py:function:`attrs.validators.instance_of` 90 82
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
------------------------------------------------
Cannot infer intersphinx_mapping from a local objects.inv.
------------------------------------------------
Project: attrs
Version: 22.1
129 objects in inventory.
------------------------------------------------
6 results found at/above current threshold of 48.
Name Score Index
------------------------------------------------------ ------- -------
:py:exception:`attr.exceptions.FrozenInstanceError` 90 26
:py:exception:`attrs.exceptions.FrozenInstanceError` 90 56
:py:function:`attrs.validators.instance_of` 90 82
:std:doc:`license` 51 115
:py:function:`attr.define` 48 21
:py:function:`attrs.define` 48 50
Remote objects.inv files can be retrieved for inspection by passing the
--url flag:
$ sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/main/tests/resource/objects_attrs.inv instance -u -t 48
Attempting https://github.com/bskinn/sphobjinv/raw/main/tests/resource/objects_attrs.inv ...
... inventory found.
------------------------------------------------
Cannot infer intersphinx_mapping for this docset using the provided input URL.
------------------------------------------------
Project: attrs
Version: 22.1
129 objects in inventory.
------------------------------------------------
6 results found at/above current threshold of 48.
:py:exception:`attr.exceptions.FrozenInstanceError`
:py:exception:`attrs.exceptions.FrozenInstanceError`
:py:function:`attrs.validators.instance_of`
:std:doc:`license`
:py:function:`attr.define`
:py:function:`attrs.define`
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/stable/cli/convert.html compress
Attempting https://sphobjinv.readthedocs.io/en/stable/cli/convert.html ...
... no recognized inventory.
Attempting "https://sphobjinv.readthedocs.io/en/stable/cli/convert.html/objects.inv" ...
... HTTP error: 404 Not Found.
Attempting "https://sphobjinv.readthedocs.io/en/stable/cli/objects.inv" ...
... HTTP error: 404 Not Found.
Attempting "https://sphobjinv.readthedocs.io/en/stable/objects.inv" ...
... inventory found.
------------------------------------------------
The intersphinx_mapping for this docset is LIKELY:
(https://sphobjinv.readthedocs.io/en/stable/, None)
------------------------------------------------
Project: sphobjinv
Version: 2.3
220 objects in inventory.
------------------------------------------------
2 results found at/above current threshold of 75.
: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
------------------------------------------------
Cannot infer intersphinx_mapping from a local objects.inv.
------------------------------------------------
Project: attrs
Version: 22.1
129 objects in inventory.
------------------------------------------------
14 results found at/above current threshold of 75.
Name Score
---------------------------------------- -------
:py:function:`attr.attr.validate` 90
:py:function:`attr.get_run_validators` 90
:py:function:`attr.set_run_validators` 90
:py:function:`attrs.setters.validate` 90
:py:function:`attrs.validate` 90
:py:function:`attrs.validators.and_` 90
:py:function:`attrs.validators.ge` 90
:py:function:`attrs.validators.gt` 90
:py:function:`attrs.validators.in_` 90
:py:function:`attrs.validators.le` 90
:py:function:`attrs.validators.lt` 90
:std:label:`api_validators` 90
:std:label:`examples_validators` 90
:std:label:`validators` 90
Usage
$ sphobjinv suggest --help
usage: sphobjinv suggest [-h] [-a] [-p] [-i] [-s] [-t {0-100}] [-u]
infile search
Fuzzy-search intersphinx inventory for desired object(s).
...
Positional Arguments
- infile
Path (or URL, if
--urlis specified) to file to be searched.If passed as
-, sphobjinv will attempt import of a plaintext or JSON inventory fromstdin. This is incompatible with--url, and automatically enables--all.
- search
Search term for
fuzzywuzzymatching.
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.objectslist for each search result returned.
- -s, --score
Display the
fuzzywuzzymatch score for each search result returned.
- -t, --thresh <#>
Change the
fuzzywuzzymatch quality threshold (0-100; higher values yield fewer results). Default is specified inDEF_THRESH.