v2.0 Rewrite

.github/workflows/test.yml

@@ -33,6 +33,8 @@ jobs:
         include:
           - python-version: '3.7'
             toxenv: lint
+          - python-version: '3.7'
+            toxenv: typing
     steps:
       - name: Check out repository
         uses: actions/checkout@v4

.gitignore

@@ -2,14 +2,15 @@
 *.egg-info/
 *.pyc
 .cache/
-.coverage
+.coverage*
 .eggs/
+.mypy_cache/
 .nox/
 .pytest_cache/
 .tox/
 __pycache__/
 build/
 dist/
+docs/.doctrees/
 docs/_build/
-pip-wheel-metadata/
 venv/

CHANGELOG.md

@@ -1,8 +1,40 @@
-In Development
---------------
+v2.0.0 (in development)
+-----------------------
 - Dropped support for Python 3.6
 - Support Python 3.11 and 3.12
 - Moved to wheelodex organization
+- Added type annotations
+- Removed the old `SCHEMA` alias for `WHEEL_SCHEMA` (deprecated in v1.6.0)
+- Removed the re-export of `ParsedWheelFilename` and `parse_wheel_filename()`
+  from `wheel-filename` (deprecated in v1.5.0)
+- Digest algorithm names in `RECORD` files are now converted to lowercase
+  during parsing
+- Schema changes:
+    - `RECORD`s are now represented by an object that maps each file path to
+      either `null` or a subobject with "algorithm", "digest", and "size"
+      properties
+    - The `.file` property in wheel inspection results (containing the file's
+      size and digest) has been removed
+    - The filename component properties have been organized into a
+      `"wheel_name"` subobject, and many of them have been renamed
+    - `DIST_INFO_SCHEMA` has been eliminated; `WHEEL_SCHEMA` is now used for
+      all inspection results
+    - The `dependency_links`, `entry_points`, `namespace_packages`,
+      `top_level`, and `zip_safe` properties of the `dist_info` object are now
+      `null` instead of absent if the respective files are absent from the
+      `*.dist-info` directory.
+    - `.validation_error.str` has been renamed to "message"
+    - `.validation_error` now contains an "args" field giving type-specific
+      properties
+- `RECORD` entries with negative sizes are now detected & errored on earlier
+- Gave `inspect_wheel()` a `digest_files` option for controlling verification
+  of files' digests
+- Gave the CLI command a `--digest-files`/`--no-digest-files` option for
+  controlling verification of files' digests
+- `RECORD` parsing now detects & errors when it encounters a file path that is
+  also a parent path of another entry
+- Path type mismatches between the `RECORD` and the wheel now cause
+  verification to fail
 
 
 v1.7.1 (2022-04-08)

README.rst

@@ -24,7 +24,9 @@
 
 ``wheel-inspect`` examines Python wheel files & ``*.dist-info`` directories and
 outputs various information about their contents as JSON-serializable objects.
-It can be invoked in Python code as::
+It can be invoked in Python code as:
+
+.. code:: python
 
     from wheel_inspect import inspect_wheel
 
@@ -291,10 +293,7 @@ API
 
 ``wheel_inspect.WHEEL_SCHEMA``
    A `JSON Schema <http://json-schema.org>`_ for the structure returned by
-   ``inspect_wheel()``.  This value was previously exported under the name
-   "``SCHEMA``"; the old name continues to be available for backwards
-   compatibility, but it will go away in the future and should not be used in
-   new code.
+   ``inspect_wheel()``.
 
 ``wheel_inspect.inspect_dist_info_dir(dirpath)``
    Treat ``dirpath`` as a ``*.dist-info`` directory and inspect just it & its
@@ -305,14 +304,6 @@ API
    Inspect the wheel file at the given ``path``.  The structure of the return
    value is described by ``WHEEL_SCHEMA``.
 
-Previous versions of ``wheel-inspect`` provided a ``parse_wheel_filename()``
-function.  As of version 1.5.0, that feature has been split off into its own
-package, `wheel-filename <https://github.com/jwodder/wheel-filename>`_.
-``wheel-inspect`` continues to re-export this function in order to maintain API
-compatibility with earlier versions, but this will change in the future.  Code
-that imports ``parse_wheel_filename()`` from ``wheel-inspect`` should be
-updated to use ``wheel-filename`` instead.
-
 
 Command
 =======

docs/changelog.rst

