Merge pull request #221 from bskinn/release-2.2

Merge v2.2 release to stable

Author: bskinn

.coveragerc

@@ -1,13 +1,14 @@
 [run]
-omit =
-    # Don't do coverage on test code
-    sphobjinv/test/*
-    tests.py
+source =
+    src
 
-    # Don't cover code in the env (Termux only?)
-    env/*
+omit =
+    # Don't worry about covering vendored libraries
+    src/sphobjinv/_vendored/*
 
 [report]
 exclude_lines =
     pragma: no cover
     ^\s*pass\s*$
+
+show_missing = True

.github/workflows/ci_tests.yml

@@ -4,7 +4,7 @@ on: push
 
 jobs:
   all_checks:
-    name: Run all tests, lints, etc. (Python 3.9)
+    name: Run all tests, lints, etc. (Python 3.10)
     runs-on: ubuntu-latest
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
 
@@ -15,7 +15,7 @@ jobs:
     - name: Install Python
       uses: actions/setup-python@v2
       with:
-        python-version: 3.9
+        python-version: '3.10'
 
     - name: Update pip & setuptools
       run: python -m pip install -U pip setuptools
@@ -32,9 +32,9 @@ jobs:
         make html
         mkdir scratch
 
-    - name: Run tests
+    - name: Run tests & report source coverage
       run: |
-        pytest --cov=src --testall --nonloc
+        pytest --cov --testall --nonloc
         tox -e sdist_install
 
     - name: Run doctests
@@ -59,7 +59,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python: ['3.6', '3.7', '3.8']
+        python: ['3.6', '3.7', '3.8', '3.9']
     if: "!contains(github.event.head_commit.message, '[skip ci]')"
 
     steps:
@@ -86,8 +86,7 @@ jobs:
         make html
         mkdir scratch
 
-    - name: Run tests
+    - name: Run tests & report source coverage
       run: |
-        pytest --cov=src --testall --nonloc
+        pytest --cov --testall --nonloc
         tox -e sdist_install
-      

.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+# See https://pre-commit.com for more information
+# See https://pre-commit.com/hooks.html for more hooks
+repos:
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: 'v3.2.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.1.0'
+    hooks:
+    -   id: black

.readthedocs.yml

@@ -14,7 +14,7 @@ formats: all
 
 # Python and requirements
 python:
-  version: 3.8
+  version: '3.8'
   install:
     - requirements: requirements-rtd.txt
     - method: pip

AUTHORS.md

@@ -11,13 +11,13 @@ hadn't yet been documented (that happened in [2018](https://github.com/sphinx-do
 and a fair bit of searching didn't turn up anything promising. 
 
 Once I dug into the Sphinx code to figure out how to zlib-decompress the object data, it was relatively straightforward
-to put together the initial v1.0 of `sphobjinv`, which could only (de)compress objects.inv files to/from plaintext.
+to put together the initial v1.0 of `sphobjinv`, which could only (de)compress `objects.inv` files to/from plaintext.
 As I started to use it regularly in my own documentation work, it became clear that there would be significant advantages
 from also implementing functionality to assist with object searches, especially in large documentation sets.
 Also, it seemed likely that a robust API for creation/manipulation of inventory contents would be useful, in order to
-assist with things like scraping a non-Sphinx website to generate an objects.inv for cross-referencing in other docs.
+assist with things like scraping a non-Sphinx website to generate an `objects.inv` for cross-referencing in other docs.
 This led to the current object-oriented API of `sphobjinv` v2.x.
 
 While there are [numerous](https://github.com/bskinn/sphobjinv/issues) possible enhancements to the project,
 I'm quite satisfied with its ease of use and usefulness, at least for my purposes, and thus consider it fully stable.
-I'm always glad to receive feature requests and (especially) bug reports, though.
+I'm always glad to receive feature requests and bug reports, though.

CHANGELOG.md

@@ -7,6 +7,51 @@ and this project strives to adhere to
 [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 
+### [2.2] - 2022-01-30
+
+#### 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.
+
+
+### [2.2b1] - 2021-12-23
+
+#### Removed
+
+  * Acceleration of the `suggest` functionality via use of `python-Levenshtein`
+    is no longer possible due to the vendoring of an early, MIT-licensed version
+    of `fuzzywuzzy`, as noted below. The `speedup` install extra is now obsolete,
+    and has been removed.
+
+#### Internal
+
+  * The `fuzzywuzzy` string matcher was vendored into the project from a point
+    in its development history before the `python-Levenshtein` dependency,
+    and its corresponding GPL encumbrance, was introduced.
+
+#### Administrative
+
+  * Project default branch migrated to `main` from `master`.
+
+  * Standard development Python version bumped to 3.10.
+
+  * Standard development Sphinx version bumped to 4.3.1.
+
+  * Active support for Python 3.11 added.
+
+
 ### [2.1] - 2021-04-14
 
 #### Added
@@ -246,4 +291,3 @@ and this project strives to adhere to
  * Programmatic conversion via API is available, but
    potentially buggy due to poor segregation of cmdline
    behaviors. This is to be fixed.
-

CONTRIBUTING.md

@@ -43,7 +43,7 @@ in whatever location you prefer. Any Python interpreter 3.6+ *should* work fine.
 I prefer to use `virtualenv` and create in `./env`:
 
 ```
-$ python3.9 -m virtualenv env --prompt="(sphobjinv) "
+$ python3.10 -m virtualenv env --prompt="sphobjinv"
 ```
 
 Activate the environment:
@@ -63,6 +63,12 @@ The next step is to upgrade/install the development requirements:
 (sphobjinv) $ pip install -r requirements-dev.txt
 ```
 
+Then, install the pre-commit hooks:
+
+```
+(sphobjinv) $ pre-commit install
+```
+
 Finally, you'll need to build the Sphinx docs,
 as some of the tests interact with them:
 
@@ -84,21 +90,21 @@ $ git checkout -b description-of-change
 ```
 
 This makes it a lot simpler to get your repo fork up to date
-after `master` receives further commits.
+after `main` receives further commits.
 
-To bring your fork's `master` up to date, you first need to
+To bring your fork's `main` up to date, you first need to
 add the main repo as a new git remote (one-time task):
 
 ```
 $ git remote add upstream https://github.com/bskinn/sphobjinv
 ```
 
-Then, any time you need to refresh the fork's master:
+Then, any time you need to refresh the fork's `main`:
 
 ```
 $ git fetch --all
-$ git checkout master
-$ git merge upstream/master  # (should merge without incident)
+$ git checkout main
+$ git merge upstream/main  # (should merge without incident)
 $ git push  # (should push to your fork without incident)
 ```
 
@@ -128,6 +134,9 @@ please go beyond this and add tests that check potential edge cases,
 bad/malformed/invalid inputs, etc. For bugfixes, add one or more
 focused regression tests that cover the bug behavior being fixed.
 
+PRs that add [xfail tests for existing bugs](https://blog.ganssle.io/articles/2021/11/pytest-xfail.html)
+are also welcomed.
+
 There are some situations where it may make sense to use a
 `# pragma: no cover` to ignore coverage on certain line(s) of code.
 Please start a discussion in the issue or PR comments before
@@ -138,7 +147,7 @@ configured for the project, it is **not** set up to be an everyday test runner.
 Instead, it's used to execute a 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.10
+working versions of all of Python 3.6 through 3.11
 installed and on `PATH` as `python3.6`, `python3.7`, 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
@@ -159,7 +168,7 @@ To run the lints locally, it's easiest to use `tox`:
 $ tox -e flake8
 ```
 
-In some limited circumstances, it may be necessary to add 
+In some limited circumstances, it may be necessary to add
 [`# noqa`](https://flake8.pycqa.org/en/stable/user/violations.html#in-line-ignoring-errors)
 or [`per_file_ignores`](https://flake8.pycqa.org/en/stable/user/options.html#cmdoption-flake8-per-file-ignores)
 exclusions to the `flake8` lints.
@@ -239,20 +248,20 @@ and the link validity checker 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.9,
+Github Actions runs the test suite on Linux for Python 3.6 through 3.10,
 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.
 
 The Azure Pipelines CI runs an extensive matrix of cross-platform and
 cross-Python-version tests, as well as numerous other checks.
 Due to its length, it is configured to run only on release branches
-and PRs to `master` or `stable`. It cannot be skipped.
+and PRs to `main` or `stable`. It cannot be skipped.
 
 
 ## CHANGELOG
 
-The project [`CHANGELOG`](https://github.com/bskinn/sphobjinv/blob/master/CHANGELOG.md)
+The project [`CHANGELOG`](https://github.com/bskinn/sphobjinv/blob/main/CHANGELOG.md)
 should be updated for the majority of contributions. No tooling is in place
 (e.g., [`towncrier`](https://github.com/twisted/towncrier)) for automated collation
 of news items into `CHANGELOG`;
@@ -278,4 +287,3 @@ you want to create, though, then don't use them.
 ## License
 
 All contributions will take on the MIT License of the project at large.
-

LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2021 Brian Skinn
+Copyright (c) 2016-2022 Brian Skinn
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.rst

@@ -7,7 +7,7 @@ sphobjinv: Manipulate and inspect Sphinx objects.inv files
     :alt: GitHub Workflow Status
     :target: https://github.com/bskinn/sphobjinv/actions
 
-.. image:: https://codecov.io/gh/bskinn/sphobjinv/branch/master/graph/badge.svg
+.. image:: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg
     :target: https://codecov.io/gh/bskinn/sphobjinv
 
 **Most Recent Stable Release:**
@@ -22,12 +22,19 @@ sphobjinv: Manipulate and inspect Sphinx objects.inv files
 .. image:: https://img.shields.io/readthedocs/sphobjinv/latest.svg
     :target: http://sphobjinv.readthedocs.io/en/latest/
 
+.. image:: https://badges.gitter.im/sphobjinv/community.svg
+   :alt: Join the chat at https://gitter.im/sphobjinv/community
+   :target: https://gitter.im/sphobjinv/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
+
 .. image:: https://img.shields.io/github/license/mashape/apistatus.svg
     :target: https://github.com/bskinn/sphobjinv/blob/stable/LICENSE.txt
 
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
     :target: https://github.com/psf/black
 
+.. image:: https://pepy.tech/badge/sphobjinv/month
+    :target: https://pepy.tech/project/sphobjinv?versions=2.1b1&versions=2.2b1&versions=2.2&versions=2.1&versions=2.0.1
+
 ----
 
 **Using Sphinx?**
@@ -47,15 +54,21 @@ to cross-reference into, and pass it to ``sphobjinv suggest``.
 
 For internal cross-references, locate ``objects.inv`` within ``build/html``::
 
-    $ sphobjinv suggest doc/build/html/objects.inv as_rst -st 50
-
-      Name                                                     Score
-    --------------------------------------------------------  -------
-    :py:method:`sphobjinv.data.SuperDataObj.as_rst`             60
-    :std:doc:`cli/implementation/parser`                        57
-    :py:module:`sphobjinv.cli.parser`                           50
-    :py:method:`sphobjinv.data.SuperDataObj.as_str`             50
-    :py:method:`sphobjinv.inventory.Inventory.objects_rst`      50
+    $ sphobjinv suggest doc/build/html/objects.inv as_rst -st 58
+
+      Name                                                Score
+    ---------------------------------------------------  -------
+    :py:property:`sphobjinv.data.SuperDataObj.as_rst`      60
+    :py:class:`sphobjinv.cli.parser.PrsConst`              59
+    :py:class:`sphobjinv.data.DataFields`                  59
+    :py:class:`sphobjinv.data.DataObjBytes`                59
+    :py:class:`sphobjinv.data.DataObjStr`                  59
+    :py:class:`sphobjinv.data.SuperDataObj`                59
+    :py:class:`sphobjinv.enum.HeaderFields`                59
+    :py:class:`sphobjinv.enum.SourceTypes`                 59
+    :py:function:`sphobjinv.fileops.writebytes`            59
+    :py:function:`sphobjinv.fileops.writejson`             59
+    :py:class:`sphobjinv.inventory.Inventory`              59
 
 .. end shell command
 
@@ -120,11 +133,11 @@ inventory creation/modification::
     >>> import sphobjinv as soi
     >>> inv = soi.Inventory('doc/build/html/objects.inv')
     >>> print(inv)
-    <Inventory (fname_zlib): sphobjinv v2.1, 205 objects>
+    <Inventory (fname_zlib): sphobjinv v2.2, 205 objects>
     >>> inv.project
     'sphobjinv'
     >>> inv.version
-    '2.1'
+    '2.2'
     >>> inv.objects[0]
     DataObjStr(name='sphobjinv.cli.core', domain='py', role='module', priority='0', uri='cli/implementation/core.html#module-$', dispname='-')
 
@@ -146,7 +159,7 @@ Source on `GitHub <https://github.com/bskinn/sphobjinv>`__.  Bug reports
 and feature requests are welcomed at the
 `Issues <https://github.com/bskinn/sphobjinv/issues>`__ page there.
 
-Copyright (c) Brian Skinn 2016-2021
+Copyright (c) Brian Skinn 2016-2022
 
-License: The MIT License. See `LICENSE.txt <https://github.com/bskinn/sphobjinv/blob/master/LICENSE.txt>`__
+License: The MIT License. See `LICENSE.txt <https://github.com/bskinn/sphobjinv/blob/main/LICENSE.txt>`__
 for full license terms.