Sphobjinv

Tests

* Update test machinery for the shell examples in the README, downstream of
the conversion to Markdown ([289]).

Administrative

* Added formal support for Python 3.12.

* Removed formal support for Python 3.7, which is end-of-life.

* Bump `checkout` and `setup-python` GitHub Actions versions ([289]).

* Convert README from reST to Markdown ([289], fixes [287]).

* Fix some broken/redirecting docs links ([289]).

* Adjust `flake8` configuration to account for some new lint warnings/errors
([289]).

Changed

* The printout of the inferred `intersphinx_mapping` item for inventories
retrieved by URL (`--url`) in the 'suggest' CLI mode is now relocated to
fall immediately below the inventory-search output. It also now is displayed
even if no objects in the `objects.inv` satisfy the score threshold.
([262](https://github.com/bskinn/sphobjinv/issues/262))

* The 'suggest' CLI mode output now includes dividers for improved
readability.

Tests

* The plaintext `tests/resource/objects_attrs.txt` was converted to POSIX EOLs
and declared as binary to git, in order to provide a consistent state for
sdist packaging, regardless of platform (POSIX vs Windows).

* As a result, it was necessary to modify the `scratch_path` fixture to
"`unix2dos`" this file on Windows systems, in order to provide a
consistent test state.

* Similarly, the `decomp_cmp_test` fixture was modified to "`unix2dos`" the
`objects_attrs.txt` resource before comparisons, again in order to provide
a consistent reference artifact. Implementing required direct manipulation
of the bytes contents of the file, instead of the `filecmp.cmp` method
that had been used previously.

* The README doctests and shell tests have been removed from the default
pytest suite. They must be explicitly opted-in with the `--readme` and
`--doctest-glob="README.rst"` flags to pytest.

* A new job, `readme`, has been added to the `aux_tests` stage of the Azure
Pipelines CI to run these tests for PRs and release branches.

* The constraint for `pytest-check` was bumped to `>=1.1.2` and all uses of
the `check` fixture were revised from `with check.check(...):` to
`with check(...):`. ([265](https://github.com/bskinn/sphobjinv/issues/265))

* Azure Pipelines now has Python 3.11 available for all of Ubuntu, Windows and
MacOS, so it was added to the core text matrix for all platforms.

* A new CI job was created on Azure Pipelines that creates an sdist from the
current project, extracts it into a sandboxed environment, installs the dev
dependencies, and runs the pytest suite (`azure-sdisttest.yml`).

* All uses of `pytest-check` were updated to use the
[v1.1.2 syntax](https://github.com/okken/pytest-check/blob/main/changelog.md#110---2022-nov-21)
(`check` fixture, or `from pytest_check import check`).

Internal

* The `sys.exit()` in the case of no objects falling above the 'suggest'
search threshold was refactored into the main `do_suggest()` body, to
minimize the surprise of an `exit()` call coming in a subfunction.
([263](https://github.com/bskinn/sphobjinv/issues/263))

Packaging

* `MANIFEST.in` was revised in order to provide a testable (`pytest --nonloc`)
sdist, in order to streamline packaging of `sphobjinv` for conda-forge.
(Thanks very much to [anjos](https://github.com/anjos) for getting the
recipes for `sphobjinv` and its dependencies in place! See
[264](https://github.com/bskinn/sphobjinv/issues/264).)

Administrative

* `sphobjinv` is now available via conda-forge! A note was added to the docs
to indicate this.

* The version bump on `pytest-check` no longer permits the use of Python 3.6
in CI. As Python 3.6 is nearly a year beyond EOL, this seems a reasonable
time to officially drop support for it. `python_requires` will still be at
`>=3.6` for now; it *should* still work for 3.6...but, no guarantees.

* The hook versions for `pre-commit-hooks`, `black`, and `pyproject-fmt` were
updated to v4.3, v22.10, and v0.3.5, respectively.

* `CONTENT_LICENSE.txt` was created, to specifically house the full
content/documentation license information.

* `LICENSE.txt` was revised to only hold the MIT License for the code,
primarily so that Github's automatic systems will recognize the project as
MIT licensed.

* Caching of pip downloads was added to all of the Azure Pipelines jobs.

* The version constraint for `pytest-check` was raised to `>=1.1.2`.

* A temporary upper bound was placed on the `flake8` version (now `>=5,<6`,
instead of `>=5`) to avoid pip resolver failures likely due to conflicts
with constraints declared by plugins.

* The older versions of `jsonschema` tested in the `tox` matrix were
streamlined down to 3.0 (`==3.0`), 3.x (`<4`), 4.0 (`<4.1`) and 4.8
(`<4.9`).

* The pin of `sphinx-issues==0.4.0` in the `tox` matrix was removed, to match
the unpinned package in the `requirements-xxx.txt` files.

Added

* The CLI now prints the project name and version for the `objects.inv` as
part of the 'suggest' mode output.

* The CLI now prints an inferred `intersphinx_mapping` entry for a remote
docset as part of the 'suggest' mode output, where such inference is
possible. The output from this mapping inference was added to the relevant
tests, and a couple of unit tests on some basic pieces of functionality were
written. ([149](https://github.com/bskinn/sphobjinv/issues/149))

* The CLI now provides considerably more information about what is happening
with the URLs it checks when trying to retrieve a remote inventory.
([99](https://github.com/bskinn/sphobjinv/issues/99), plus more)

* CLI 'suggest' results output now displays more information about
the total number of objects in the inventory, the search score threshold,
and the number of results falling at/above that threshold.
([232](https://github.com/bskinn/sphobjinv/issues/232))

* A new CLI option, `-p`/`--paginate`, enables paging of the results from the
`suggest` feature. ([70](https://github.com/bskinn/sphobjinv/issues/70))

Fixed

* The regex for parsing object lines from decompressed inventories now
correctly processes `{role}` values that contain internal colons.

* CLI corner case where options are passed but no subparser is specified
now results in a clean error-exit, instead of an exception.
([239](https://github.com/bskinn/sphobjinv/issues/239))

Documentation

* Updated doctests to reflect the new v22.1 attrs `objects.inv` used for
demonstration purposes.

* Updated `syntax.rst` to indicate that the `{role}` in an inventory object
MAY contain a colon.

* Added new 'CLI implementation' pages for the new modules, downstream of the
refactoring of the CLI 'convert' and 'suggest' code.

* Revised the intro paragraph of the 'CLI usage' page to more clearly emphasize
the two CLI subcommands and the links to their respective docs pages.

* Fixed a mistake in the CLI help info for the `--url` argument to `convert`.

Tests

* Various tests were updated to reflect the contents of the new v22.1 attrs
`objects.inv` introduced to replace the previous v17.2 inventory.

* A modern Sphinx `objects.inv` (v6.0.0b) was added to `tests/resource` as
`objects_sphinx.inv`, and the previous v1.6.6 was renamed to
`objects_sphinx_1_6_6.inv`.

* The 'valid objects' test cases were updated to reflect the possibility for a
colon within `{role}`:

* The colon-within-`{role}` test case was moved from 'invalid' to 'valid'.

* The colon-within-`{domain}` test case was also moved from 'invalid' to
'valid', but with an annotation added to indicate that it's not actually
viable---it will actually be interpreted incorrectly, with the first
portion of the colon-containing `{domain}` imported as `{domain}`, and the
remainder imported as part of `{role}`.

Internal

* Refactor CLI code to place the 'convert' and 'suggest' implementations in
their own modules.

* Refactor CLI 'suggest' code to the main `do_suggest()` function and a
handful of sub-functions.

* Rename the `log_print()` CLI helper function to the more-descriptive
`print_stderr()`.

* Bump development Sphinx version to v5.3.

* Bump flake8 version to >=5, due to the absorption of flake8-colors
colorization functionality. The flake8/tox config was updated accordingly.

* Bump pre-commit black hook to v22.3.0.

* Remove PyPy and Python 3.6 from Azure Pipelines test matrix.

* Revise `__version__` retrieval in `setup.py` to use an intermediate
dictionary with `exec()`.

* Update `setup.cfg` to use `license_files`, instead of the deprecated
`license_file`.

Administrative

* Apply CC BY 4.0 to documentation and docstrings and update project files to
reflect.

Fixed

* UnicodeDecodeErrors are ignored within the vendored `fuzzywuzzy` package
during `suggest` operations, using the `errors=replace` mode within
bytes.decode().

* This misbehavior emerged after vendoring `fuzzywuzzy`, suggesting that
it was a bug fixed later on in that project's development, after the
point from which it was vendored.

* This change may alter `suggest` behavior for those inventory objects with
pathological characters. But, given their rarity, user experience is not
expected to be noticeably affected.

Internal

* The `pyproject-fmt` formatted was added as a pre-commit hook.

* The `flake8-raise` plugin was added to the linting suite.

Testing

* A smoke test for error-free `suggest` execution was added for all of the
inventory files in `tests/resource`.

Internal

* The `benchmarks.py` file within the vendored version of `fuzzywuzzy`
was removed. This *should* have no effect on `sphobjinv` functionality.
* Per [223](https://github.com/bskinn/sphobjinv/issues/223), the
Python 2 code within `benchmarks.py` breaks a full-source compilation
done as part of an RPM packaging workflow.

Administrative

* The project documentation has been updated to reflect the deprecation
of the `python-Levenshtein` speedup.

* `pre-commit` has been added to the project, primarily to automate
`black` code formatting on every commit.

* The default trailing-whitespace, end-of-file, YAML syntax, and
large-file-prevention hooks have also been added.

Internal

* `sphinx-removed-in` was added as a dev and RTD dependency, to provide
the `versionremoved` Sphinx directive.