check_dist._core

Core check-dist logic for checking Python source and wheel distributions.

Attributes

_PLATFORM_EXTENSION_MAP
_EXTENSION_DEFAULTS
_COMMON_SDIST_PRESENT
_COMMON_SDIST_ABSENT
_COMMON_WHEEL_ABSENT
_DEFAULT_DIST_DIRS
_HATCH_AUTO_INCLUDE_PATTERNS
_GENERATED_SDIST_FILES

Exceptions

CheckDistError

Error raised when distribution checks fail.

Functions

_get_platform_key(→ str)
translate_extension(→ str)	Translate file extensions to the current platform's convention.
_wrong_platform_extensions(→ list[str])	Return extensions that should NOT appear on the current platform.
load_config(→ dict)	Load [tool.check-dist] configuration from pyproject.toml.
load_hatch_config(→ dict)	Load [tool.hatch.build] configuration from pyproject.toml.
load_copier_config(→ dict)	Load .copier-answers.yaml from source_dir, if it exists.
_module_name_from_project(→ str)	Convert a human project name to a Python module name.
_normalize_name(→ str)	Normalize a name by stripping underscores, hyphens, and periods.
_resolve_module_from_hatch(→ str)	Resolve the module name from hatch packages configuration.
copier_defaults(→ dict | None)	Derive default check-dist config from copier answers.
_filter_extras_by_hatch(→ list[str])	Filter copier sdist_present_extra against the hatch sdist config.
build_dists(→ list[str])	Build sdist and wheel into output_dir.
find_dist_files(→ tuple[str | None, str | None])	Return (sdist_path, wheel_path) found in output_dir.
_find_pre_built(→ str | None)	Search default directories for pre-built distributions.
list_sdist_files(→ list[str])	List files inside an sdist, stripping the top-level directory.
list_wheel_files(→ list[str])	List files inside a wheel.
get_vcs_files(→ list[str])	Return files tracked by git in source_dir.
matches_pattern(→ bool)	Check whether filepath matches pattern.
_matches_hatch_pattern(→ bool)	Match a file path against a hatch include/exclude pattern.
check_present(→ list[str])	Return error strings for any patterns not found in files.
check_absent(→ list[str])	Return error strings for any patterns found in files.
check_wrong_platform_extensions(→ list[str])	Flag files that use an extension from another platform.
_is_hatch_auto_included(→ bool)	Return True if filename is a top-level file hatch auto-includes.
_sdist_expected_files(→ set[str])	Derive the set of VCS files we expect to see in the sdist,
check_sdist_vs_vcs(→ list[str])	Compare sdist contents against VCS-tracked files.
check_dist(→ tuple[bool, list[str]])	Run all distribution checks.

Module Contents

exception check_dist._core.CheckDistError

Bases: Exception

Error raised when distribution checks fail.

Initialize self. See help(type(self)) for accurate signature.

check_dist._core._PLATFORM_EXTENSION_MAP: dict[str, dict[str, str]]

check_dist._core._get_platform_key() → str

check_dist._core.translate_extension(pattern: str) → str

Translate file extensions to the current platform’s convention.

For example, if a user specifies *.so on Windows, this returns *.pyd.

check_dist._core._wrong_platform_extensions() → list[str]

Return extensions that should NOT appear on the current platform.

check_dist._core.load_config(pyproject_path: str | pathlib.Path = 'pyproject.toml', *, source_dir: str | pathlib.Path | None = None) → dict

Load [tool.check-dist] configuration from pyproject.toml.

If no [tool.check-dist] section exists and source_dir contains a .copier-answers.yaml with an add_extension key, sensible defaults are derived from the copier template answers.

check_dist._core.load_hatch_config(pyproject_path: str | pathlib.Path = 'pyproject.toml') → dict

Load [tool.hatch.build] configuration from pyproject.toml.

check_dist._core._EXTENSION_DEFAULTS: dict[str, dict]

check_dist._core._COMMON_SDIST_PRESENT = ['LICENSE', 'pyproject.toml', 'README.md']

check_dist._core._COMMON_SDIST_ABSENT = ['.copier-answers.yaml', 'Makefile', '.github', 'dist', 'docs', 'examples', 'tests']

