Textconv previously 307

.coveragerc

@@ -5,6 +5,8 @@ source =
 omit =
     # Don't worry about covering vendored libraries
     src/sphobjinv/_vendored/*
+    setup.py
+    conftest.py
 
 [report]
 exclude_lines =

.github/workflows/all_core_tests.yml

@@ -12,16 +12,19 @@ jobs:
       cancel-in-progress: true
     strategy:
       matrix:
-        os: ['ubuntu-latest', 'windows-latest']
-
+        os:
+          - windows-latest
+          - ubuntu-latest
+        python-version:
+          - '3.12'
     steps:
     - name: Check out repo
       uses: actions/checkout@v4
 
     - name: Install Python
       uses: actions/setup-python@v5
       with:
-        python-version: '3.12'
+        python-version: "${{ matrix.python-version }}"
         cache: 'pip'
         cache-dependency-path: requirements-ci.txt
 
@@ -43,11 +46,18 @@ jobs:
     - name: Run tests & report source coverage
       run: |
         pytest --cov --testall --nonloc
+        coverage xml -o coverage-service.xml
 
     - name: Submit to Codecov if Linux, ready status, and main/stable
       if: ${{ matrix.os == 'ubuntu-latest' && !github.event.pull_request.draft && (github.event.pull_request.base.ref == 'main' || github.event.pull_request.base.ref == 'stable') }}
-      run: |
-        coverage xml -o coverage-service.xml
-        curl -Os https://cli.codecov.io/latest/linux/codecov
-        chmod +x codecov
-        ./codecov --verbose upload-process --fail-on-error -t ${{ secrets.CODECOV_TOKEN }} -n 'service'-${{ github.run_id }} -F service -f coverage-service.xml
+      uses: codecov/[email protected]
+      with:
+        name: 'service'-${{ github.run_id }}
+        token: ${{ secrets.CODECOV_TOKEN }}
+        slug: bskinn/sphobjinv
+        os: linux
+        flags: unittests
+        files: ./coverage.xml
+        env_vars: OS,PYTHON
+        fail_ci_if_error: true
+        verbose: true

CONTRIBUTING.md

@@ -72,7 +72,6 @@ interact with them:
 (sphobjinv) doc $ make html
 ```
 
-
 ## Working with git
 
 There's no way I can fit a whole git tutorial in here, so this just highlights a
@@ -150,6 +149,40 @@ e.g.:
 $ tox -rp2
 ```
 
+
+### pyenv and tox
+
+Contributors are **not expected** to do exhaustive testing on all
+supported py interpreters, leave that to the CI. Not saying can't.
+
+Assumes familiarity with pyenv and shims already installed for various
+py interpreters.
+
+Notable pyenv commands
+
+```bash
+pyenv version
+pyenv versions --bare
+```
+
+Gets the active pyenv version and get all installed pyenv versions respectively.
+
+To configure pyenv within the `.tox/` folder.
+
+```bash
+pyenv versions --bare > .tox/.python-version
+```
+
+Within the package base folder only one py interpreter is available. 
+
+Run tox for py39
+
+```bash
+cd .tox; PYTHONPATH=../ tox --root=.. -c ../tox.ini \
+-e py39-sphx_latest-attrs_latest-jsch_latest --workdir=.; cd - &>/dev/null
+```
+
+
 ## Code Autoformatting
 
 The project is set up with a `tox` environment to blacken the codebase; run with:

README.md

@@ -155,7 +155,7 @@ inventory creation/modification:
 >>> import sphobjinv as soi
 >>> inv = soi.Inventory('doc/build/html/objects.inv')
 >>> print(inv)
-<Inventory (fname_zlib): sphobjinv v2.3, 220 objects>
+<Inventory (fname_zlib): sphobjinv v2.3, ... objects>
 >>> inv.project
 'sphobjinv'
 >>> inv.version

conftest.py

@@ -45,6 +45,7 @@
 from sphinx.util.inventory import InventoryFile as IFile
 
 import sphobjinv as soi
+from tests.enums import Entrypoints
 
 
 def pytest_addoption(parser):
@@ -233,21 +234,32 @@ def sphinx_version():
 @pytest.fixture()  # Must be function scope since uses monkeypatch
 def run_cmdline_test(monkeypatch):
     """Return function to perform command line exit code test."""
-    from sphobjinv.cli.core import main
 
-    def func(arglist, *, expect=0):  # , suffix=None):
+    def func(arglist, *, expect=0, prog: Entrypoints = Entrypoints.SOI):
         """Perform the CLI exit-code test."""
 
         # Assemble execution arguments
-        runargs = ["sphobjinv"]
+        assert isinstance(prog, Entrypoints)
+        runargs = []
+        if prog == Entrypoints.SOI:
+            from sphobjinv.cli.core import main
+
+            ep_fcn = main
+            runargs.append(Entrypoints.SOI.value)
+        else:
+            from sphobjinv.cli.core_textconv import main as main_textconv
+
+            ep_fcn = main_textconv
+            runargs.append(Entrypoints.SOI_TEXTCONV.value)
+
         runargs.extend(str(a) for a in arglist)
 
         # Mock sys.argv, run main, and restore sys.argv
         with monkeypatch.context() as m:
             m.setattr(sys, "argv", runargs)
 
             try:
-                main()
+                ep_fcn()
             except SystemExit as e:
                 retcode = e.args[0]
                 ok = True

doc/source/cli/git_diff.rst

@@ -0,0 +1,160 @@
+.. Description of configure git diff support for inventory files
+
+Integration -- git diff
+========================
+
+.. program:: git diff
+
+|soi-textconv| converts .inv files to plain text sending the
+output to |stdout|.
+
+.. code-block:: shell
+
+   sphobjinv-textconv objects.inv
+
+Which is equivalent to
+
+.. code-block:: shell
+
+   sphobjinv convert plain objects.inv -
+
+Convenience aside, why the redundant CLI command, |soi-textconv|?
+
+To compare changes to a |objects.inv| file, :code:`git diff` won't
+produce a useful result without configuration. And git only accepts a
+CLI command with:
+
+- one input, the INFILE path
+
+- sends output to |stdout|
+
+Usage
+------
+
+Initialize git
+"""""""""""""""
+
+.. code-block:: shell
+
+   git init
+   git config user.email [email protected]
+   git config user.name "a test"
+
+Configure git
+""""""""""""""
+
+``git diff`` is really useful, so it's time to configure git
+
+There is no CLI command to configure git for us.
+
+In ``.git/config`` (or $HOME/.config/git/config) append,
+
+.. code-block:: text
+
+   [diff "inv"]
+   	textconv = [absolute path to venv bin folder]/sphobjinv-textconv
+
+Note has one tab, not whitespace(s)
+
+In ``.gitattributes`` append,
+
+.. code-block:: text
+
+   *.inv binary diff=inv
+
+Example
+--------
+
+Make one commit
+""""""""""""""""
+
+Commit these files:
+
+- objects_attrs.inv
+
+- objects_attrs.txt
+
+- .gitattributes
+
+.. code-block:: shell
+
+   git add .
+   git commit --no-verify --no-gpg-sign -m "test textconv"
+
+Make a change to ``objects_attrs.inv``
+"""""""""""""""""""""""""""""""""""""""
+
+By shell
+
+.. code-block:: shell
+
+   URL="https://github.com/bskinn/sphobjinv/raw/main/tests/resource/objects_attrs.inv"
+   wget "$URL"
+   sphobjinv convert plain -qu "$URL" objects_attrs.txt
+   export APPEND_THIS="attrs.validators.set_cheat_mode py:function 1 api.html#$ -"
+   echo "$APPEND_THIS" >> objects_attrs.txt
+   sphobjinv convert zlib -qu objects_attrs.txt objects_attrs.inv
+
+By python code
+
+.. versionadded:: 2.4.0
+    Append a line to .inv (compressed) inventory
+
+    .. doctest:: append_a_line
+
+       >>> from pathlib import Path
+       >>> from sphobjinv import DataObjStr
+       >>> from sphobjinv.cli.load import import_infile
+       >>> from sphobjinv.cli.write import write_plaintext
+       >>>
+       >>> remote_url = (
+       ...     "https://github.com/bskinn/sphobjinv/"
+       ...     "raw/main/tests/resource/objects_attrs.inv"
+       ... )
+       >>> cli_run(f'sphobjinv convert plain -qu {remote_url} objects_attrs.txt')
+       <BLANKLINE>
+       >>> path_dst_dec = Path('objects_attrs.txt')
+       >>> path_dst_cmp = Path('objects_attrs.inv')
+       >>> dst_dec_path = str(path_dst_dec)
+       >>> path_dst_dec.is_file()
+       True
+       >>> inv_0 = import_infile(dst_dec_path)
+       >>> obj_datum = DataObjStr(
+       ...     name="attrs.validators.set_cheat_mode",
+       ...     domain="py",
+       ...     role="function",
+       ...     priority="1",
+       ...     uri="api.html#$",
+       ...     dispname="-",
+       ... )
+       >>> inv_0.objects.append(obj_datum)
+       >>> write_plaintext(inv_0, dst_dec_path)
+       >>> cli_run('sphobjinv convert -q zlib objects_attrs.txt objects_attrs.inv')
+       <BLANKLINE>
+       >>> path_dst_cmp.is_file()
+       True
+
+Show the diff
+""""""""""""""
+
+To see the changes to objects_attrs.inv
+
+.. code-block:: shell
+
+   git diff HEAD objects_attrs.inv 2>/dev/null
+
+Without |soi-textconv|, *These two binary files differ*
+
+With |soi-textconv| configured
+
+.. code-block:: text
+
+   diff --git a/objects.inv b/objects.inv
+   index 85189bd..65cc567 100644
+   --- a/objects.inv
+   +++ b/objects.inv
+   @@ -131,4 +131,5 @@ types std:doc -1 types.html Type Annotations
+    validators std:label -1 init.html#$ Validators
+    version-info std:label -1 api.html#$ -
+    why std:doc -1 why.html Why not…
+   +attrs.validators.set_cheat_mode py:function 1 api.html#$ -

doc/source/cli/implementation/core-textconv.rst

@@ -0,0 +1,7 @@
+.. Module API page for cli/core_textconv.py
+
+sphobjinv.cli.core_textconv
+===========================
+
+.. automodule:: sphobjinv.cli.core_textconv
+    :members:

doc/source/cli/implementation/index.rst

@@ -8,6 +8,7 @@ sphobjinv.cli (non-API)
 
     convert
     core
+    core-textconv
     load
     parser
     paths