Merge pull request #271 from bskinn/release-2.3.1

Merge v2.3.1 to `stable`

Author: bskinn

.gitattributes

@@ -1,2 +1,2 @@
 tests/resource/objects_mkdoc_zlib0.inv binary
-
+tests/resource/objects_attrs.txt binary

.github/workflows/ci_tests.yml

@@ -63,7 +63,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.6', '3.7', '3.8', '3.9', '3.11']
+        python: ['3.7', '3.8', '3.9', '3.11']
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
 
     steps:

.pre-commit-config.yaml

@@ -2,17 +2,17 @@
 # See https://pre-commit.com/hooks.html for more hooks
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: 'v3.2.0'
+    rev: 'v4.3.0'
     hooks:
     -   id: trailing-whitespace
     -   id: end-of-file-fixer
     -   id: check-yaml
     -   id: check-added-large-files
 -   repo: https://github.com/psf/black
-    rev: '22.3.0'
+    rev: '22.10.0'
     hooks:
     -   id: black
 -   repo: https://github.com/tox-dev/pyproject-fmt
-    rev: '0.3.2'
+    rev: '0.3.5'
     hooks:
     -   id: pyproject-fmt

CHANGELOG.md

@@ -7,6 +7,108 @@ and this project strives to adhere to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 
+### [2.3.1] - 2022-11-29
+
+#### 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.
+
+
 ### [2.3] - 2022-11-08
 
 #### Added
@@ -24,6 +126,11 @@ and this project strives to adhere to
     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))
 
@@ -61,7 +168,8 @@ and this project strives to adhere to
     `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 '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'.
 
@@ -105,12 +213,6 @@ and this project strives to adhere to
 
 ### [2.2.2] - 2022-03-22
 
-#### Changed
-
-  * 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.
-
 #### Fixed
 
   * UnicodeDecodeErrors are ignored within the vendored `fuzzywuzzy` package

CONTENT_LICENSE.txt

@@ -0,0 +1,4 @@
+The sphobjinv documentation (including docstrings and README) is licensed under
+a Creative Commons Attribution 4.0 International License (CC-BY).
+
+See http://creativecommons.org/licenses/by/4.0/.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-Welcome!
+Welcome!  <!-- omit in toc -->
 --------
 
 Thanks for your interest in contributing to `sphobjinv`!
@@ -10,7 +10,7 @@ If you have any questions, please drop me a line on Twitter
 [issue](https://github.com/bskinn/sphobjinv/issues).
 
 
-Table of Contents
+Table of Contents <!-- omit in toc -->
 -----------------
 
 <!--TOC-->
@@ -23,7 +23,7 @@ Table of Contents
 - [Documentation](#documentation)
 - [Continuous Integration](#continuous-integration)
 - [CHANGELOG](#changelog)
-- [Issue & PR Templates](#issue--pr-templates)
+- [Issue and PR Templates](#issue-and-pr-templates)
 - [License](#license)
 
 <!--TOC-->
@@ -38,7 +38,7 @@ $ git clone https://github.com/{you}/sphobjinv
 ```
 
 Then, create a virtual environment for the project, in whatever location you
-prefer. Any Python interpreter 3.6+ *should* work fine.
+prefer. Any Python interpreter 3.7+ *should* work fine.
 
 I prefer to use `virtualenv` and create in `./env`:
 
@@ -153,8 +153,8 @@ Note that while [`tox`](https://tox.wiki/en/latest/) *is* configured for the
 project, it is **not** set up to be an everyday test runner. Instead, it's used
 to execute an extensive matrix of test environments checking for the
 compatibility of different Python and dependency versions. You can run it if you
-want, but you'll need working versions of all of Python 3.6 through 3.11
-installed and on `PATH` as `python3.6`, `python3.7`, etc. The nonlocal test
+want, but you'll need working versions of all of Python 3.7 through 3.11
+installed and on `PATH` as `python3.7`, `python3.8`, etc. The nonlocal test
 suite is run for each `tox` environment, so it's best to use at most two
 parallel sub-processes to avoid oversaturating your network bandwidth; e.g.:
 
@@ -250,7 +250,7 @@ with `make linkcheck`.
 Both Github Actions and Azure Pipelines are set up for the project, and should
 run on any forks of the repository.
 
-Github Actions runs the test suite on Linux for Python 3.6 through 3.11, as well
+Github Actions runs the test suite on Linux for Python 3.7 through 3.11, as well
 as the `flake8` lints and the Sphinx doctests and link-validity testing, and is
 configured to run on all commits. The workflow can be skipped per-commit by
 including `[skip ci]` in the commit message.
@@ -279,7 +279,7 @@ settings, etc.) may also warrant a `CHANGELOG` bullet, depending on the
 situation. When in doubt, ask!
 
 
-## Issue & PR Templates
+## Issue and PR Templates
 
 I've set up the project with a PR template and a couple of issue templates, to
 hopefully make it easier to provide all the information needed to act on code
@@ -290,4 +290,4 @@ issue/PR you want to create, though, then don't use them.
 ## License
 
 All code and documentation contributions will respectively take on the MIT