check_dist._core._COMMON_WHEEL_ABSENT = ['.gitignore', '.copier-answers.yaml', 'Makefile', 'pyproject.toml', '.github', 'dist', 'docs',...

check_dist._core.load_copier_config(source_dir: str | pathlib.Path) → dict

Load .copier-answers.yaml from source_dir, if it exists.

check_dist._core._module_name_from_project(project_name: str) → str

Convert a human project name to a Python module name.

Replaces spaces and hyphens with underscores.

check_dist._core._normalize_name(name: str) → str

Normalize a name by stripping underscores, hyphens, and periods.

check_dist._core._resolve_module_from_hatch(module: str, hatch_config: dict) → str

Resolve the module name from hatch packages configuration.

If any package in the hatch sdist or wheel packages (or only-include) is equivalent to module after normalizing away underscores, hyphens, and periods, return that package name instead. This handles projects where the distribution name differs from the importable package name (e.g. jupyter-fs vs jupyterfs).

check_dist._core.copier_defaults(copier_config: dict, hatch_config: dict | None = None) → dict | None

Derive default check-dist config from copier answers.

Returns a config dict with the same shape as load_config output, or None if deriving defaults is not possible (no add_extension key, or unknown extension type).

When hatch_config is provided, sdist_present_extra patterns are filtered against the hatch sdist configuration to only require paths that will actually appear in the archive. Follows hatch precedence: only-include (exhaustive) > packages (used as only-include fallback) > include (filter on full tree).

check_dist._core._filter_extras_by_hatch(extras: list[str], hatch_config: dict) → list[str]

Filter copier sdist_present_extra against the hatch sdist config.

Uses the same precedence as hatchling: 1. only-include — exhaustive; keep extras that appear in the list. 2. packages (when no only-include) — acts as only-include

fallback; keep extras that appear in the list.

3. include — keep extras that match an include pattern.

4. force-include — destinations are always present; keep extras whose path appears as a force-include destination.

5. No constraints — keep everything.

check_dist._core.build_dists(source_dir: str, output_dir: str, *, no_isolation: bool = False) → list[str]

Build sdist and wheel into output_dir.

Returns a list of warnings (e.g. when only one dist type could be built).

check_dist._core.find_dist_files(output_dir: str) → tuple[str | None, str | None]

Return (sdist_path, wheel_path) found in output_dir.

check_dist._core._DEFAULT_DIST_DIRS = ['dist', 'wheelhouse']

check_dist._core._find_pre_built(source_dir: str) → str | None

Search default directories for pre-built distributions.

Checks dist/ and wheelhouse/ under source_dir. Returns the first directory that contains at least one sdist or wheel, or None.

check_dist._core.list_sdist_files(sdist_path: str) → list[str]

List files inside an sdist, stripping the top-level directory.

check_dist._core.list_wheel_files(wheel_path: str) → list[str]

List files inside a wheel.

check_dist._core.get_vcs_files(source_dir: str) → list[str]

Return files tracked by git in source_dir.

check_dist._core.matches_pattern(filepath: str, pattern: str) → bool

Check whether filepath matches pattern.

• A bare name like check_dist matches any file whose path starts with check_dist/.

• Glob wildcards (*, ?, […]) are matched against both the full path and the basename.

• Extensions are translated to the current platform before matching.

check_dist._core._matches_hatch_pattern(filepath: str, pattern: str) → bool

Match a file path against a hatch include/exclude pattern.

Hatch patterns may start with / (root-relative). Bare names match as either an exact file, a directory prefix, or any path component.

check_dist._core.check_present(files: list[str], patterns: list[str], dist_type: str) → list[str]

Return error strings for any patterns not found in files.

check_dist._core.check_absent(files: list[str], patterns: list[str], dist_type: str, *, present_patterns: list[str] | None = None) → list[str]

Return error strings for any patterns found in files.

When present_patterns is given, files nested inside a directory that matches a present pattern are not flagged. This avoids false positives like lerna/tests/fake_package/pyproject.toml being flagged as unwanted when lerna is a required present pattern.

check_dist._core.check_wrong_platform_extensions(files: list[str], dist_type: str) → list[str]

Flag files that use an extension from another platform.

check_dist._core._HATCH_AUTO_INCLUDE_PATTERNS = ['pyproject.toml', 'README*', 'LICENSE*', 'COPYING*', 'NOTICE*', 'AUTHORS*']

check_dist._core._is_hatch_auto_included(filename: str) → bool

Return True if filename is a top-level file hatch auto-includes.

check_dist._core._sdist_expected_files(vcs_files: list[str], hatch_config: dict) → set[str]

Derive the set of VCS files we expect to see in the sdist, taking [tool.hatch.build.targets.sdist] into account.

Follows hatchling’s precedence:

1. only-include is an exhaustive list of paths to walk.

2. If absent, packages is used as only-include (hatch fallback).

3. If neither is set and include is present, only files matching include patterns are kept.

4. exclude always removes files (except force-included ones).

5. force-include entries are always present regardless of other settings. Hatch also auto-force-includes pyproject.toml, .gitignore, README, and LICENSE files.

check_dist._core._GENERATED_SDIST_FILES

check_dist._core.check_sdist_vs_vcs(sdist_files: list[str], vcs_files: list[str], hatch_config: dict, sdist_absent: list[str] | None = None) → list[str]

Compare sdist contents against VCS-tracked files.

check_dist._core.check_dist(source_dir: str = '.', *, no_isolation: bool = False, verbose: bool = False, pre_built: str | None = None, rebuild: bool = False) → tuple[bool, list[str]]

Run all distribution checks.

Parameters:

• source_dir – Path to the project root.

• no_isolation – Passed to python -m build --no-isolation.

• verbose – List every file in each distribution.

• pre_built – If given, skip building and use existing dist files from this directory. Useful when native toolchains have already produced the archives.

• rebuild – Force a fresh build even when pre-built distributions exist in dist/ or wheelhouse/.

• ``(success (Returns) –

• messages)``.