@@ -0,0 +1,143 @@
+.. currentmodule:: wheel_inspect
+
+Changelog
+=========
+
+v2.0.0 (in development)
+-----------------------
+- Dropped support for Python 3.6
+- Support Python 3.11 and 3.12
+- Moved to wheelodex organization
+- Added type annotations
+- Removed the old ``SCHEMA`` alias for `~wheel_inspect.schema.WHEEL_SCHEMA`
+  (deprecated in v1.6.0)
+- Removed the re-export of ``ParsedWheelFilename`` and
+  ``parse_wheel_filename()`` from ``wheel-filename`` (deprecated in v1.5.0)
+- Digest algorithm names in :file:`RECORD` files are now converted to lowercase
+  during parsing
+- Schema changes:
+
+  - :file:`RECORD`\s are now represented by an object that maps each file path
+    to either ``null`` or a subobject with "algorithm", "digest", and "size"
+    properties
+  - The ``.file`` property in wheel inspection results (containing the file's
+    size and digest) has been removed
+  - The filename component properties have been organized into a
+    ``"wheel_name"`` subobject, and many of them have been renamed
+  - ``DIST_INFO_SCHEMA`` has been eliminated;
+    `~wheel_inspect.schema.WHEEL_SCHEMA` is now used for all inspection results
+  - The ``dependency_links``, ``entry_points``, ``namespace_packages``,
+    ``top_level``, and ``zip_safe`` properties of the ``dist_info`` object are
+    now ``null`` instead of absent if the respective files are absent from the
+    :file:`*.dist-info` directory.
+  - ``.validation_error.str`` has been renamed to "message"
+  - ``.validation_error`` now contains an "args" field giving type-specific
+    properties
+
+- :file:`RECORD` entries with negative sizes are now detected & errored on
+  earlier
+- Gave `inspect_wheel()` a ``digest_files`` option for controlling verification
+  of files' digests
+- Gave the CLI command a :option:`wheel2json
+  --digest-files`/:option:`wheel2json --no-digest-files` option for controlling
+  verification of files' digests
+- :file:`RECORD` parsing now detects & errors when it encounters a file path
+  that is also a parent path of another entry
+- Path type mismatches between the :file:`RECORD` and the wheel now cause
+  verification to fail
+
+
+v1.7.1 (2022-04-08)
+-------------------
+- Support Python 3.10
+- Remove the upper bound on the ``readme_renderer`` dependency
+
+
+v1.7.0 (2020-11-07)
+-------------------
+- When verifying a :file:`RECORD`, directory entries listed therein are now
+  checked for existence.
+- Remove dependency on ``pkg_resources``
+- Dropped support for Python 3.5
+- Support Python 3.9
+- Drop ``read_version`` build dependency
+- Support wheels whose filenames and :file:`*.dist-info` directories use
+  different casings/spellings for the project name and/or version
+- Better validation errors for wheels with missing or improper
+  :file:`*.dist_info` directories
+
+
+v1.6.0 (2020-05-01)
+-------------------
+- Added an `inspect_dist_info_dir()` function for inspecting bare, unpacked
+  :file:`*.dist-info` directories
+- Added a ``DIST_INFO_SCHEMA`` schema describing the return value of
+  `inspect_dist_info_dir()`
+- Renamed ``SCHEMA`` to `~wheel_inspect.schema.WHEEL_SCHEMA`; the value remains
+  available under the old name for backwards compatibility
+- The :command:`wheel2json` command now accepts directory arguments and
+  inspects them with `inspect_dist_info_dir()`
+
+
+v1.5.0 (2020-04-21)
+-------------------
+- **Bugfix**: Now *actually* discard *all* empty keywords
+- Split off the wheel filename processing code into its own package,
+  `wheel-filename <https://github.com/jwodder/wheel-filename>`_.  Wheel-Inspect
+  currently re-exports ``ParsedWheelFilename`` and ``parse_wheel_filename()``
+  from this library in order to maintain API compatibility with earlier
+  versions, but this may change in the future.
+- Adjusted the schema to indicate that ``.dist_info.metadata.description`` may
+  be ``null``
+- Binary extension modules and modules located in ``*.data/{purelib,platlib}``
+  are now included in ``.derived.modules``
+
+
+v1.4.1 (2020-03-12)
+-------------------
+- Drop support for Python 3.4
+- Update ``property-manager`` dependency, thereby eliminating a
+  DeprecationWarning
+
+
+v1.4.0 (2020-01-25)
+-------------------
+- When splitting apart comma-separated keywords, trim whitespace and discard
+  any keywords that are empty or all-whitespace
+- Support Python 3.8
+
+
+v1.3.0 (2019-05-09)
+-------------------
+- Upgraded ``wheel_inspect.SCHEMA`` from JSON Schema draft 4 to draft 7
+- Don't require directory entries in wheels to be listed in :file:`RECORD`
+
+
+v1.2.1 (2019-04-20)
+-------------------
+- Include :file:`pyproject.toml` in :file:`MANIFEST.in`, thereby making it
+  possible to build from sdist
+
+
+v1.2.0 (2019-04-20)
+-------------------
+- ``.derived.keywords`` is now sorted and duplicate-free
+
+
+v1.1.0 (2018-10-28)
+-------------------
+- ``"buildver"`` is now `None`/``null`` instead of the empty string when there
+  is no build tag in the wheel's filename
+- Added a ``parse_wheel_filename()`` function for parsing a wheel filename into
+  its components
+- Validation of :file:`RECORD` files is now done directly by ``wheel-inspect``
+  instead of with ``distlib`` in order to achieve more descriptive error
+  messages
+
+
+v1.0.0 (2018-10-12)
+-------------------
+Initial release
+
+This project's code was previously part of `Wheelodex
+<https://github.com/jwodder/wheelodex>`_.

