Check Reference
This page describes each of the checks that pydistcheck
performs.
The section headings correspond to the error codes printed in pydistcheck
’s output.
compiled-objects-have-debug-symbols
The distribution contains compiled objects, like C/C++ shared libraries, with debug symbols.
Compilers for languages like C, C++, Fortran, and Rust can optionally include additional information like source code file names and line numbers, and other information useful for printing stack traces or enabling interactive debugging.
The inclusion of such information can increase the size of built objects substantially.
It’s pydistcheck
’s position that the inclusion of such debug symbols in a shared library distributed as part of Python wheel is rarely desirable, and that by default wheels shouldn’t include that type of information.
This check attempts to run the following tools with subprocess.run()
.
dsymutil
llvm-nm
llvm-objdump
nm
objdump
readelf
Installing more of these in the environment where you run pydistcheck
improves its ability to detect debug symbols.
Warning
If pydistcheck
invoking these other tools with subprocess.run()
is a concern for you (for example, if it causes permissions-related issues),
turn this check off by passing it to --ignore
.
For a LOT more information about this topic, see these discussions in other open source projects.
“(scikit-image) Add linker flags to strip debug symbols during wheel building “
“(scylladb/python-driver) scylla-driver is 100 times larger than cassandra-driver”
And these other resources.
distro-too-large-compressed
The package distribution is larger (compressed) than the allowed size.
Change that limit using configuration option max-distro-size-compressed
.
distro-too-large-uncompressed
The package distribution is larger (uncompressed) than the allowed size.
Change that limit using configuration option max-distro-size-uncompressed
.
files-only-differ-by-case
The package distribution contains filepaths which are identical after lowercasing.
Such paths are not portable, as some filesystems (notably macOS), are case-insensitive.
mixed-file-extensions
Filepaths in the package distribution use a mix of file extensions for the same type of file.
For example, some_file.yaml
and other_file.yml
.
Some programs may use file extensions, instead of more reliable mechanisms like magic bytes to detect file types, like this:
if filepath.endswith(".yaml"):
In such cases, having a mix of file extensions can lead to only a subset of relevant files being matched.
Standardizing on a single extension for files of the same type improves the probability of either catching or completely avoiding such bugs… either all intended files will be matched or none will.
path-contains-non-ascii-characters
At least one filepath in the package distribution contains non-ASCII characters.
Non-ASCII characters are not portable, and their inclusion in filepaths can lead to installation and usage issues on different platforms.
For more information, see:
path-contains-spaces
At least one filepath in the package distribution contains spaces.
Filepaths with spaces require special treatment, like quoting in some settings. Avoiding paths with spaces eliminates a whole class of potential issues related to software that doesn’t handle such paths well.
For more information, see:
too-many-files
The package distribution contains more than the allowed number of files.
This is a very very rough way to detect that unexpected files have been included in a new release of a project.
pydistcheck
defaults to raising this error when a distribution has more than 2000 files…a totally arbitrary number chosen by the author.
To change that limit, use configuration option max-allowed-files
.
unexpected-files
Files were found in the distribution which weren’t expected to be included.
With pydistcheck
’s default settings, this check raises errors for the inclusion of files that are commonly found in source control during development but are not useful in distributions, like .gitignore
.
Which files are “expected” is highly project-specific.
See Configuration for a list of the files pydistcheck
complains about by default, and for information about how to customize that list.