diff --git a/.github/workflows/ci_tests.yml b/.github/workflows/ci_tests.yml index 7565e8e..9597cfd 100644 --- a/.github/workflows/ci_tests.yml +++ b/.github/workflows/ci_tests.yml @@ -4,18 +4,18 @@ on: push jobs: all_checks: - name: Run all tests, lints, etc. (Python 3.10) + name: Run all tests, lints, etc. (Python 3.11) runs-on: ubuntu-latest if: "!contains(github.event.head_commit.message, '[skip ci]')" steps: - name: Check out repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Install Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: - python-version: '3.10' + python-version: '3.11' cache: 'pip' cache-dependency-path: | requirements-ci.txt @@ -63,15 +63,15 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - python: ['3.7', '3.8', '3.9', '3.11'] + python: ['3.8', '3.9', '3.10', '3.12'] if: "!contains(github.event.head_commit.message, '[skip ci]')" steps: - name: Check out repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Install Python - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python }} cache: 'pip' diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f4c74c..b6f7c2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,8 +3,32 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) -and this project strives to adhere to -[Semantic Versioning](http://semver.org/spec/v2.0.0.html). +and this project follows an extension of +[Semantic Versioning](http://semver.org/spec/v2.0.0.html), where a bump in a +fourth number represents an administrative maintenance release with no code +changes. + +### [2.3.1.1] - 2024-05-21 + +#### 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]). ### [2.3.1] - 2022-11-29 @@ -534,3 +558,7 @@ 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. + + +[#287]: https://github.com/bskinn/sphobjinv/issues/287 +[#289]: https://github.com/bskinn/sphobjinv/pull/289 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b2a915c..01f1f54 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,8 +5,8 @@ Thanks for your interest in contributing to `sphobjinv`! The aim of this document is to provide the information you need to get started smoothly on a contribution. -If you have any questions, please drop me a line on Twitter -([@btskinn](https://twitter.com/btskinn)) or open an +If you have any questions, please drop me a line on Mastodon +([@btskinn@fosstodon.org](https://fosstodon.org/@btskinn)) or open an [issue](https://github.com/bskinn/sphobjinv/issues). @@ -38,12 +38,12 @@ $ git clone https://github.com/{you}/sphobjinv ``` Then, create a virtual environment for the project, in whatever location you -prefer. Any Python interpreter 3.7+ *should* work fine. +prefer. Any Python interpreter 3.8+ *should* work fine. I prefer to use `virtualenv` and create in `./env`: ``` -$ python3.10 -m virtualenv env --prompt="sphobjinv" +$ python3.11 -m virtualenv env --prompt="sphobjinv" ``` Activate the environment: @@ -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.7 through 3.11 -installed and on `PATH` as `python3.7`, `python3.8`, etc. The nonlocal test +want, but you'll need working versions of all of Python 3.8 through 3.12 +installed and on `PATH` as `python3.8`, `python3.9`, 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.7 through 3.11, as well +Github Actions runs the test suite on Linux for Python 3.8 through 3.12, 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. diff --git a/LICENSE.txt b/LICENSE.txt index 3a32da7..fbebf23 100644 --- a/LICENSE.txt +++ b/LICENSE.txt @@ -1,6 +1,6 @@ The MIT License (MIT) -Copyright (c) 2016-2022 Brian Skinn and community contributors +Copyright (c) 2016-2024 Brian Skinn and community contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in diff --git a/MANIFEST.in b/MANIFEST.in index c7069e4..e83169a 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,5 +1,5 @@ include AUTHORS.md CHANGELOG.md CONTRIBUTING.md LICENSE.txt pyproject.toml -include README.rst requirements-dev.txt requirements-flake8.txt tox.ini +include README.md requirements-dev.txt requirements-flake8.txt tox.ini graft src/sphobjinv/_vendored/fuzzywuzzy diff --git a/README.md b/README.md new file mode 100644 index 0000000..f90a22a --- /dev/null +++ b/README.md @@ -0,0 +1,211 @@ +## sphobjinv: Manipulate and inspect Sphinx objects.inv files + + +#### Current Development Version + +[![GitHub Workflow Status][workflow badge]][workflow link target] +[![Codecov Coverage][codecov badge]][codecov target] + +#### Most Recent Stable Release + +[![PyPI Version][pypi badge]][pypi link target] +![Python Versions][python versions badge] + +#### Info + +[![ReadTheDocs status][readthedocs badge]][readthedocs link target] +[![gitter chat][gitter badge]][gitter link target] + +[![MIT License][license badge]][license link target] +[![black formatted][black badge]][black link target] +[![PePY stats][pepy badge]][pepy link target] + +---- + +### Using Sphinx? + +#### Having trouble writing cross-references? + +`sphobjinv` (short for '**sph**inx **obj**ects.**inv**') can help! + +The syntax required for a functional Sphinx cross-reference is highly +non-obvious in many cases. Sometimes Sphinx can guess correctly what +you mean, but it's pretty hit-or-miss. The best approach is to provide +Sphinx with a completely specified cross-reference, and that's where +`sphobjinv` comes in. + +After a `pip install sphobjinv` (or `pipx install sphobjinv`), find the +documentation set you want to cross-reference into, and pass it to +`sphobjinv suggest`. + +For internal cross-references, locate `objects.inv` within `build/html`: + +```none +$ 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 + +220 objects in inventory. + +------------------------------------------------ + +11 results found at/above current threshold of 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 +``` + +The `-s` argument in the above shell command indicates to print the +`fuzzywuzzy` match score along with each search result, and `-t 50` +changes the reporting threshold for the match score. + +For external references, find the API documentation wherever it lives on +the web, and pass `sphobjinv suggest` a URL from within the documentation set +with the `--url/-u` flag. For example, say I need to know how to +cross-reference the `linspace` function from numpy (see +[here][numpy linspace]): + +```none +$ sphobjinv suggest https://numpy.org/doc/1.26/reference/index.html linspace -su + +Attempting https://numpy.org/doc/1.26/reference/index.html ... + ... no recognized inventory. +Attempting "https://numpy.org/doc/1.26/reference/index.html/objects.inv" ... + ... HTTP error: 404 Not Found. +Attempting "https://numpy.org/doc/1.26/reference/objects.inv" ... + ... HTTP error: 404 Not Found. +Attempting "https://numpy.org/doc/1.26/objects.inv" ... + ... inventory found. + +---------------------------------------------------------------------------------- + +The intersphinx_mapping for this docset is LIKELY: + + (https://numpy.org/doc/1.26/, None) + +---------------------------------------------------------------------------------- + +Project: NumPy +Version: 1.26 + +8152 objects in inventory. + +---------------------------------------------------------------------------------- + +8 results found at/above current threshold of 75. + + Name Score +-------------------------------------------------------------- ------- +:py:function:`numpy.linspace` 90 +:py:method:`numpy.polynomial.chebyshev.Chebyshev.linspace` 90 +:py:method:`numpy.polynomial.hermite.Hermite.linspace` 90 +:py:method:`numpy.polynomial.hermite_e.HermiteE.linspace` 90 +:py:method:`numpy.polynomial.laguerre.Laguerre.linspace` 90 +:py:method:`numpy.polynomial.legendre.Legendre.linspace` 90 +:py:method:`numpy.polynomial.polynomial.Polynomial.linspace` 90 +:std:doc:`reference/generated/numpy.linspace` 90 +``` + +**NOTE** that the results from `sphobjinv suggest` are printed using the +longer *block directives*, whereas cross-references must be composed using the +*inline directives*. Thus, the above `linspace()` function must be +cross-referenced as ``` :func:`numpy.linspace` ``` , **not** +``` :function:`numpy.linspace` ```. + +**Need to edit an inventory after it's created, or compose one from scratch?** + +`sphobjinv` can help with that, too. + +`objects.inv` files can be decompressed to plaintext at the commandline: + +```none +$ sphobjinv convert plain -o doc/build/html/objects.inv doc/scratch/ +Conversion completed. +'...objects.inv' converted to '...objects.txt' (plain). +``` + +JSON output is supported (`sphobjinv convert json ...`), and +inventories can be re-compressed to the +partially-zlib-compressed form that `intersphinx` reads +(`sphobjinv convert zlib ...`). + +Alternatively, `sphobjinv` exposes an API to enable automation of +inventory creation/modification: + +```python +>>> import sphobjinv as soi +>>> inv = soi.Inventory('doc/build/html/objects.inv') +>>> print(inv) + +>>> inv.project +'sphobjinv' +>>> inv.version +'2.3' +>>> inv.objects[0] +DataObjStr(name='sphobjinv.cli.convert', domain='py', role='module', priority='0', uri='cli/implementation/convert.html#module-$', dispname='-') + +``` + +The API also enables straightforward re-export of an inventory, for subsequent +use with `intersphinx` cross-references. See [the docs][soi docs inv export] for +more details. + +---- + +Full documentation is hosted at [Read The Docs][readthedocs link target]. + +Available on [PyPI][pypi link target] (`pip install sphobjinv`). + +Source on [GitHub][github repo]. Bug reports and feature requests are welcomed +at the [Issues][github issue tracker] page there. + +Copyright (c) Brian Skinn 2016-2024 + +The `sphobjinv` documentation (including docstrings and README) is licensed +under a [Creative Commons Attribution 4.0 International License][cc-by 4.0] +(CC-BY). The `sphobjinv` codebase is released under the [MIT License]. See +[`LICENSE.txt`][license link target] for full license terms. + + +[black badge]: https://img.shields.io/badge/code%20style-black-000000.svg +[black link target]: https://github.com/psf/black +[cc-by 4.0]: http://creativecommons.org/licenses/by/4.0/ +[codecov badge]: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg +[codecov target]: https://codecov.io/gh/bskinn/sphobjinv +[soi docs inv export]: http://sphobjinv.readthedocs.io/en/latest/api_usage.html#exporting-an-inventory +[github issue tracker]: https://github.com/bskinn/sphobjinv/issues +[github repo]: https://github.com/bskinn/sphobjinv +[gitter badge]: https://badges.gitter.im/sphobjinv/community.svg +[gitter link target]: https://gitter.im/sphobjinv/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge +[license badge]: https://img.shields.io/github/license/mashape/apistatus.svg +[license link target]: https://github.com/bskinn/sphobjinv/blob/stable/LICENSE.txt +[mit license]: https://opensource.org/licenses/MIT +[numpy linspace]: https://numpy.org/doc/1.26/reference/generated/numpy.linspace.html +[pepy badge]: https://pepy.tech/badge/sphobjinv/month +[pepy link target]: https://pepy.tech/project/sphobjinv?versions=2.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1 +[pypi badge]: https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi] +[pypi link target]: https://pypi.org/project/sphobjinv +[python versions badge]: https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python +[readthedocs badge]: https://img.shields.io/readthedocs/sphobjinv/latest.svg +[readthedocs link target]: http://sphobjinv.readthedocs.io/en/latest/ +[workflow badge]: https://img.shields.io/github/actions/workflow/status/bskinn/sphobjinv/ci_tests.yml?logo=github&branch=main +[workflow link target]: https://github.com/bskinn/sphobjinv/actions diff --git a/README.rst b/README.rst deleted file mode 100644 index 146eaf6..0000000 --- a/README.rst +++ /dev/null @@ -1,207 +0,0 @@ -sphobjinv: Manipulate and inspect Sphinx objects.inv files -========================================================== - -**Current Development Version:** - -.. image:: https://img.shields.io/github/workflow/status/bskinn/sphobjinv/ci-tests?logo=github - :alt: GitHub Workflow Status - :target: https://github.com/bskinn/sphobjinv/actions - -.. image:: https://codecov.io/gh/bskinn/sphobjinv/branch/main/graph/badge.svg - :target: https://codecov.io/gh/bskinn/sphobjinv - -**Most Recent Stable Release:** - -.. image:: https://img.shields.io/pypi/v/sphobjinv.svg?logo=pypi - :target: https://pypi.org/project/sphobjinv - -.. image:: https://img.shields.io/pypi/pyversions/sphobjinv.svg?logo=python - -**Info:** - -.. 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.0.1&versions=2.1&versions=2.2.2&versions=2.3&versions=2.3.1 - ----- - -**Using Sphinx?** - -**Having trouble writing cross-references?** - -``sphobjinv`` (short for '**sph**\ inx **obj**\ ects.\ **inv**') can help! - -The syntax required for a functional Sphinx cross-reference is highly -non-obvious in many cases. Sometimes Sphinx can guess correctly what -you mean, but it's pretty hit-or-miss. The best approach is to provide -Sphinx with a completely specified cross-reference, and that's where -``sphobjinv`` comes in. - -After a ``pip install sphobjinv`` (or ``pipx install sphobjinv``), find the -documentation set you want 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 58 - - ------------------------------------------------ - - Cannot infer intersphinx_mapping from a local objects.inv. - - ------------------------------------------------ - - Project: sphobjinv - Version: 2.3 - - 220 objects in inventory. - - ------------------------------------------------ - - 11 results found at/above current threshold of 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 - -The ``-s`` argument in the above shell command indicates to print the -``fuzzywuzzy`` match score along with each search result, and ``-t 50`` -changes the reporting threshold for the match score. - -For external references, just find the API documentation wherever it lives on -the web, and pass ``sphobjinv suggest`` a URL from within the documentation set -with the ``--url/-u`` flag. For example, say I need to know how to -cross-reference the ``linspace`` function from numpy (see -`here `__):: - - $ sphobjinv suggest https://numpy.org/doc/1.23/reference/index.html linspace -su - - Attempting https://numpy.org/doc/1.23/reference/index.html ... - ... no recognized inventory. - Attempting "https://numpy.org/doc/1.23/reference/index.html/objects.inv" ... - ... HTTP error: 404 Not Found. - Attempting "https://numpy.org/doc/1.23/reference/objects.inv" ... - ... HTTP error: 404 Not Found. - 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. - - - Name Score - -------------------------------------------------------------- ------- - :py:function:`numpy.linspace` 90 - :py:method:`numpy.polynomial.chebyshev.Chebyshev.linspace` 90 - :py:method:`numpy.polynomial.hermite.Hermite.linspace` 90 - :py:method:`numpy.polynomial.hermite_e.HermiteE.linspace` 90 - :py:method:`numpy.polynomial.laguerre.Laguerre.linspace` 90 - :py:method:`numpy.polynomial.legendre.Legendre.linspace` 90 - :py:method:`numpy.polynomial.polynomial.Polynomial.linspace` 90 - :std:doc:`reference/generated/numpy.linspace` 90 - -.. end shell command - -**NOTE** that the results from ``sphobjinv suggest`` are printed using the -longer *block directives*, whereas cross-references must be composed using the -*inline directives*. Thus, the above ``linspace()`` function must be -cross-referenced as ``:func:`numpy.linspace```, **not** -``:function:`numpy.linspace```. - -**Need to edit an inventory after it's created, or compose one from scratch?** - -``sphobjinv`` can help with that, too. - -``objects.inv`` files can be decompressed to plaintext at the commandline:: - - $ sphobjinv convert plain -o doc/build/html/objects.inv doc/scratch/ - Conversion completed. - '...objects.inv' converted to '...objects.txt' (plain). - -.. end shell command - -JSON output is supported (``sphobjinv convert json ...``), and -inventories can be re-compressed to the -partially-zlib-compressed form that ``intersphinx`` reads -(``sphobjinv convert zlib ...``). - -Alternatively, ``sphobjinv`` exposes an API to enable automation of -inventory creation/modification:: - - >>> import sphobjinv as soi - >>> inv = soi.Inventory('doc/build/html/objects.inv') - >>> print(inv) - - >>> inv.project - 'sphobjinv' - >>> inv.version - '2.3' - >>> inv.objects[0] - DataObjStr(name='sphobjinv.cli.convert', domain='py', role='module', priority='0', uri='cli/implementation/convert.html#module-$', dispname='-') - -The API also enables straightforward re-export of an inventory, -for subsequent use with ``intersphinx`` cross-references. -See `the docs `__ -for more details. - ----- - -Full documentation is hosted at -`Read The Docs `__. - -Available on `PyPI `__ -(``pip install sphobjinv``). - -Source on `GitHub `__. Bug reports -and feature requests are welcomed at the -`Issues `__ page there. - -Copyright (c) Brian Skinn 2016-2022 - -The ``sphobjinv`` documentation (including docstrings and README) is licensed -under a -`Creative Commons Attribution 4.0 International License `__ -(CC-BY). The ``sphobjinv`` codebase is released under the -`MIT License `__. See -`LICENSE.txt `__ for -full license terms. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..8ad2b1f --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,16 @@ +# Security Policy + +## Supported Versions + +`sphobjinv` development currently does not use any maintenance branches, +so any security fixes will be released inline with the primary development +branch. + + +## Reporting a Vulnerability + +To report a security vulnerability, please use the +[Tidelift security contact](https://tidelift.com/security). +Tidelift will coordinate the fix and disclosure, including +any updates on progress toward a fix on a vulnerability and +on accept/decline status of the vulnerability report. diff --git a/azure-pipelines.yml b/azure-pipelines.yml index d3acc29..64f0c2a 100644 --- a/azure-pipelines.yml +++ b/azure-pipelines.yml @@ -1,6 +1,3 @@ -trigger: -- release-* - pr: branches: include: @@ -26,7 +23,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -58,7 +55,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -82,8 +79,6 @@ stages: - template: azure-coretest.yml parameters: pythons: - py37: - spec: '3.7' py38: spec: '3.8' py39: @@ -92,6 +87,8 @@ stages: spec: '3.10' py311: spec: '3.11' + py312: + spec: '3.12' pypy3: spec: 'pypy3' platforms: [linux] @@ -99,8 +96,6 @@ stages: - template: azure-coretest.yml parameters: pythons: - py37: - spec: '3.7' py38: spec: '3.8' py39: @@ -109,6 +104,8 @@ stages: spec: '3.10' py311: spec: '3.11' + py312: + spec: '3.12' platforms: [windows, macOs] - template: azure-sdisttest.yml @@ -127,7 +124,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -153,7 +150,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -171,7 +168,7 @@ stages: - job: readme - displayName: Run README doctests/shell tests + displayName: Run README doctests pool: vmImage: 'Ubuntu-latest' @@ -179,7 +176,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - script: pip install -r requirements-ci.txt displayName: Install CI requirements @@ -195,8 +192,8 @@ stages: - script: cd doc; make html displayName: Build docs - - script: pytest -k readme --readme --doctest-glob="README.rst" - displayName: Run README doc/shell tests + - script: pytest -k readme --doctest-glob="README.md" + displayName: Run README doctests - job: linkcheck @@ -208,7 +205,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -234,7 +231,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: @@ -250,7 +247,7 @@ stages: - script: cd doc; make html; mkdir scratch displayName: Build docset - - script: pytest --cov=. --nonloc --flake8_ext --readme + - script: pytest --cov=. --nonloc --flake8_ext displayName: Run pytest with coverage on the entire project tree - script: coverage report --include="tests/*" --fail-under=100 @@ -266,7 +263,7 @@ stages: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: diff --git a/azure-sdisttest.yml b/azure-sdisttest.yml index 422881b..f7448ea 100644 --- a/azure-sdisttest.yml +++ b/azure-sdisttest.yml @@ -11,7 +11,7 @@ jobs: steps: - task: UsePythonVersion@0 inputs: - versionSpec: '3.10' + versionSpec: '3.11' - task: Cache@2 inputs: diff --git a/conftest.py b/conftest.py index 5c10462..cccab68 100644 --- a/conftest.py +++ b/conftest.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv @@ -62,7 +62,6 @@ def pytest_addoption(parser): parser.addoption( "--flake8_ext", action="store_true", help="Include flake8 extensions test" ) - parser.addoption("--readme", action="store_true", help="Include README shell tests") @pytest.fixture(scope="session") diff --git a/doc/source/conf.py b/doc/source/conf.py index 419bc1e..a89ab04 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -18,7 +18,7 @@ # -- Project information ----------------------------------------------------- project = "sphobjinv" -copyright = "2016-2022, Brian Skinn" +copyright = "2016-2024, Brian Skinn" author = "Brian Skinn" # The full version for `release`, including alpha/beta/rc tags @@ -123,11 +123,11 @@ .. _license_txt: https://github.com/bskinn/sphobjinv/blob/main/LICENSE.txt -.. _MIT License: https://opensource.org/licenses/MIT +.. _MIT License: https://opensource.org/license/MIT .. |CC BY 4.0| replace:: CC BY 4.0 International License -.. _CC BY 4.0: http://creativecommons.org/licenses/by/4.0/ +.. _CC BY 4.0: https://creativecommons.org/licenses/by/4.0/ .. |fuzzywuzzy| replace:: ``fuzzywuzzy`` @@ -135,7 +135,7 @@ .. |pipx| replace:: ``pipx`` -.. _pipx: https://pypa.github.io/pipx/ +.. _pipx: https://pipx.pypa.io/stable/ .. |python-Levenshtein| replace:: ``python-Levenshtein`` diff --git a/doc/source/customfile.rst b/doc/source/customfile.rst index 24871e4..3765cc5 100644 --- a/doc/source/customfile.rst +++ b/doc/source/customfile.rst @@ -71,10 +71,10 @@ can be found at the GitHub repo The `role` values here must be the **full** role names ("`block directives`"), described as the "directives" in the `Sphinx documentation for - domains `__, + domains `__, and not the abbreviated forms ("`inline directives`") `used when constructing cross-references - `__. + `__. Thus, for example, a :class:`~sphobjinv.data.DataObjStr` corresponding to a method on a class should be constructed with @@ -143,7 +143,7 @@ can be found at the GitHub repo intersphinx_mapping = { # Standard reference to web docs, with web objects.inv - 'python': ('https://docs.python.org/3.5', None), + 'python': ('https://docs.python.org/3.12', None), # Django puts its objects.inv file in a non-standard location 'django': ('https://docs.djangoproject.com/en/dev/', 'https://docs.djangoproject.com/en/dev/_objects/'), diff --git a/doc/source/index.rst b/doc/source/index.rst index f285ca2..ad8f24a 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -11,7 +11,7 @@ Welcome to sphobjinv! When documentation is built using, e.g., Sphinx's :obj:`~sphinx.builders.html.StandaloneHTMLBuilder`, an inventory of the named objects in the documentation set `is dumped -`__ +`__ to a file called |objects.inv| in the html build directory. (One common location is, |cour|\ doc/build/html\ |/cour|, though the exact location will vary depending on the details of how Sphinx is configured.) This file is read by |isphx| when @@ -55,7 +55,7 @@ and package managers, including: * Alpine Linux: ``py3-sphobjinv`` (`info `__) - * Arch Linux: ``python-sphobjinv`` (`info `__) + * Arch Linux: ``python-sphobjinv`` * Fedora: ``python-sphobjinv`` (`info `__) @@ -73,7 +73,7 @@ and package managers, including: * pkgsrc: ``textproc/py-sphobjinv`` (`info `__) - * spack: ``py-sphobjinv`` (`info `__) + * spack: ``py-sphobjinv`` |soi| is configured for use both as a diff --git a/doc/source/syntax.rst b/doc/source/syntax.rst index 1bb62e4..ab51b11 100644 --- a/doc/source/syntax.rst +++ b/doc/source/syntax.rst @@ -5,8 +5,8 @@ Sphinx objects.inv v2 Syntax After decompression, "version 2" Sphinx |objects.inv| files follow a syntax that, to the best of this author's ability to determine, is not included in the -Sphinx documentation. The below syntax is believed to be accurate as of Nov 2022 -(Sphinx v6.0.0b2). It is based on inspection of |objects.inv| files "in the +Sphinx documentation. The below syntax is believed to be accurate as of May 2024 +(Sphinx v7.3.7). It is based on inspection of |objects.inv| files "in the wild" and of the Sphinx inventory object `parsing regex`_. Based upon a quick ``git diff`` of the `Sphinx repository @@ -27,7 +27,7 @@ data line. ---- **The first line** `must be exactly -`__: +`__: .. code-block:: none @@ -36,7 +36,7 @@ data line. ---- **The second and third lines** `must obey -`__ +`__ the template: .. code-block:: none @@ -56,7 +56,7 @@ the |isphx| cross-references: ---- **The fourth line** `must contain -`__ +`__ the string ``zlib`` somewhere within it, but for consistency it should be exactly: .. code-block:: none @@ -67,7 +67,7 @@ the string ``zlib`` somewhere within it, but for consistency it should be exactl **All remaining lines** of the file are the objects data, each laid out in the `following syntax -`__: +`__: .. code-block:: none @@ -132,8 +132,9 @@ the string ``zlib`` somewhere within it, but for consistency it should be exactl ``{priority}`` Flag for `placement in search results - `__. Most will be ``1`` (standard priority) or - ``-1`` (omit from results) for documentation built by Sphinx. + `__. Most will be ``1`` (standard priority) or + ``-1`` (omit from results) for documentation built by Sphinx; + values of ``0`` (higher priority) or ``2`` (lower priority) may also occur. To note, as of Jan 2022 this value is **not** used by ``intersphinx``; it is only used internally within the search function of the static webpages @@ -193,7 +194,7 @@ of cross-references from other documentation source. **For illustration**, the following is the entry for the :meth:`join() ` method of the :class:`str` class in the -Python 3.9 |objects.inv|, broken out field-by-field: +Python 3.12 |objects.inv|, broken out field-by-field: .. code-block:: none @@ -216,11 +217,11 @@ size of the inventory file: `__," the portion following the ``#`` symbol) and the tail of the anchor is identical to |{name}|_, that tail is `replaced - `__ + `__ with ``$``. |br| |br| #. If |{dispname}|_ is identical to |{name}|_, it is `stored - `__ + `__ as ``-``. Thus, a standard |isphx| reference to this method would take the form: @@ -270,11 +271,11 @@ as in :obj:`This is join! `: .. |prio_js_search| replace:: here -.. _prio_js_search: https://github.com/sphinx-doc/sphinx/blob/2f60b44999d7e610d932529784f082fc1c6af989/sphinx/themes/basic/static/searchtools.js#L28-L47 +.. _prio_js_search: https://github.com/sphinx-doc/sphinx/blob/ac3f74a3e0fbb326f73989a16dfa369e072064ca/sphinx/themes/basic/static/searchtools.js#L28-L46 .. |prio_py_search| replace:: here -.. _prio_py_search: https://github.com/sphinx-doc/sphinx/blob/2f60b44999d7e610d932529784f082fc1c6af989/sphinx/search/__init__.py#L332-L333 +.. _prio_py_search: https://github.com/sphinx-doc/sphinx/blob/ac3f74a3e0fbb326f73989a16dfa369e072064ca/sphinx/search/__init__.py#L344-L345 .. |sphinx_uri_issue| replace:: sphinx-doc/sphinx#7096 @@ -296,4 +297,4 @@ as in :obj:`This is join! `: .. _rst-directive-option: https://www.sphinx-doc.org/en/master/usage/restructuredtext/domains.html#directive-rst-directive-option -.. _parsing regex: https://github.com/sphinx-doc/sphinx/blob/2f60b44999d7e610d932529784f082fc1c6af989/sphinx/util/inventory.py#L115-L116 +.. _parsing regex: https://github.com/sphinx-doc/sphinx/blob/ac3f74a3e0fbb326f73989a16dfa369e072064ca/sphinx/util/inventory.py#L134-L135 diff --git a/pyproject.toml b/pyproject.toml index 3780104..14a04df 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,10 +1,70 @@ [build-system] build-backend = "setuptools.build_meta" requires = [ - "setuptools", + "setuptools>=61.2", "wheel", ] +[project] +name = "sphobjinv" +description = "Sphinx objects.inv Inspection/Manipulation Tool" +license = {text = "MIT License"} +authors = [{name = "Brian Skinn", email = "brian.skinn@gmail.com"}] +classifiers = [ + "License :: OSI Approved", + "License :: OSI Approved :: MIT License", + "Natural Language :: English", + "Environment :: Console", + "Framework :: Sphinx", + "Intended Audience :: Developers", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.8", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Topic :: Documentation", + "Topic :: Documentation :: Sphinx", + "Topic :: Software Development", + "Topic :: Software Development :: Documentation", + "Topic :: Utilities", + "Development Status :: 5 - Production/Stable", +] +keywords = ["sphinx", "sphinx-doc", "inventory", "manager", "inspector"] +requires-python = ">=3.8" +dependencies = [ + "attrs>=19.2", + "certifi", + "jsonschema>=3.0", +] +dynamic = ["version", "readme"] + +[project.urls] +Homepage = "https://github.com/bskinn/sphobjinv" +Changelog = "https://github.com/bskinn/sphobjinv/blob/main/CHANGELOG.md" +Docs = "https://sphobjinv.readthedocs.io/en/stable/" +Thank = "https://fosstodon.org/@btskinn" +Donate = "https://github.com/sponsors/bskinn" + +[project.scripts] +sphobjinv = "sphobjinv.cli.core:main" + +[tool.setuptools] +package-dir = {"" = "src"} +platforms = ["any"] +license-files = ["LICENSE.txt"] +include-package-data = false + +[tool.setuptools.packages.find] +where = ["src"] +namespaces = false + +[tool.setuptools.dynamic] +version = {attr = "sphobjinv.version.__version__"} + [tool.black] line-length = 88 include = ''' diff --git a/requirements-ci.txt b/requirements-ci.txt index e2ab803..af4b5b0 100644 --- a/requirements-ci.txt +++ b/requirements-ci.txt @@ -10,7 +10,7 @@ pytest-check>=1.1.2 pytest-cov pytest-ordering pytest-timeout -sphinx==5.3.0 +sphinx==7.1.2 sphinx-issues sphinx-removed-in sphinx-rtd-theme>=0.5.1 diff --git a/requirements-dev.txt b/requirements-dev.txt index 3a15831..4a36818 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -15,7 +15,7 @@ pytest-ordering pytest-timeout restview rope -sphinx==5.3.0 +sphinx==7.1.2 sphinx-autobuild sphinx-issues sphinx-removed-in diff --git a/requirements-rtd.txt b/requirements-rtd.txt index a5480e1..0445b73 100644 --- a/requirements-rtd.txt +++ b/requirements-rtd.txt @@ -1,5 +1,5 @@ attrs>=19.2 -sphinx==5.3.0 +sphinx==7.1.2 sphinx-issues sphinx-removed-in sphinx-rtd-theme>=0.5.1 diff --git a/setup.cfg b/setup.cfg deleted file mode 100644 index 4d0049d..0000000 --- a/setup.cfg +++ /dev/null @@ -1,57 +0,0 @@ -[metadata] -name = sphobjinv -version = attr: sphobjinv.version.__version__ -description = Sphinx objects.inv Inspection/Manipulation Tool -url = https://github.com/bskinn/sphobjinv -project_urls = - Changelog=https://github.com/bskinn/sphobjinv/blob/main/CHANGELOG.md - Docs=https://sphobjinv.readthedocs.io/en/stable/ - Thank=https://twitter.com/btskinn - Donate=https://github.com/sponsors/bskinn -license = MIT License -license_files = - LICENSE.txt -platforms = any -author = Brian Skinn -author_email = brian.skinn@gmail.com -classifiers = - License :: OSI Approved - License :: OSI Approved :: MIT License - Natural Language :: English - Environment :: Console - Framework :: Sphinx - Intended Audience :: Developers - Operating System :: OS Independent - Programming Language :: Python - Programming Language :: Python :: 3 - Programming Language :: Python :: 3 :: Only - Programming Language :: Python :: 3.7 - Programming Language :: Python :: 3.8 - Programming Language :: Python :: 3.9 - Programming Language :: Python :: 3.10 - Programming Language :: Python :: 3.11 - Topic :: Documentation - Topic :: Documentation :: Sphinx - Topic :: Software Development - Topic :: Software Development :: Documentation - Topic :: Utilities - Development Status :: 5 - Production/Stable -keywords = sphinx, sphinx-doc, inventory, manager, inspector - -[options] -install_requires = - attrs>=19.2 - certifi - jsonschema>=3.0 - -python_requires = >=3.6 -packages = find: -package_dir = - =src - -[options.packages.find] -where = src - -[options.entry_points] -console_scripts = - sphobjinv=sphobjinv.cli.core:main diff --git a/setup.py b/setup.py index 9e34359..a81837a 100644 --- a/setup.py +++ b/setup.py @@ -13,7 +13,7 @@ def readme(): - content = Path("README.rst").read_text(encoding="utf-8") + content = Path("README.md").read_text(encoding="utf-8") new_ver = version_override if version_override else __version__ @@ -36,6 +36,7 @@ def content_update(content, pattern, sub): setup( + name=NAME, long_description=readme(), - long_description_content_type="text/x-rst", + long_description_content_type="text/markdown", ) diff --git a/src/sphobjinv/__init__.py b/src/sphobjinv/__init__.py index e825f1b..325f1ba 100644 --- a/src/sphobjinv/__init__.py +++ b/src/sphobjinv/__init__.py @@ -10,7 +10,7 @@ 17 May 2016 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/__main__.py b/src/sphobjinv/__main__.py index 4b857e1..6328f25 100644 --- a/src/sphobjinv/__main__.py +++ b/src/sphobjinv/__main__.py @@ -10,7 +10,7 @@ 15 May 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/_vendored/__init__.py b/src/sphobjinv/_vendored/__init__.py index 9fd9d19..1334246 100644 --- a/src/sphobjinv/_vendored/__init__.py +++ b/src/sphobjinv/_vendored/__init__.py @@ -12,7 +12,7 @@ 11 Dec 2021 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/_vendored/fuzzywuzzy/__init__.py b/src/sphobjinv/_vendored/fuzzywuzzy/__init__.py index 4d0ee0d..1fefbce 100644 --- a/src/sphobjinv/_vendored/fuzzywuzzy/__init__.py +++ b/src/sphobjinv/_vendored/fuzzywuzzy/__init__.py @@ -25,7 +25,7 @@ 11 Dec 2021 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/__init__.py b/src/sphobjinv/cli/__init__.py index db6aa5c..6bd2ecd 100644 --- a/src/sphobjinv/cli/__init__.py +++ b/src/sphobjinv/cli/__init__.py @@ -10,7 +10,7 @@ 15 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/convert.py b/src/sphobjinv/cli/convert.py index 34f2cc2..b84eadf 100644 --- a/src/sphobjinv/cli/convert.py +++ b/src/sphobjinv/cli/convert.py @@ -10,7 +10,7 @@ 20 Oct 2022 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/core.py b/src/sphobjinv/cli/core.py index dba7479..a5c73d7 100644 --- a/src/sphobjinv/cli/core.py +++ b/src/sphobjinv/cli/core.py @@ -10,7 +10,7 @@ 15 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/load.py b/src/sphobjinv/cli/load.py index f9bd326..d30850c 100644 --- a/src/sphobjinv/cli/load.py +++ b/src/sphobjinv/cli/load.py @@ -10,7 +10,7 @@ 17 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/parser.py b/src/sphobjinv/cli/parser.py index 1928c5d..a4d012e 100644 --- a/src/sphobjinv/cli/parser.py +++ b/src/sphobjinv/cli/parser.py @@ -10,7 +10,7 @@ 15 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv @@ -44,7 +44,7 @@ class PrsConst: #: Version &c. output blurb VER_TXT = ( - f"\nsphobjinv v{__version__}\n\nCopyright (c) Brian Skinn 2016-2022\n" + f"\nsphobjinv v{__version__}\n\nCopyright (c) Brian Skinn 2016-2024\n" "License: The MIT License\n\n" "Bug reports & feature requests:" " https://github.com/bskinn/sphobjinv\n" diff --git a/src/sphobjinv/cli/paths.py b/src/sphobjinv/cli/paths.py index 73a68c3..4941768 100644 --- a/src/sphobjinv/cli/paths.py +++ b/src/sphobjinv/cli/paths.py @@ -10,7 +10,7 @@ 19 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/suggest.py b/src/sphobjinv/cli/suggest.py index 8bd7d65..6367c9d 100644 --- a/src/sphobjinv/cli/suggest.py +++ b/src/sphobjinv/cli/suggest.py @@ -10,7 +10,7 @@ 20 Oct 2022 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/ui.py b/src/sphobjinv/cli/ui.py index 302f1b9..3dd5972 100644 --- a/src/sphobjinv/cli/ui.py +++ b/src/sphobjinv/cli/ui.py @@ -10,7 +10,7 @@ 19 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/cli/write.py b/src/sphobjinv/cli/write.py index e7617bb..8611d94 100644 --- a/src/sphobjinv/cli/write.py +++ b/src/sphobjinv/cli/write.py @@ -10,7 +10,7 @@ 19 Nov 2020 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/data.py b/src/sphobjinv/data.py index 17d5fba..94dd1cf 100644 --- a/src/sphobjinv/data.py +++ b/src/sphobjinv/data.py @@ -10,7 +10,7 @@ 7 Nov 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/enum.py b/src/sphobjinv/enum.py index 866eb8a..6cc3d3e 100644 --- a/src/sphobjinv/enum.py +++ b/src/sphobjinv/enum.py @@ -10,7 +10,7 @@ 4 May 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/error.py b/src/sphobjinv/error.py index ceb90fc..cf2b21d 100644 --- a/src/sphobjinv/error.py +++ b/src/sphobjinv/error.py @@ -10,7 +10,7 @@ 5 Nov 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/fileops.py b/src/sphobjinv/fileops.py index e2d01ed..225dca9 100644 --- a/src/sphobjinv/fileops.py +++ b/src/sphobjinv/fileops.py @@ -10,7 +10,7 @@ 5 Nov 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/inventory.py b/src/sphobjinv/inventory.py index 3d62785..323ad41 100644 --- a/src/sphobjinv/inventory.py +++ b/src/sphobjinv/inventory.py @@ -10,7 +10,7 @@ 7 Dec 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/re.py b/src/sphobjinv/re.py index c02199f..c9ba844 100644 --- a/src/sphobjinv/re.py +++ b/src/sphobjinv/re.py @@ -10,7 +10,7 @@ 5 Nov 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/schema.py b/src/sphobjinv/schema.py index 9851fa5..7b61e23 100644 --- a/src/sphobjinv/schema.py +++ b/src/sphobjinv/schema.py @@ -11,7 +11,7 @@ 7 Dec 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/src/sphobjinv/version.py b/src/sphobjinv/version.py index c84d65a..7f12092 100644 --- a/src/sphobjinv/version.py +++ b/src/sphobjinv/version.py @@ -10,7 +10,7 @@ 18 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv @@ -29,4 +29,4 @@ """ -__version__ = "2.3.1" +__version__ = "2.3.1.1" diff --git a/src/sphobjinv/zlib.py b/src/sphobjinv/zlib.py index f256ce4..3100cfd 100644 --- a/src/sphobjinv/zlib.py +++ b/src/sphobjinv/zlib.py @@ -10,7 +10,7 @@ 5 Nov 2017 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** https://github.com/bskinn/sphobjinv diff --git a/tests/test_api_fail.py b/tests/test_api_fail.py index a584b73..50d8734 100644 --- a/tests/test_api_fail.py +++ b/tests/test_api_fail.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_api_good.py b/tests/test_api_good.py index 2712d4b..d5b1280 100644 --- a/tests/test_api_good.py +++ b/tests/test_api_good.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_api_good_nonlocal.py b/tests/test_api_good_nonlocal.py index b45ba5a..85bfb1d 100644 --- a/tests/test_api_good_nonlocal.py +++ b/tests/test_api_good_nonlocal.py @@ -10,7 +10,7 @@ 21 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_cli.py b/tests/test_cli.py index b1d5748..71f99b8 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv @@ -399,7 +399,7 @@ def test_cli_suggest_paginated(self, res_cmp, run_cmdline_test): """Confirm pagination works as expected for a controlled example.""" with stdio_mgr("\n" * 5) as (in_, out_, err_): run_cmdline_test(["suggest", res_cmp, "function", "-sapt30"]) - assert 5 == out_.getvalue().count("Press Enter to continue") + assert 1 < out_.getvalue().count("Press Enter to continue") class TestFail: diff --git a/tests/test_cli_nonlocal.py b/tests/test_cli_nonlocal.py index 1e4da53..c2d8ea3 100644 --- a/tests/test_cli_nonlocal.py +++ b/tests/test_cli_nonlocal.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_fixture.py b/tests/test_fixture.py index 1e94d4a..0a19aab 100644 --- a/tests/test_fixture.py +++ b/tests/test_fixture.py @@ -10,7 +10,7 @@ 20 Mar 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_flake8_ext.py b/tests/test_flake8_ext.py index 2255488..1ae90ea 100644 --- a/tests/test_flake8_ext.py +++ b/tests/test_flake8_ext.py @@ -10,7 +10,7 @@ 27 Apr 2019 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_intersphinx.py b/tests/test_intersphinx.py index 177326d..24079a5 100644 --- a/tests/test_intersphinx.py +++ b/tests/test_intersphinx.py @@ -10,7 +10,7 @@ 21 Jun 2022 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tests/test_readme.py b/tests/test_readme.py deleted file mode 100644 index 4b5086f..0000000 --- a/tests/test_readme.py +++ /dev/null @@ -1,107 +0,0 @@ -r"""*README shell command doctests for* ``sphobjinv``. - -``sphobjinv`` is a toolkit for manipulation and inspection of -Sphinx |objects.inv| files. - -**Author** - Brian Skinn (brian.skinn@gmail.com) - -**File Created** - 6 Aug 2018 - -**Copyright** - \(c) Brian Skinn 2016-2022 - -**Source Repository** - http://www.github.com/bskinn/sphobjinv - -**Documentation** - https://sphobjinv.readthedocs.io/en/stable - -**License** - Code: `MIT License`_ - - Docs & Docstrings: |CC BY 4.0|_ - - See |license_txt|_ for full license terms. - -**Members** - -""" - -import doctest as dt -import platform -import re -import shlex -import subprocess as sp # noqa: S404 -import sys -from pathlib import Path - - -import pytest -from sphinx import __version__ as sphinx_ver - - -reqs = Path("requirements-dev.txt").read_text() - -m_sphinx_req = re.search("^sphinx==(.+)$", reqs, re.I | re.M) -sphinx_req = m_sphinx_req.group(1) - - -p_shell = re.compile( - r""" - \n\s+[$](?P.*) # Entered command - (?P(\n.*)+?) # Line(s) of output - (?=\n\.\.) # Lookahead for explicit shell block endpoint - """, - re.X, -) - - -pytestmark = [pytest.mark.readme] - - -@pytest.fixture(scope="module", autouse=True) -def skip_if_no_readme_option(pytestconfig): - """Skip test if --readme not provided. - - Auto-applied to all functions in module, since module is dedicated to README. - - """ - if not pytestconfig.getoption("--readme"): - pytest.skip("'--readme' not specified") # pragma: no cover - - -@pytest.mark.skipif( - sphinx_ver != sphinx_req, - reason="Skip if Sphinx version mismatches current dev version.", -) -@pytest.mark.skipif( - "pypy" in platform.python_implementation().lower(), - reason="Inconsistent suggest results on PyPy", -) -def test_readme_shell_cmds(ensure_doc_scratch, is_win, check): - """Perform testing on README shell command examples.""" - if is_win and sys.version_info < (3, 9): # pragma: no cover - pytest.skip("Windows mishandles stdout/stderr for Python < 3.9") - - text = Path("README.rst").read_text() - - chk = dt.OutputChecker() - - dt_flags = dt.ELLIPSIS | dt.NORMALIZE_WHITESPACE - - for mch in p_shell.finditer(text): - cmd = mch.group("cmd") - out = mch.group("out") - - proc = sp.run( # noqa: S603 - shlex.split(cmd), stdout=sp.PIPE, stderr=sp.STDOUT, timeout=30 - ) - - result = proc.stdout.decode("utf-8") - - msg = "\n\nExpected:\n" + out + "\n\nGot:\n" + result - - with check(): - assert chk.check_output(out, result, dt_flags), msg diff --git a/tests/test_valid_objects.py b/tests/test_valid_objects.py index 109befa..648c954 100644 --- a/tests/test_valid_objects.py +++ b/tests/test_valid_objects.py @@ -10,7 +10,7 @@ 13 Feb 2021 **Copyright** - \(c) Brian Skinn 2016-2022 + \(c) Brian Skinn 2016-2024 **Source Repository** http://www.github.com/bskinn/sphobjinv diff --git a/tox.ini b/tox.ini index 8e13b51..3176583 100644 --- a/tox.ini +++ b/tox.ini @@ -3,23 +3,23 @@ minversion=2.0 isolated_build=True envlist= # Test all Python versions on latest lib versions - py3{7,8,9,10,11}-sphx_latest-attrs_latest-jsch_latest - # Test dev Python version on current in-repo dev lib versions - py310-sphx_dev-attrs_dev-jsch_dev + py3{8,9,10,11,12}-sphx_latest-attrs_latest-jsch_latest + # Test leading Python version on current in-repo dev lib versions + py312-sphx_dev-attrs_dev-jsch_dev # Scan across Sphinx versions - py310-sphx_{1_6_x,1_x,2_x,4_x,dev}-attrs_latest-jsch_latest + py312-sphx_{1_6_x,1_x,2_x,4_x,5_x,6_xdev}-attrs_latest-jsch_latest # sphx_3_x is incompatible with py310 due to a typing import. Test on py39 instead. py39-sphx_3_x-attrs_latest-jsch_latest # Scan attrs versions - py310-sphx_latest-attrs_{19_2,19_3,20_1,20_2,20_3,21_2,21_3,dev}-jsch_latest + py312-sphx_latest-attrs_{19_2,19_3,20_1,20_2,20_3,21_2,21_3,22_2,dev}-jsch_latest # Scan jsonschema versions - py310-sphx_latest-attrs_latest-jsch_{3_0,3_x,4_0,4_8,dev} + py312-sphx_latest-attrs_latest-jsch_{3_0,3_x,4_0,4_8,4_14,dev} # Earliest supported Python and lib versions all together - py37-sphx_1_6_x-attrs_19_2-jsch_3_0 + py38-sphx_1_6_x-attrs_19_2-jsch_3_0 # Spot matrix of early Python, Sphinx, attrs versions - py3{7,8,9}-sphx_{1,2}_x-attrs_{19,20}_2-jsch_latest + py3{8,9}-sphx_{1,2}_x-attrs_{19,20}_2-jsch_latest # Test the specific Sphinx threshold cases where behavior changed - py310-sphx_{2_3_1,2_4_0,3_2_1,3_3_0,3_4_0}-attrs_latest-jsch_latest + py312-sphx_{2_3_1,2_4_0,3_2_1,3_3_0,3_4_0}-attrs_latest-jsch_latest # Simple 'does the sdist install' check sdist_install # Lints @@ -38,6 +38,8 @@ deps= sphx_2_x: sphinx<3 sphx_3_x: sphinx<4 sphx_4_x: sphinx<5 + sphx_5_x: sphinx<6 + sphx_6_x: sphinx<7 sphx_2_3_1: sphinx==2.3.1 sphx_2_4_0: sphinx==2.4.0 sphx_3_2_1: sphinx==3.2.1 @@ -53,6 +55,7 @@ deps= attrs_20_3: attrs==20.3 attrs_21_2: attrs==21.2 attrs_21_3: attrs==21.3 + attrs_22_2: attrs==22.2 attrs_latest: attrs attrs_dev: git+https://github.com/python-attrs/attrs @@ -60,6 +63,7 @@ deps= jsch_3_x: jsonschema<4 jsch_4_0: jsonschema<4.1 jsch_4_8: jsonschema<4.9 + jsch_4_14: jsonschema<4.15 jsch_latest: jsonschema jsch_dev: git+https://github.com/Julian/jsonschema @@ -76,24 +80,24 @@ deps= [testenv:linux] platform=linux basepython= + py312: python3.12 py311: python3.11 py310: python3.10 py39: python3.9 py38: python3.8 - py37: python3.7 [testenv:flake8] skip_install=True deps=-rrequirements-flake8.txt commands= - flake8 conftest.py src tests + flake8 ./conftest.py src tests [testenv:flake8-noqa] skip_install=True deps=-rrequirements-flake8.txt commands= pip install flake8-noqa - flake8 --color=never --exit-zero conftest.py tests src + flake8 --color=never --exit-zero ./conftest.py tests src [testenv:interrogate] skip_install=True @@ -113,7 +117,6 @@ markers = cli: Command-line interface tests api: Direct API tests intersphinx: Tests on intersphinx-related functionality - readme: Testing shell examples in README.rst fixture: Trivial tests for test suite fixtures testall: Tests that use *all* objects_xyz.inv files in tests/resource, if --testall is specified flake8_ext: Test checking that all desired plugins are active @@ -132,7 +135,8 @@ exclude = src/sphobjinv/_vendored # W503: black formats binary operators to start of line -ignore = W503 +# A005: Submodules are going to be shadowing builtins for the moment +ignore = W503,A005 show_source = True max_line_length = 88 format = %(cyan)s%(path)s%(reset)s:%(yellow)s%(row)d%(reset)s:%(green)s%(col)d%(reset)s %(red)s(%(code)s)%(reset)s %(text)s