tessl/pypi-check-wheel-contents
Tool for validating Python wheel contents to detect common packaging errors and ensure proper distribution structure
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
validation.mddocs/
Validation System
Comprehensive validation system with configurable checks for common wheel packaging issues. Supports built-in checks (W001-W202) covering bytecode files, duplicates, module placement, library structure, and package completeness.
Capabilities
Wheel Validation
Main validation orchestrator that runs selected checks against wheel contents and reports failures with detailed diagnostic information.
class WheelChecker:
"""A class for performing various checks on a WheelContents instance"""
def __init__(self, selected: set[Check] | None = None,
toplevel: list[str] | None = None,
pkgtree: Directory | None = None):
"""
Initialize wheel checker.
Parameters:
- selected: Set of checks to run, or None for all checks
- toplevel: Expected toplevel library entries for W2 checks
- pkgtree: Expected package structure for W1 checks
"""
def configure_options(self, configpath=None, select: set[Check] | None = None,
ignore: set[Check] | None = None,
toplevel: list[str] | None = None,
package: tuple[str, ...] = (),
src_dir: tuple[str, ...] = (),
package_omit: list[str] | None = None) -> None:
"""
Configure checker options from various sources.
Parameters:
- configpath: Path to configuration file, or NO_CONFIG to disable
- select: Specific checks to enable
- ignore: Specific checks to disable
- toplevel: List of expected toplevel library entries
- package: Tuple of package paths to expect in wheel
- src_dir: Tuple of source directories to expect contents of
- package_omit: Patterns to omit when traversing package/src_dir
Raises:
- UserInputError: If configuration is invalid
"""
def check_contents(self, contents: WheelContents) -> list[FailedCheck]:
"""
Run all selected checks on wheel contents.
Parameters:
- contents: WheelContents instance to check
Returns:
List of FailedCheck instances for any failures
"""Check Types and Failures
Enumeration of all available validation checks and representation of check failures with diagnostic information.
class Check(Enum):
"""Enumeration of validation checks and their error messages"""
# Basic content checks
W001 = "Wheel contains .pyc/.pyo files"
W002 = "Wheel contains duplicate files"
W003 = "Wheel contains non-module at library toplevel"
W004 = "Module is not located at importable path"
W005 = "Wheel contains common toplevel name in library"
W006 = "__init__.py at top level of library"
W007 = "Wheel library is empty"
W008 = "Wheel is empty"
W009 = "Wheel contains multiple toplevel library entries"
W010 = "Toplevel library directory contains no Python modules"
# Package structure checks
W101 = "Wheel library is missing files in package tree"
W102 = "Wheel library contains files not in package tree"
# Toplevel specification checks
W201 = "Wheel library is missing specified toplevel entry"
W202 = "Wheel library has undeclared toplevel entry"
class FailedCheck:
"""A check that has failed"""
def __init__(self, check: Check, args: list[str] | None = None):
"""
Initialize failed check.
Parameters:
- check: The check that failed
- args: Relevant filepaths or other diagnostic information
"""
def show(self, filename: str | None = None) -> str:
"""
Format failure message for display.
Parameters:
- filename: Name of wheel being checked (optional)
Returns:
Formatted error message string
"""Check Parsing and Selection
Utilities for parsing check specifications from command-line and configuration files, supporting check names, prefixes, and ranges.
def parse_checks_string(s: str) -> set[Check]:
"""
Parse comma-separated check names and prefixes.
Parameters:
- s: Comma-separated string of check names/prefixes
Returns:
Set of Check instances
Raises:
- UserInputError: If any check name/prefix is invalid
"""
def parse_check_prefixes(prefixes: list[str]) -> set[Check]:
"""
Parse list of check names and prefixes.
Parameters:
- prefixes: List of check names and prefixes
Returns:
Set of Check instances
Raises:
- UserInputError: If any check name/prefix is invalid
"""
def parse_check_prefix(s: str) -> set[Check]:
"""
Parse single check name or prefix.
Parameters:
- s: Check name or prefix (e.g., "W001", "W1", "W")
Returns:
Set of matching Check instances
Raises:
- UserInputError: If check name/prefix is invalid
"""Usage Examples
from check_wheel_contents import WheelChecker, WheelContents
from check_wheel_contents.checks import Check, parse_checks_string
from check_wheel_contents.errors import UserInputError
# Create checker with default settings (all checks enabled)
checker = WheelChecker()
# Create checker with specific checks
selected_checks = {Check.W001, Check.W002, Check.W003}
checker = WheelChecker(selected=selected_checks)
# Configure from command-line style options
checker = WheelChecker()
try:
checker.configure_options(
select=parse_checks_string("W1,W2"), # Enable W1xx and W2xx checks
ignore=parse_checks_string("W005"), # Disable W005
toplevel=["mypackage", "mypackage.ext"]
)
except UserInputError as e:
print(f"Configuration error: {e}")
# Run checks on wheel
contents = WheelContents.from_wheel("dist/mypackage-1.0.0-py3-none-any.whl")
failures = checker.check_contents(contents)
# Process results
if failures:
print("Validation failures:")
for failure in failures:
print(f" {failure.show()}")
if failure.args:
for arg in failure.args:
print(f" - {arg}")
else:
print("All checks passed!")
# Check for specific issues
bytecode_failures = [f for f in failures if f.check == Check.W001]
if bytecode_failures:
print("Bytecode files found:")
for f in bytecode_failures:
for path in f.args:
print(f" {path}")
# Parse check specifications
try:
w1_checks = parse_checks_string("W1") # All W1xx checks
specific = parse_checks_string("W001,W005") # Specific checks
combined = parse_checks_string("W1,W201") # Mix of prefix and specific
except UserInputError as e:
print(f"Invalid check specification: {e}")Install with Tessl CLI
npx tessl i tessl/pypi-check-wheel-contents