1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
.. Description of suggest commandline usage
Command-Line Usage: "suggest" Subcommand
========================================
.. program:: sphobjinv suggest
The |cour|\ suggest\ |/cour| 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 :attr:`SuperDataObj.as_rst <sphobjinv.data.SuperDataObj.as_rst>`:
.. command-output:: sphobjinv suggest objects_attrs.inv instance
:cwd: /../../tests/resource
The |fuzzywuzzy|_ match score and the index of the object within the inventory can
be printed by passing the :option:`--score` and :option:`--index` options,
respectively:
.. command-output:: sphobjinv suggest objects_attrs.inv instance -s -i
:cwd: /../../tests/resource
If too few or too many matches are returned, the reporting threshold can be changed
via :option:`--thresh`:
.. command-output:: sphobjinv suggest objects_attrs.inv instance -s -i -t 48
:cwd: /../../tests/resource
Remote |objects.inv| files can be retrieved for inspection by passing the
:option:`--url` flag:
.. command-output:: sphobjinv suggest https://github.com/bskinn/sphobjinv/raw/main/tests/resource/objects_attrs.inv instance -u -t 48
:cwd: /../../tests/resource
The URL provided **MUST** have the leading protocol specified (here,
|cour|\ https\ ://\ |/cour|).
It is usually not necessary to locate the |objects.inv| file before running |soi|;
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|:
.. command-output:: sphobjinv suggest -u https://sphobjinv.readthedocs.io/en/stable/cli/convert.html compress
:cwd: /../../tests/resource
|soi| 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 <https://github.com/bskinn/sphobjinv/issues>`__.
.. versionadded:: 2.1
The |soi| CLI can now read JSON and plaintext inventories from ``stdin``
by passing the special ``-`` argument for `infile`:
.. command-output:: sphobjinv suggest -s - valid < objects_attrs.txt
:cwd: /../../tests/resource
:shell:
**Usage**
.. command-output:: sphobjinv suggest --help
:ellipsis: 4
**Positional Arguments**
.. option:: infile
Path (or URL, if :option:`--url` is specified) to file to be searched.
If passed as ``-``, |soi| will attempt import of a plaintext or JSON
inventory from ``stdin``. This is incompatible with :option:`--url`,
and automatically enables :option:`--all`.
.. option:: search
Search term for |fuzzywuzzy|_ matching.
**Flags**
.. option:: -h, --help
Display `suggest` help message and exit.
.. option:: -a, --all
Display all search results without prompting, regardless of the number of hits.
Otherwise, prompt if number of results exceeds
:attr:`~sphobjinv.cli.parser.PrsConst.SUGGEST_CONFIRM_LENGTH`.
.. option:: -i, --index
Display the index position within the
:attr:`Inventory.objects <sphobjinv.inventory.Inventory.objects>` list
for each search result returned.
.. option:: -s, --score
Display the |fuzzywuzzy|_ match score for each search result returned.
.. option:: -t, --thresh <#>
Change the |fuzzywuzzy|_ match quality threshold (0-100; higher values
yield fewer results). Default is specified in
:attr:`~sphobjinv.cli.parser.PrsConst.DEF_THRESH`.
.. option:: -u, --url
Treat :option:`infile` as a URL for download. Cannot be used when
:option:`infile` is passed as ``-``.
|