-License and CC-BY 4.0 license of the project at large.
+License and CC BY 4.0 license of the project at large.

LICENSE.txt

@@ -1,16 +1,3 @@
-The sphobjinv documentation (including docstrings) is licensed under a Creative
-Commons Attribution 4.0 International License (CC-BY).
-
-See http://creativecommons.org/licenses/by/4.0/.
-
-
-The sphobjinv codebase is released under the MIT License, the text of which is
-included below.
-
-
-====================================================================================
-
-
 The MIT License (MIT)
 
 Copyright (c) 2016-2022 Brian Skinn and community contributors

MANIFEST.in

@@ -1 +1,15 @@
-include AUTHORS.md CHANGELOG.md CONTRIBUTING.md LICENSE.txt pyproject.toml README.rst
+include AUTHORS.md CHANGELOG.md CONTRIBUTING.md LICENSE.txt pyproject.toml
+include README.rst requirements-dev.txt requirements-flake8.txt tox.ini
+
+graft src/sphobjinv/_vendored/fuzzywuzzy
+
+graft doc/source
+include doc/make.bat doc/Makefile
+
+include conftest.py
+graft tests
+prune tests/resource
+include tests/resource/objects_attrs* tests/resource/objects_sarge*
+
+global-exclude __pycache__/*
+prune **/*.egg-info

README.rst

@@ -33,7 +33,7 @@ sphobjinv: Manipulate and inspect Sphinx objects.inv files
     :target: https://github.com/psf/black
 
 .. image:: https://pepy.tech/badge/sphobjinv/month
-    :target: https://pepy.tech/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3
+    :target: https://pepy.tech/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1
 
 ----
 
@@ -57,14 +57,21 @@ For internal cross-references, locate ``objects.inv`` within ``build/html``::
 
     $ sphobjinv suggest doc/build/html/objects.inv as_rst -st 58
 
+    ------------------------------------------------
+
+    Cannot infer intersphinx_mapping from a local objects.inv.
+
+    ------------------------------------------------
+
     Project: sphobjinv
     Version: 2.3
 
-    219 objects in inventory.
+    220 objects in inventory.
+
+    ------------------------------------------------
 
     11 results found at/above current threshold of 58.
 
-    Cannot infer intersphinx_mapping from a local objects.inv.
 
       Name                                                Score
     ---------------------------------------------------  -------
@@ -103,16 +110,22 @@ cross-reference the ``linspace`` function from numpy (see
     Attempting "https://numpy.org/doc/1.23/objects.inv" ...
       ... inventory found.
 
+    ------------------------------------------------
+
+    The intersphinx_mapping for this docset is LIKELY:
+
+      (https://numpy.org/doc/1.23/, None)
+
+    ------------------------------------------------
+
     Project: NumPy
     Version: 1.23
 
     8074 objects in inventory.
 
-    8 results found at/above current threshold of 75.
-
-    The intersphinx_mapping for this docset is LIKELY:
+    ------------------------------------------------
 
-      (https://numpy.org/doc/1.23/, None)
+    8 results found at/above current threshold of 75.
 
 
       Name                                                           Score
@@ -157,7 +170,7 @@ inventory creation/modification::
     >>> import sphobjinv as soi
     >>> inv = soi.Inventory('doc/build/html/objects.inv')
     >>> print(inv)
-    <Inventory (fname_zlib): sphobjinv v2.3, 219 objects>
+    <Inventory (fname_zlib): sphobjinv v2.3, 220 objects>
     >>> inv.project
     'sphobjinv'
     >>> inv.version
@@ -185,7 +198,8 @@ and feature requests are welcomed at the
 
 Copyright (c) Brian Skinn 2016-2022
 
-The ``sphobjinv`` documentation (including docstrings) is licensed under a
+The ``sphobjinv`` documentation (including docstrings and README) is licensed
+under a
 `Creative Commons Attribution 4.0 International License <http://creativecommons.org/licenses/by/4.0/>`__
 (CC-BY). The ``sphobjinv`` codebase is released under the
 `MIT License <https://opensource.org/licenses/MIT>`__. See

azure-coretest.yml

@@ -1,3 +1,6 @@
+# Caching implemented as per
+# https://stackoverflow.com/a/70297887/4376000
+
 parameters:
   pythons: []
   platforms: []
@@ -15,6 +18,7 @@ jobs:
           image: 'macOS-latest'
         ${{ if notIn(platform, 'macOs', 'linux', 'windows') }}:
           image: 'Ubuntu-latest'
+        pip_cache_dir: $(Pipeline.Workspace)/.pip
 
       pool:
         vmImage: $[ variables.image ]
@@ -26,6 +30,14 @@ jobs:
           architecture: 'x64'
         displayName: Use cached ${{ coalesce(python.value.name, python.key) }} for tests.
 
+      - task: Cache@2
+        inputs:
+          key: 'pip | "$(Agent.OS)" | requirements-dev.txt | requirements-flake8.txt'
+          restoreKeys: |
+            pip | "$(Agent.OS)"
+          path: $(pip_cache_dir)
+        displayName: Cache pip
+
       - script: pip install -U --force-reinstall -r requirements-ci.txt
         displayName: Install CI requirements