docs/classes.rst

@@ -0,0 +1,40 @@
+.. currentmodule:: wheel_inspect
+
+Core Classes
+============
+
+ABCs
+----
+
+.. autosummary::
+    :nosignatures:
+
+    DistInfoProvider
+    FileProvider
+    BackedDistInfo
+
+.. autoclass:: DistInfoProvider
+
+.. autoclass:: FileProvider
+
+.. autoclass:: BackedDistInfo
+    :show-inheritance:
+
+Concrete Classes
+----------------
+
+.. autosummary::
+    :nosignatures:
+
+    WheelFile
+    UnpackedWheelDir
+    DistInfoDir
+
+.. autoclass:: WheelFile()
+    :show-inheritance:
+
+.. autoclass:: UnpackedWheelDir()
+    :show-inheritance:
+
+.. autoclass:: DistInfoDir()
+    :show-inheritance:

docs/command.rst

@@ -0,0 +1,30 @@
+.. index:: wheel2json (command)
+
+Command-Line Program
+====================
+
+::
+
+    wheel2json [<option>] [<path> ...]
+
+``wheel-inspect`` provides a :command:`wheel2json` command (also accessible as
+``python -m wheel_inspect``) that can be used to inspect wheels and
+:file:`*.dist-info` directories from the command line.  Each path passed to the
+command is inspected separately (treated as a :file:`*.dist-info` directory if
+it is a directory, treated as a wheel file otherwise), and the resulting data
+is output as a pretty-printed JSON object.  (Note that this results in a stream
+of JSON objects with no separation when multiple paths are given.)
+
+Options
+-------
+
+.. program:: wheel2json
+
+.. option:: --digest-files
+
+    Verify the digests of files listed inside wheels' :file:`RECORD`\s.  This
+    is the default.
+
+.. option:: --no-digest-files
+
+    Do not verify file digests

docs/conf.py

@@ -0,0 +1,46 @@
+from wheel_inspect import __version__
+
+project = "wheel-inspect"
+author = "John Thorvald Wodder II"
+copyright = "2017-2021 John Thorvald Wodder II"  # noqa: A001
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.inheritance_diagram",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.viewcode",
+    "sphinx_copybutton",
+]
+
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+}
+autodoc_typehints_format = "fully-qualified"
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+exclude_patterns = ["_build"]
+source_suffix = ".rst"
+source_encoding = "utf-8"
+master_doc = "index"
+version = __version__
+release = __version__
+today_fmt = "%Y %b %d"
+default_role = "py:obj"
+pygments_style = "sphinx"
+# nitpicky = True
+
+html_theme = "furo"
+html_last_updated_fmt = "%Y %b %d"
+html_show_sourcelink = True
+html_show_sphinx = True
+html_show_copyright = True
+
+copybutton_prompt_text = r">>> |\.\.\. |\$ "
+copybutton_prompt_is_regexp = True
+
+# inheritance_graph_attrs = {"rankdir": "TB"}

docs/errors.rst

@@ -0,0 +1,11 @@
+Exceptions
+==========
+
+.. inheritance-diagram:: wheel_inspect.errors
+    :caption: Exception Hierarchy
+    :parts: 1
+
+.. automodule:: wheel_inspect.errors
+    :member-order: bysource
+    :show-inheritance:
+    :inherited-members: Exception