🎰 Slotscheck

Adding __slots__ to a class in Python is a great way to improve performance. But to work properly, all base classes need to implement it — without overlap! It’s easy to get wrong, and what’s worse: there is nothing warning you that you messed up.

✨ Until now! ✨

slotscheck helps you validate your slots are working properly. You can even use it to enforce the use of slots across (parts of) your codebase.

See my blog post for the origin story behind slotscheck.

Quickstart

Usage is quick from the command line:

python -m slotscheck [FILES]...
# or
slotscheck -m [MODULES]...

For example:

$ slotscheck -m sanic
ERROR: 'sanic.app:Sanic' defines overlapping slots.
ERROR: 'sanic.response:HTTPResponse' has slots but superclass does not.
Oh no, found some problems!
Scanned 72 module(s), 111 class(es).

Now get to fixing — and add slotscheck to your CI pipeline or pre-commit to prevent mistakes from creeping in again! See here and here for examples.

Features

• Detect broken slots inheritance

• Detect overlapping slots

• Detect duplicate slots

• Pre-commit hook

• (Optionally) enforce the use of slots

See the documentation for more details and configuration options.

Why not a flake8 plugin?

Flake8 plugins need to work without running the code. Many libraries use conditional imports, star imports, re-exports, and define slots with decorators or metaclasses. This all but requires running the code to determine the slots and class tree.

There’s an issue to discuss the matter.

Notes

• slotscheck will try to import all submodules of the given package. If there are scripts without if __name__ == "__main__": blocks, they may be executed.

• Even in the case that slots are not inherited properly, there may still be an advantage to using them (i.e. attribute access speed and some memory savings). However, in most cases this is unintentional. slotscheck allows you to ignore specific cases.

• Because slotscheck imports your code in arbitrary order, it can—in rare cases—result in confusing and randomly-occurring import errors in third-party libraries. In such a case, it is recommended to omit modules such as your tests and mypy plugins from the slotscheck run. See here. Alternatively, you can use PYTHONHASHSEED=<any value> to make the import order deterministic. A solution to this problem is being worked on in this issue.

Installation

It’s available on PyPI.

pip install slotscheck

Contents

• Command line interface
  • slotscheck
• Configuration
  • Command line options
  • Configuration file
• Errors and violations
  • Superclass has no slots
  • Overlapping slots
  • Duplicate slots
• Module discovery
• Advanced topics
  • Pre-commit hook

Changelog

0.19.1 (2024-10-19)

• Explicit Python 3.13 support, drop Python 3.8 support

• Documentation improvements

0.19.0 (2024-03-25)

• Improved support for implicit/native namespace packages (#228, #230)

0.18.0 (2024-03-21)

• Improved robustness of importing of namespace packages and built-in modules (#227)

0.17.3 (2024-02-04)

• Fix packaging metadata issue where README/CHANGELOG were installed to the wrong location.

0.17.2 (2024-02-04)

• Remove Python upper version constraint in package metadata

0.17.1 (2023-11-03)

• Fixed Generic false positive in Python 3.12+ (#201).

• Remove pkgutil deprecation warning on Python 3.12+.

• Official Python 3.12 support.

0.17.0 (2023-07-31)

• Drop Python 3.7 support.

• Remove typing-extensions and importlib_metadata dependencies.

• More robust checks to prevent Protocol false positives.

0.16.5 (2023-03-01)

• Don’t flag TypedDict from typing_extensions in Python versions where typing has TypedDict itself.

0.16.4 (2023-01-13)

• Remove tomli dependency on Python 3.11+

0.16.3 (2023-01-03)

• Fix broken Protocol import due to absent typing_extensions on Python <3.10.

0.16.2 (2022-12-29)

• Don’t flag Protocol classes as needing slots if strict require-subclass option is enabled.

0.16.1 (2022-11-21)

• Don’t flag TypedDict subclasses as missing slots (#120).

0.16.0 (2022-11-01)

Breaking changes

• The “strict-imports” default value was mistakenly False in contrast to what is documented. The default value is now True, in line with documentation. If you were relying on this permissive import behavior, you will need to set this option in the CLI or settings file.

• Drop Python 3.6 support

Bugfixes

• Disabling “strict-imports” now also gracefully handles failed imports of the root module given (#113).

Features

• Add official Python 3.11 support

0.15.0 (2022-08-09)

• Fix error when encountering metaclass with slots (#106)

• Improved detection of immutable classes on Python 3.10+ (#92)

0.14.1 (2022-06-26)

• Gracefully handle inspection failure due to unimportable parent package (#90).

0.14.0 (2022-02-27)

• Improved robustness of importing implicitly namespaced and extension packages (#64)

0.13.0 (2022-02-26)

• Improved robustness of determining whether a class is pure Python (#65)

0.12.1 (2022-02-12)

• Add helpful link to ‘failed to find module’ message.

0.12.0 (2022-02-06)

• Support setup.cfg as alternate settings file (#52).

0.11.0 (2022-02-05)

• Explicitly prevent ambiguous imports (#51).

0.10.2 (2022-01-30)

• Correctly handle case when __slots__ is defined as a single string (#47).

0.10.1 (2022-01-30)

• Small improvements to verbose error messages.

0.10.0 (2022-01-29)

• Detect duplicate slots (#21).

• Improvements to docs.

• Clarify pre-commit usage (#45).

0.9.0 (2022-01-25)

• Support specifying the location of settings file with --settings option.

• Improved verbose error messages.

0.8.0 (2022-01-21)

• Extension modules are now traversed.

• Small tweaks to documentation.

0.7.2 (2022-01-18)

• Recommend running as python -m slotscheck when checking files. Update pre-commit hook to reflect this.

0.7.1 (2022-01-18)

• Add Python 3.6 support

0.7.0 (2022-01-18)

Breaking changes

• Strict imports are now the default

• Include/exclude regex patterns now use partial patch (like mypy, isort do).

Adjustments

• Clarifications in documentation

• Pre-commit hook uses verbose mode by default

0.6.0 (2022-01-17)

Breaking changes

• Arguments are now file paths. Use the -m/--module option to scan modules.

Features

• Support use as pre-commit hook.

• Multiple modules or files allowed as input.

• Document the types of slot errors.

0.5.3 (2022-01-14)

• Fix typo in readme.

0.5.2 (2022-01-14)

• Fix crash when encountering overlapping slots from multiple classes.

0.5.1 (2022-01-14)

• Relax tomli dependency pin.

0.5.0 (2022-01-14)

• More descriptive output on overlapping slots (#26).

• Simplify slot requirement flags.

• allow configuration by pyproject.toml (#28).

0.4.0 (2022-01-12)

• Recognize builtin exceptions as not having slots.

• Split --exclude-modules and exclude-classes.

• Add flags to specify inclusion as well as exclusion of modules/classes.

• Allow disabling slot inheritance check.

• Add --require-slots option.

0.3.1 (2022-01-10)

• Catch BaseException in module import.

0.3.0 (2022-01-10)

• Add --strict-imports flag (#24)

• Detect overlapping slots (#10)

• 100% test coverage (#15)

• Add --exclude flag (#9)

0.2.1 (2022-01-04)

• Improved error message if module cannot be found (#18)

0.2.0 (2022-01-03)

• Enable running with -m slotscheck (#13)

0.1.2 (2022-01-03)

• Skip __main__.py in module scan to prevent running unintented code

0.1.1 (2022-01-03)

• Improve output report

0.1.0 (2021-12-30)

• Improve documentation

0.0.1 (2021-12-29)

• Initial release

Indices and tables

• Index

• Module Index

• Search Page