Metadata-Version: 2.4
Name: slotscheck
Version: 0.20.1
Summary: Ensure your __slots__ are working properly.
Author: Arie Bovenberg
Author-email: Arie Bovenberg <a.c.bovenberg@gmail.com>
License-Expression: MIT
Classifier: Typing :: Typed
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3
Requires-Dist: tomli>=0.2.6,<3.0.0 ; python_full_version < '3.11'
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/ariebovenberg/slotscheck
Project-URL: Repository, https://github.com/ariebovenberg/slotscheck
Description-Content-Type: text/x-rst

🎰 Slotscheck
=============

.. image:: https://img.shields.io/pypi/v/slotscheck.svg?color=blue
   :target: https://pypi.python.org/pypi/slotscheck

.. image:: https://img.shields.io/pypi/l/slotscheck.svg
   :target: https://pypi.python.org/pypi/slotscheck

.. image:: https://img.shields.io/pypi/pyversions/slotscheck.svg
   :target: https://pypi.python.org/pypi/slotscheck

.. image:: https://img.shields.io/readthedocs/slotscheck.svg
   :target: http://slotscheck.readthedocs.io/

.. image:: https://github.com/ariebovenberg/slotscheck/actions/workflows/build.yml/badge.svg
   :target: https://github.com/ariebovenberg/slotscheck/actions/workflows/build.yml

.. image:: https://img.shields.io/badge/coverage-100%25-forestgreen?style=flat-square

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 talk at EuroPython <https://www.youtube.com/watch?v=87DoVbgtuRA>`_
for the details of how slots work and what can go wrong with them.

Quickstart
----------

Usage is quick from the command line:

.. code-block:: bash

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

For example:

.. code-block:: bash

   $ 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 <https://slotscheck.rtfd.io/en/latest/advanced.html#pre-commit-hook>`_
to prevent mistakes from creeping in again!
See `here <https://github.com/Instagram/LibCST/pull/615>`__ and
`here <https://github.com/dry-python/returns/pull/1233>`__ for examples.

Features
--------

- Detect broken slots inheritance
- Detect overlapping slots
- Detect duplicate slots
- `Pre-commit <https://slotscheck.rtfd.io/en/latest/advanced.html#pre-commit-hook>`_ hook
- (Optionally) enforce the use of slots

See `the documentation <https://slotscheck.rtfd.io>`_ 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 <https://github.com/ariebovenberg/slotscheck/issues/6>`_
to discuss the matter.

Why not pylint or ruff?
-----------------------

Pylint and Ruff do have some checks related to ``__slots__``, but they are
still static analyzers.
They cannot see slots that are computed at import time—or follow deep
inheritance trees, which are common in real code.
People often generate slots automatically when optimizing class hierarchies,
and frameworks like ``dataclasses``, ``attrs``, and ``pydantic`` also generate
slots for you.
``slotscheck`` runs the code and inspects the resulting class tree, and it can
also detect unused slots.
Ruff and Pylint can still catch some more basic slot mistakes, such as invalid
``__slots__`` declarations.

Notes
-----

- ``slotscheck`` does not work on alternative Python implementations
  such as PyPy, Jython, or IronPython. This is for two reasons:

  1. Other implementations such as PyPy handle slots differently,
     and running slotscheck wouldn't be useful.
  2. To perform its checks, ``slotscheck`` uses CPython-specific features

- ``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 <https://github.com/ariebovenberg/slotscheck/issues/178>`_.
  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 <https://github.com/ariebovenberg/slotscheck/issues/270>`_.

Installation
------------

It's available on PyPI.

.. code-block:: bash

  pip install slotscheck
