Metadata-Version: 2.5
Name: impall
Version: 3.0.1
Summary: 🛎 Test-import all modules 🛎
Project-URL: Homepage, https://github.com/rec/impall
Project-URL: Repository, https://github.com/rec/impall
Project-URL: Documentation, https://rec.github.io/impall
Author-email: Tom Ritchford <tom@swirly.com>
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 🛎 Test-import all modules 🛎

Individually and separately imports each Python module or file in a project and
reports warnings or failures at the end.

### Running impall as a unit test

Just inherit from the base class and it will
automatically find and import each file, like this.

    import impall

    class ImpAllTest(impall.ImpAllTest):
        pass

(You can copy
[this file](https://github.com/rec/impall/blob/master/all_test.py)
into your project if you like.)

Tests are customized by overriding one of these following properties in the
derived class.

    CLEAR_SYS_MODULES, EXCLUDE, FAILING, INCLUDE, MODULES, PATHS,
    RAISE_EXCEPTIONS, and WARNINGS_ACTION.

For example, to turn warnings into errors, set the property
WARNINGS_ACTION in the derived class definition, like this.

    class ImpAllTest(impall.ImpAllTest):
        WARNINGS_ACTION = 'error'

## Running impall as a command-line utility

    $ impall --warnings_action=error
    $ impall -w error

The properties INCLUDE, EXCLUDE, and PATHS can be
lists of strings, or a string separated with colons like
'foo.mod1:foo.mod2'

INCLUDE and EXCLUDE match relative filesystem paths using `fnmatch`. Use the
platform path separator when providing a single string. For example,
`INCLUDE = 'src/*.py'` matches Python files directly beneath `src`.

### A note on side-effects

to reduce side-effects, `sys.modules` is restored to its original
condition after each import if CLEAR_SYS_MODULES is true, but there might be
other side-effects from loading some specific module.

Use the EXCLUDE property to exclude modules with undesirable side
effects. In general, it is probably a bad idea to have significant
side-effects just from loading a module.

### [API Documentation](https://rec.github.io/impall#impall--api-documentation)

### A note on AI use

Version 3.0 has exactly the same API as before, and the great majority of the code is
still the handwritten code from before, but I recently used a coding assistant to find a
lot of possible errors and edge cases and fix them.

I believe it should do exactly what it did before, but not fail in some unusual but
certainly not impossible cases. Please let me know with an [issue
report](https://github.com/rec/impall/issues/new) if any problems crop up.
