# Command-Line Usage: `sphobjinv suggest`

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

    180 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: 25.4

    180 objects in inventory.

    ------------------------------------------------

    3 results found at/above current threshold of 75.

      Name                                                   Score    Index
    ------------------------------------------------------  -------  -------
    :py:exception:`attr.exceptions.FrozenInstanceError`       90       24
    :py:exception:`attrs.exceptions.FrozenInstanceError`      90       94
    :py:function:`attrs.validators.instance_of`               90       127

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

    180 objects in inventory.

    ------------------------------------------------

    6 results found at/above current threshold of 48.

      Name                                                   Score    Index
    ------------------------------------------------------  -------  -------
    :py:exception:`attr.exceptions.FrozenInstanceError`       90       24
    :py:exception:`attrs.exceptions.FrozenInstanceError`      90       94
    :py:function:`attrs.validators.instance_of`               90       127
    :std:doc:`license`                                        51       167
    :py:function:`attr.define`                                48       17
    :py:function:`attrs.define`                               48       87

Remote objects.inv files can be retrieved for inspection by passing the `--url` flag:

    $ sphobjinv suggest https://sphobjinv.readthedocs.io/en/stable/objects.inv Inventory -u -t 85

    Attempting https://sphobjinv.readthedocs.io/en/stable/objects.inv ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/stable/objects.inv/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/stable/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/objects.inv" ...
      ... error attempting to retrieve URL.

    No inventory found!

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 ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/stable/cli/convert.html/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/stable/cli/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/stable/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/en/objects.inv" ...
      ... error attempting to retrieve URL.
    Attempting "https://sphobjinv.readthedocs.io/objects.inv" ...
      ... error attempting to retrieve URL.

    No inventory found!

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.

Added 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: 25.4

    180 objects in inventory.

    ------------------------------------------------

    18 results found at/above current threshold of 75.

      Name                                     Score
    ----------------------------------------  -------
    :py:function:`attr.get_run_validators`      90
    :py:function:`attr.set_run_validators`      90
    :py:function:`attr.validate`                90
    :py:module:`attr.validators`                90
    :py:function:`attrs.setters.validate`       90
    :py:function:`attrs.validate`               90
    :py:module:`attrs.validators`               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
    :py:function:`attrs.validators.not_`        90
    :py:function:`attrs.validators.or_`         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 `--url` is specified) to file to be searched.

  If passed as `-`, sphobjinv will attempt import of a plaintext or JSON inventory from `stdin`. This is incompatible with `--url`, and automatically enables `--all`.

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 for confirmation before displaying the entire result set if count exceeds 30.

-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). Current default threshold is 75.

-u, --url

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