{"author":null,"author_email":"John Thorvald Wodder II ","bugtrack_url":null,"classifiers":["Environment :: Console","Intended Audience :: Developers","Programming Language :: Python :: 3","Programming Language :: Python :: 3 :: Only","Programming Language :: Python :: 3.10","Programming Language :: Python :: 3.11","Programming Language :: Python :: 3.12","Programming Language :: Python :: 3.13","Programming Language :: Python :: Implementation :: CPython","Programming Language :: Python :: Implementation :: PyPy","Topic :: Software Development :: Build Tools","Topic :: Software Development :: Libraries :: Python Modules","Topic :: Software Development :: Quality Assurance"],"description":"|repostatus| |ci-status| |coverage| |pyversions| |license|\n\n.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg\n :target: https://www.repostatus.org/#active\n :alt: Project Status: Active — The project has reached a stable, usable\n state and is being actively developed.\n\n.. |ci-status| image:: https://github.com/jwodder/check-wheel-contents/actions/workflows/test.yml/badge.svg\n :target: https://github.com/jwodder/check-wheel-contents/actions/workflows/test.yml\n :alt: CI Status\n\n.. |coverage| image:: https://codecov.io/gh/jwodder/check-wheel-contents/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/check-wheel-contents\n\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/check-wheel-contents.svg\n :target: https://pypi.org/project/check-wheel-contents/\n\n.. |license| image:: https://img.shields.io/github/license/jwodder/check-wheel-contents.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub `_\n| `PyPI `_\n| `Issues `_\n| `Changelog `_\n\nGetting the right files into your wheel is tricky, and sometimes we mess up and\npublish a wheel containing ``__pycache__`` directories or ``tests/``. Do we\nhave to manually check the contents of every wheel we build before uploading it\nto PyPI? How about letting this program check for you? Just run\n``check-wheel-contents`` on your wheel, and it'll fail and notify you if any of\nseveral common errors & mistakes are detected. The errors are described below,\nalong with common causes and corresponding fixes.\n\nInstallation\n============\n``check-wheel-contents`` requires Python 3.10 or higher. Just use `pip\n`_ for Python 3 (You have pip, right?) to install\n``check-wheel-contents`` and its dependencies::\n\n python3 -m pip install check-wheel-contents\n\n\nUsage\n=====\n\n::\n\n check-wheel-contents [] ...\n\n``check-wheel-contents`` takes zero or more paths as arguments, each pointing\nto either a wheel to analyze or a directory that will be traversed for wheels\nto analyze. If a given wheel fails any checks, a message will be printed for\neach check along with (if applicable) a list of filepaths in the wheel causing\nthe check to fail, and the command will exit with a nonzero status. If a wheel\npasses all checks, the program will print ``{path_to_wheel}: OK``.\n\nOptions\n-------\n\n-c FILE, --config FILE Read configuration from the given file; see below for\n more information\n\n--no-config Disable reading from the configuration file\n\n-h, --help Display a usage message and exit\n\n-V, --version Display the program version and exit\n\nThe remaining options can be given either on the command line or in the\nconfiguration file; see \"`Configuration Options`_\" for more information.\n\n\nConfiguration\n=============\n\nConfiguration File\n------------------\n\nIf a configuration file is specified on the command line with the ``--config``\noption, ``check-wheel-contents`` reads its configuration from the given file.\nFiles with a ``.toml`` extension are parsed as TOML files, and the\nconfiguration is read from the ``tool.check-wheel-contents`` table. All other\nfiles are parsed as INI files, and their configuration is read from the\n``[check-wheel-contents]`` section (unless the file is named ``setup.cfg``, in\nwhich case the section ``[tool:check-wheel-contents]`` is used instead).\n\nIf no configuration file is specified on the command line, the program begins\nsearching for a file named ``pyproject.toml``, ``tox.ini``, ``setup.cfg``,\n``check-wheel-contents.cfg``, or ``.check-wheel-contents.cfg``, starting in the\ncurrent directory and going up. The files are read using the same rules as for\nthe ``--config`` option, and the first file in the list that contains the\nappropriate section is used. Searching stops once a directory containing any\nof the named files is found, even if none of them contain the relevant section.\n\nConfiguration Options\n---------------------\n\nThe following options may be set either on the command line or in the\nconfiguration file. Settings given on the command line override those in the\nconfiguration file. Unknown keys in configuration files are ignored.\n\n``--select `` / ``select = ``\n Select/enable only the given checks. ```` is a comma-separated list\n of check IDs and/or check ID prefixes (to select all checks beginning with\n the given prefixes).\n\n In a TOML file, ```` may alternatively be given as a list of\n strings.\n\n By default, all checks are selected (though some checks are no-ops when\n certain other options are/aren't given).\n\n``--ignore `` / ``ignore = ``\n Ignore/skip the given checks. ```` is a comma-separated list of\n check IDs and/or check ID prefixes (to ignore all checks beginning with the\n given prefixes).\n\n In a TOML file, ```` may alternatively be given as a list of\n strings.\n\n By default, no checks are ignored.\n\n``--toplevel `` / ``toplevel = ``\n Tell ``check-wheel-contents`` to check that the toplevel library entries of\n the wheel equal the set of names in the comma-separated list ````;\n e.g., ``--toplevel foo.py,bar/`` checks that ``foo.py``, ``bar``, and\n nothing else is at the top level of your wheel. Trailing slashes on\n directory names are optional.\n\n In a TOML file, ```` may alternatively be given as a list of strings.\n\n This option disables check W009 and enables checks W201 and W202. It is\n also used by check W005 to prevent failure on common names that are\n intentionally used as toplevel names.\n\n``--package `` / ``package = ``\n Tell ``check-wheel-contents`` to check that the wheel's library sections\n contain the file tree rooted at ````.\n\n Paths given on the command line are resolved relative to the current working\n directory. Paths given in a configuration file are resolved relative to the\n directory containing the configuration file.\n\n On the command line, multiple paths can be specified by supplying\n ``--package`` multiple times. In a configuration file, multiple paths can\n be specified by setting ``package`` to a comma-separated list of paths. In\n a TOML file, ```` may alternatively be given as a list of strings.\n\n This option disables check W009 and enables checks W101 and W102.\n\n``--src-dir `` / ``src_dir = ``\n The same as ``--package``, except that only the contents of ````\n (which must be a directory) and not ```` itself are checked against\n the wheel's contents.\n\n``--package-omit `` / ``package_omit = ``\n Ignore files & directories inside ``--package`` or ``--src-dir`` arguments\n that match any of the glob patterns in the comma-separated list\n ````. Ignored files will not be looked for in wheels for check\n W101, and if any of them do show up in a wheel, it will cause check W102 to\n fail.\n\n In a TOML file, ```` may alternatively be given as a list of\n strings.\n\n The default set of ignored patterns is ``.*, CVS, RCS, *.pyc, *.pyo,\n *.egg-info``.\n\n\nChecks\n======\n\n**Note**: Unless otherwise stated, the common causes and their fixes listed\nhere are specific to projects developed using setuptools. Users of other tools\nlike flit and poetry will have to consult those projects' documentation in\norder to resolve failed checks.\n\n**Note**: When rebuilding a wheel with setuptools, it is a good idea to delete\nthe ``build/`` directory first. (This can be done in a single command with\n``python setup.py clean --all bdist_wheel``.) Not doing this can cause various\nchecks to continue to fail or new ones to start failing.\n\n\nW001 — Wheel contains .pyc/.pyo files\n-------------------------------------\nThis check fails if there are any files in the wheel with a ``.pyc`` or\n``.pyo`` extension. Such files are compiled Python bytecode files, and they do\nnot belong in wheels, because (a) they are platform-specific and thus useless\nto many of your users, and (b) pip generates ``.pyc`` files for the ``.py``\nfiles in your wheel automatically.\n\nCommon causes:\n\n- You have ``include_package_data`` set to ``True``, your ``MANIFEST.in``\n contains ``graft packagename`` or ``recursive-include packagename *``, and\n the line ``global-exclude *.py[co]`` or similar is either missing from the\n ``MANIFEST.in`` or else in the wrong location.\n\n **Solution**: Ensure that ``global-exclude *.py[co]`` appears in your\n ``MANIFEST.in`` file *after* all ``include``, ``recursive-include``,\n ``global-include``, and ``graft`` commands.\n\n- You have ``[install]optimize = 1`` set in ``setup.cfg`` (or, equivalently,\n ``options={\"install\": {\"optimize\": \"1\"}}`` set in ``setup.py``).\n\n **Solution**: Remove this setting. It's only useful when using ``setup.py\n install`` anyway, which is deprecated.\n\n\nW002 — Wheel contains duplicate files\n-------------------------------------\nThis check fails if any two files in the wheel have the same contents. Common\nfile contents, such as files that are empty or just contain the line \"``# -*-\ncoding: utf-8 -*-``\", are excluded from this check.\n\nCommon causes:\n\n- *(Build tool agnostic)* You copied a file or directory when you actually\n meant to rename it.\n\n **Solution**: Delete the original copy of the file or directory.\n\n- You built a wheel, renamed a file or directory, and then built a wheel again\n without first deleting the ``build/`` directory.\n\n **Solution**: Delete the ``build/`` directory and build the wheel again.\n\n\nW003 — Wheel contains non-module at library toplevel\n----------------------------------------------------\nThis check fails if there are any files at the root of the purelib or platlib\nsection of the wheel that are not Python modules or ``.pth`` files.\nNon-modules belong elsewhere in a wheel:\n\n- Licenses and similar notices should be stored in the wheel's ``*.dist-info``\n directory using ``wheel``'s ``license_files`` option.\n\n- Package data/resource files belong inside a package directory so that they\n can be located with ``pkg_resources`` or ``importlib-resources``.\n\n- A project's ``README`` should already be used as the project's\n ``long_description``, in which case the text of the ``README`` is already\n included in the wheel inside the ``*.dist-info/METADATA`` file. There should\n thus be no need to store the ``README`` in the wheel's library sections.\n\n\nW004 — Module is not located at importable path\n-----------------------------------------------\nThis check fails if there are any Python modules in the purelib or platlib\nsection of the wheel that cannot be imported due to one or more of their path\ncomponents being invalid Python identifiers.\n\nCommon causes:\n\n- *(Build tool agnostic)* You gave a package directory or module a name\n containing a hyphen or other character not allowed in Python identifiers.\n\n **Solution**: Rename the offending directory or module to remove the\n offending character, most likely by changing it to an underscore.\n\n- *(Build tool agnostic)* You gave a package directory or module the name of a\n Python keyword.\n\n **Solution**: Rename the offending directory or module.\n\n- *(Build tool agnostic)* Your package contains database migration files\n generated by alembic or Django, which (may) begin with numbers and thus do\n not have valid Python identifiers as names.\n\n **Solution**: Ignore this check. (Ignoring checks only for specific files is\n not yet implemented.)\n\n\nW005 — Wheel contains common toplevel name in library\n-----------------------------------------------------\nThis check fails if there are any files or directories named ``.eggs``,\n``.nox``, ``.tox``, ``.venv``, ``app``, ``build``, ``cli``, ``data``, ``dist``,\n``doc``, ``docs``, ``example``, ``examples``, ``lib``, ``scripts``, ``src``,\n``test``, ``tests``, or ``venv`` located at the root of the purelib or platlib\nsection of the wheel. These names are conventionally used for directories that\ndon't belong in wheels (aside from ``src``, whose contents belong in wheels but\nitself does not belong in a wheel). Projects should only use toplevel names\nthat resemble the project name; using common names will cause different\nprojects' files to overwrite each other on installation.\n\nIf the ``--toplevel`` option is set, the names listed in the option will not\ncause this check to fail.\n\nCommon causes:\n\n- For ``src``: You failed to set up your ``src/`` layout correctly. ``src``\n should not contain an ``__init__.py`` file, ``where='src'`` needs to be\n passed to ``setuptools.find_packages()`` in ``setup.py``, and\n ``package_dir={\"\": \"src\"}`` needs to be passed to ``setup()`` in\n ``setup.py``.\n\n- For directories other than ``src``: The directory contains an ``__init__.py``\n file, and the directory is not listed in the ``exclude`` argument to\n ``setuptools.find_packages()`` in ``setup.py``.\n\n **Solution**: Include ``'DIRNAME'`` and ``'DIRNAME.*'`` in the list passed to\n the ``exclude`` argument of ``find_packages()``.\n\n- For directories other than ``src``: The directory is listed in the\n ``exclude`` argument to ``find_packages()``, but ``'DIRNAME.*'`` is not, and\n a subdirectory of the directory contains an ``__init__.py`` file.\n\n **Solution**: Include ``'DIRNAME.*'`` in the list passed to the ``exclude``\n argument of ``find_packages()``.\n\n- You actually want to include your tests or examples in your wheel.\n\n **Solution**: Move the tests or whatever to inside your main package\n directory (e.g., move ``tests/`` to ``somepackage/tests/``) so that they\n won't collide with other projects' files on installation.\n\n- You are actually making a package whose name is one of the listed names.\n\n **Solution**: Include the name of your package in the ``--toplevel`` option\n so that ``check-wheel-contents`` knows it's meant to be there.\n\n\nW006 — ``__init__.py`` at top level of library\n----------------------------------------------\nThis check fails if there is a file named ``__init__.py`` at the root of the\npurelib or platlib section of the wheel. ``__init__.py`` files only belong\ninside package directories, not at the root of an installation.\n\nCommon causes:\n\n- You failed to set up your ``src/`` layout correctly. ``src`` should not\n contain an ``__init__.py`` file, ``where='src'`` needs to be passed to\n ``setuptools.find_packages()`` in ``setup.py``, and ``package_dir={\"\":\n \"src\"}`` needs to be passed to ``setup()`` in ``setup.py``.\n\n- You created an ``__init__.py`` file at the root of your project and set\n ``packages='.'`` in ``setup.py``.\n\n **Solution**: Configure your project's packages correctly. For single-file\n modules, pass a list of their names (without the ``.py`` extension) to the\n ``py_modules`` argument to ``setup()``. For package modules (directories),\n pass a list of their names and the dotted names of their descendant\n subpackages (possibly obtained by calling ``setuptools.find_packages()``) to\n ``packages``.\n\n\nW007 — Wheel library is empty\n-----------------------------\nThis check fails if the wheel contains no files in either its purelib or\nplatlib section.\n\nCommon causes:\n\n- Your project consists of a single-file ``.py`` module, but you declared it to\n ``setup()`` in ``setup.py`` using the ``packages`` keyword.\n\n **Solution**: Single-file modules must be declared to ``setup()`` using the\n ``py_modules`` keyword. Pass it a list of the names of your single-file\n modules without the ``.py`` extension.\n\n- You are using ``setuptools.find_packages()`` to list your packages for\n ``setup()``, but your package does not contain an ``__init__.py`` file.\n\n **Solution**: Create an ``__init__.py`` file in your package. If this is not\n an option because you are building a namespace package, use\n ``setuptools.find_namespace_packages()`` instead of ``find_packages()``. Be\n sure to set the arguments appropriately so that the function only finds your\n main package; `see the documentation for further information`__.\n\n__ https://setuptools.pypa.io/en/latest/userguide/package_discovery.html\n #finding-namespace-packages\n\n- You're deliberately creating a wheel that only contains scripts, headers, or\n other data files.\n\n **Solution**: Ignore this check.\n\n\nW008 — Wheel is empty\n---------------------\nThis check fails if the wheel contains no files other than the ``*.dist-info``\nmetadata directory. It is a stronger check than W007, intended for users who\nare creating wheels that only contain scripts, headers, and other data files\nand thus need to ignore W007.\n\nCommon causes:\n\n- Same causes as for W007\n\n- You're deliberately creating an empty wheel whose only function is to cause a\n set of dependencies to be installed.\n\n **Solution**: Ignore this check.\n\n\nW009 — Wheel contains multiple toplevel library entries\n-------------------------------------------------------\nThis check fails if the wheel's purelib and platlib sections contain more than\none toplevel entry between them, excluding ``.pth`` files and files &\ndirectories that begin with an underscore. This is generally a sign that\nsomething has gone wrong in packaging your project, as very few projects want\nto distribute code with multiple top-level modules or packages.\n\nThis check is disabled if the ``--toplevel``, ``--package``, or ``--src-dir``\noption is given either on the command line or in the configuration file.\n\nCommon causes:\n\n- You built a wheel, renamed a toplevel file or directory, and then built a\n wheel again without first deleting the ``build/`` directory.\n\n **Solution**: Delete the ``build/`` directory and build the wheel again.\n\n- You are using ``setuptools.find_packages()`` in your ``setup.py``, your\n project contains multiple directories with ``__init__.py`` files, and one or\n more of these directories (other than your main package) is not listed in the\n ``exclude`` argument to ``find_packages()``.\n\n **Solution**: Pass a list of all ``__init__.py``-having directories in your\n project other than your main package to the ``exclude`` argument of\n ``find_packages()``. For proper exclusion, each directory ``DIRNAME`` should\n correspond to two elements of this list, ``'DIRNAME'`` and ``'DIRNAME.*'``,\n in order to ensure that the directory and all of its subdirectories are\n excluded.\n\n- You are deliberately creating a wheel with multiple top-level Python modules\n or packages.\n\n **Solution**: Use the ``--toplevel`` option to let ``check-wheel-contents``\n know what toplevel entries to expect.\n\n\nW010 — Toplevel library directory contains no Python modules\n------------------------------------------------------------\nThis check fails if a directory tree rooted at the root of the purelib or\nplatlib section of the wheel contains no Python modules. ``*-stubs``\ndirectories are excluded from this check.\n\n\nW101 — Wheel library is missing files in package tree\n-----------------------------------------------------\nThis check is only enabled if the ``--package`` or ``--src-dir`` option is set.\nThis check fails if a path in a tree rooted at an argument to ``--package`` or\ninside an argument to ``--src-dir`` does not appear in the wheel's purelib or\nplatlib section. Empty directories and local files & directories that match\nany of the patterns specified with ``--package-omit`` or its default value are\nexcluded from this check.\n\nNote that this check only checks file paths, i.e., names of files &\ndirectories. File contents are not examined.\n\nFor example, given the below local tree::\n\n /usr/src/project/\n ├── foo/\n │ ├── .gitignore\n │ ├── __init__.py\n │ └── foo.py\n └── src/\n ├── bar/\n │ ├── __init__.py\n │ ├── bar.py\n │ ├── empty/\n │ └── quux/\n │ └── data.dat\n └── bar.egg-info/\n └── PKG-INFO\n\nIf the options ``--package /usr/src/project/foo`` and ``--src-dir\n/usr/src/project/src`` are supplied and ``--package-omit`` is left at its\ndefault value, then ``check-wheel-contents`` will look for the following paths\nin the wheel, and the check will fail if any of them do not appear in either\nthe purelib or platlib section::\n\n foo/__init__.py\n foo/foo.py\n bar/__init__.py\n bar/bar.py\n bar/quux/data.dat\n\nNote that ``foo/.gitignore`` and ``src/bar.egg-info`` are omitted from this\ncheck (and if they do appear in the wheel, it will cause check W102 to fail).\nEmpty directories are ignored altogether.\n\nCommon causes:\n\n- For Python files: You failed to pass all of your project's packages &\n subpackages to ``setup()``'s ``packages`` argument. If you are using\n ``setuptools.find_packages()``, all of your packages & subpackages need to\n contain ``__init__.py`` files.\n\n- For non-Python files: You failed to declare your project's package data\n appropriately. `See the setuptools documentation for information on how to\n do this`__.\n\n__ https://setuptools.pypa.io/en/latest/userguide/datafiles.html\n\n\nW102 — Wheel library contains files not in package tree\n-------------------------------------------------------\nThis check is only enabled if the ``--package`` or ``--src-dir`` option is set.\nThis check fails if the purelib or platlib section of the wheel contains any\nfiles at paths that do not exist in any of the file trees specified with\n``--package`` or ``--src-dir``.\n\nNote that this check only checks file paths, i.e., names of files &\ndirectories. File contents are not examined.\n\nFor example, given the local tree and options shown in the example under W101,\nthis check will fail if the wheel contains any files in its purelib or platlib\nsection other than the following::\n\n foo/__init__.py\n foo/foo.py\n bar/__init__.py\n bar/bar.py\n bar/quux/data.dat\n\nNote that files & directories that match any of the patterns specified with\n``--package-omit`` or its default value are ignored in local trees, and so any\nentries with those names in the wheel will cause this check to fail. Empty\ndirectories are ignored altogether.\n\nCommon causes: See common causes of W009\n\n\nW201 — Wheel library is missing specified toplevel entry\n--------------------------------------------------------\nThis check is only enabled if the ``--toplevel`` option is set. This check\nfails if one or more of the names given in the ``--toplevel`` option does not\nappear at the root of the purelib or platlib section of the wheel.\n\nCommon causes: See common causes of W007\n\n\nW202 — Wheel library has undeclared toplevel entry\n--------------------------------------------------\nThis check is only enabled if the ``--toplevel`` option is set. This check\nfails if there is a file or directory at the root of the purelib or platlib\nsection of the wheel that is not listed in the ``--toplevel`` option.\n``*.pth`` files are ignored for the purposes of this check.\n\nCommon causes: See common causes of W009\n","description_content_type":"text/x-rst","docs_url":null,"download_url":null,"downloads":{"last_day":-1,"last_month":-1,"last_week":-1},"dynamic":null,"home_page":null,"keywords":"linter, packaging, wheel","license":null,"license_expression":"MIT","license_files":["LICENSE"],"maintainer":null,"maintainer_email":null,"name":"check-wheel-contents","package_url":"https://pypi.org/project/check-wheel-contents/","platform":null,"project_url":"https://pypi.org/project/check-wheel-contents/","project_urls":{"Bug Tracker":"https://github.com/jwodder/check-wheel-contents/issues","Source Code":"https://github.com/jwodder/check-wheel-contents"},"provides_extra":null,"release_url":"https://pypi.org/project/check-wheel-contents/0.6.2/","requires_dist":["attrs>=18.1","backports-cached-property; python_version < \"3.8\"","click~=8.2","packaging","pydantic~=2.0","tomli<3.0,>=1.2; python_version < \"3.11\"","wheel-filename~=1.1"],"requires_python":">=3.10","summary":"Check your wheels have the right contents","version":"0.6.2","yanked":false,"yanked_reason":null}

Dependency	Optional
attrs	false
backports-cached-property	false
click	false
packaging	false
pydantic	false
tomli	false
wheel-filename	false

Package search

check-wheel-contents

project_urls

Dependencies

All package metadata

Releases