v2.0 Rewrite

[jwodder]

Closes #3.
Closes #4.
Closes #6.
Closes #9.
Closes #19.

Major Changes So Far

See the changelog for more.

• Public library API added
• Removed deprecated SCHEMA alias for WHEEL_SCHEMA
• Removed re-exports of ParsedWheelFilename and parse_wheel_filename() from wheel-filename
• Numerous schema changes
• 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

To Do

• Detect more validation errors #34

• Check zipfiles for "well-behaved-ness" #35

• Use headerparser's upcoming attrs-based parser API to rewrite the Metadata and WheelInfo classes

  • Blocked by: Add a new parser API built on attrs for defining classes instantiated from scanned stanzas headerparser#52
  • Store parsing & validation defects (blocked by: Add a field type for storing parsing defects headerparser#53); cf. the items about lists of errors & failing fast below

• Give Metadata a pep566_json() method (Support emitting metadata in the JSON format from PEP 566 #17)

• Look into whether zipfile.Path would help with the code

• Make Record.dist_info_dirname optional and have FiletreeMapping handle its none-ness by declaring the key absent?

• Give DistInfoDir.from_path() a wheel_name argument?

• When wheel_info.root_is_purelib is absent/not set, have the filetrees treat it as though it were True

• Should paths support / when the left operand is a file?

• Record will need a public from_csv_fields(cls, rows: Iterable[list[str]]) classmethod or similar for constructing Records for testing purposes (both wheel-inspect and check-wheel-contents)

• Make --no-digest-files the CLI's default behavior?

• Validation:

  • Make validate() check the version in *.dist-info & *.data for validity
  • Metadata: Parse/validate Requires-Python
  • Give WheelInfo a method for validating the tags & build number against that given in a wheel filename
  • Make validate() validate the wheel name's version
  • Check project & version in dist-info dirname match METADATA fields

• Error collection:

  • The wheel inspection structure should store a list of all errors encountered instead of just the first one #10
  • Make validation_error plural
  • Give the inspection schema a verification_errors: list property containing all file verification errors and a verified: bool property
  • Give validate(), verify(), and anything with a strict argument a fail_fast=True option for controlling whether to raise the first error or keep going and collect all of them
    • Compound exceptions store the original exceptions with with_traceback(None) called on them
    • Should inspect() have a fail_fast argument?
  • Give each dist-info metadata class a "defects" field, and give the Inspection class both its own "defects" field for wheel-level defects and a get_all_defects() method
    • Try to salvage as much information as possible from malformed RECORDs #13
    • The defects will have to be included in the output of for_json(), which will mean changing the return structure of Record.for_json()

• Inspection:

  • Rename WHEEL_SCHEMA again to INSPECTION_SCHEMA? INSPECT_SCHEMA? Back to SCHEMA?
  • Error during inspection if data_dirname errors
  • Add an Inspection class for the return value of inspect()
    • Give it a classmethod for constructing an instance from JSONified inspection data
  • Move .derived.readme_renders to inside the .dist_info.metadata.description object?
    • Do likewise for the .derived.description_in_* fields?

• Make the wheel_inspect namespace re-export all exception classes from wheel_inspect/errors.py

• Make the following functions from wheel_inspect/util.py public:

  • is_dist_info_dir()
  • is_data_dir()
  • is_dist_info_path()
  • is_signature_file()
  • is_record_file()

• Tests:

  • Test .filetrees[Tree.PLATLIB] and .filetrees["platlib"] in a wheel with platlib
  • Test .filetrees[Tree.PURELIB] and .filetrees["purelib"] in a non-pure wheel with purelib
  • Test .filetrees[Tree.ROOT] and .filetrees[Tree.<root>LIB] in a wheel with an empty rootlib

• Documentation:

  • Document this project's definitions of the following terms:
    • "backed"/"backing"
    • "valid"
    • "verified"
  • Document example basic usage patterns
  • Document specification conformance
  • Add docstrings to all public items
  • Use https://pypi.org/project/sphinx-jsonschema/ to show WHEEL_SCHEMA in the documentation?
  • Give CLI a docstring/--help text
  • Add item about new library API to top of changelog section
  • Update README, docs/index.rst, and module docstring
  • Regenerate the sample output in the README and docs/index.rst
  • Set up a Read the Docs site
    • Add .readthedocs.yaml file
    • Add link to README header links
    • Add link to end of module docstring
    • Add project URL
    • Add entry to CHANGELOG