Metadata-Version: 2.1
Name: check-dependencies
Version: 0.13.0
Summary: Check dependencies of a python project against pyproject.toml requirements
Keywords: packaging,development,requirements,dependencies
Author-Email: Micha Scholl <schollm-git@gmx.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Utilities
Project-URL: Bug Tracker, https://github.com/schollm/check-dependencies/issues
Project-URL: homepage, https://github.com/schollm/check-dependencies
Project-URL: repository, https://github.com/schollm/check-dependencies
Project-URL: documentation, https://github.com/schollm/check-dependencies/blob/main/README.md
Requires-Python: >=3.8
Requires-Dist: toml; python_version < "3.11"
Description-Content-Type: text/markdown

# Check Dependencies
Check all imports from python files and compares them against the declared imports of a pyproject dependency list of expected imports. 

It can be used as a stand-alone or as part of a CI/CD to check if an application has all the necessary, but no superfluous imports.

This is a pure-Python zero-dependency (Up until Python 3.11 one, toml) package.
## Usage
```text
usage: check-dependencies [-h] [--include-extra] [--verbose] [--all] [--missing MISSING] [--extra EXTRA] [--provides PROVIDES] file_name [file_name ...]

Find undeclared and unused (or all) imports in Python files

positional arguments:
  file_name          Python Source file to analyse

optional arguments:
  -h, --help         show this help message and exit
  --include-extra    Include dev dependencies
  --verbose          Show every import of a package
  --all              Show all imports (including correct ones)
  --missing MISSING  Comma seperated list of requirements known to be missing. 
                     Assume they are part of the requirements.
  --extra EXTRA      Comma seperated list of requirements known to not be imported.
                     Assume they are not part of the requirements.
  --provides IMPORT=PACKAGE
                     Map an import name to its package name for packages whose
                     import name differs from the package name. Can be specified
                     multiple times. E.g. --provides PIL=Pillow --provides jwt=PyJWT.
                     Package name is normalized (case-insensitive, hyphens and
                     underscores equivalent), so PIL=Pillow and PIL=pillow are the same.
```

### Output
The output is a list of imports with a prefix indicating the status of the import.
- `!` - Undeclared import
- `+` - Extra import, declared in pyproject.toml, but not used in the file
- ` ` - Correct import (only shown with `--all`)

**In case of `--verbose`**, the output is a list of all imports in the file, prefixed with:
- `!NA` - Undeclared import
- `+EXTRA` - Extra import, declared in pyproject.toml, but not used in the file
- ` OK` - Correct import (only shown with `--all`)

Additionally, each import is prefixed with the file name and line number
where it is imported.


### Examples
#### Basic usage
```text
check-dependencies  project/src/
  pandas
! matplotlib
  numpy
+ requests
```

#### Output all dependencies
Output all dependencies, including the correct ones.
```text
check-dependencies --all project/src/
  pandas
! matplotlib
  numpy
+ requests
```
#### Verbose output
Output each erroneous import and extra dependency with cause, file name and line number.
```text
check-dependencies --verbose project/src/
!NA matplotlib project/src/main.py:4
+EXTRA project/pyproject.toml requests
```

#### Combine verbose and all
Output all imports, including the correct ones with file name and line number.
```commandline
check-dependencies --verbose --all project/src/
 OK project/src/data.py:5 pandas
 OK project/src/main.py:3 pandas
 OK project/src/plotting.py:4 pandas
!NA project/src/plotting.py:5 matplotlib
 OK project/src/plotting.py:6 numpy

### Dependencies in config file not used in application:
# Config file: project/pyproject.toml
+EXTRA requests
```

### Configuration
The configuration is read from `pyproject.toml` file. The configuration file
supports the following entries:
- `[tool.check-dependencies.extra-requirements]` to
add extra packages to the list of dependencies.

- `[tool.check-dependencies.ignore-requirements]` does the opposite, it will
ignore existing dependencies even if they are not imported. This is useful for
  packages, that provide functionality via plugins (e.g. sqlalchemy plugins)
  and are not imported directly in the codebase.
- `[tool.check-dependencies.provides]` to map import names to package names for
  packages whose import name differs from the package name.
  E.g. Pillow is imported as PIL, but the package name is Pillow.
  The value can be either a single module or a list of modules.
```toml
[tool.check-dependencies]
known-missing = [
  "undeclared_package",
  "another_package"
]
known-extra = [
  "package_as_extra_for_another_package",
  "yet_another_package"
]
[tool.check-dependencies.provides]
# Maps import name -> package name for packages whose import name differs
PIL = "Pillow"
jwt = "PyJWT"
shapefile = "pyshp"
foxtrox = ["fox", "trox"]  # This package provides both `import fox` and `import trox`, but the package name is `foxtrox`
```

#### Exit code
- 0: No missing or superfluous dependencies found
- 2: Missing (used, but not declared in pyproject.toml) dependencies found
- 4: Extra (declared in pyproject.toml, but unused) dependencies found
- 6: Both missing and superfluous dependencies found
- 8: Could not find associated pyproject.toml file
- 1: Another error occurred

## Development
Feature requests and merge requests are welcome. For major changes, please open an 
issue first to discuss what you would like to change.

Please make sure to update tests as appropriate. Also with this project, I want
to keep the dependencies to a minimum, so please keep that in mind when proposing
a change. Currently, the only dependencies is `toml` to support Python 3.10 and below.

### Coding Standards

| **Type**       | Package  | Comment                      |
|----------------|----------|------------------------------|
| **Logging**    | `logger` | Minimize additional packages |
| **Packaging**  | `uv`     |                              |
| **Tests**      | `pytest` |                              |
| **Typing**     | `mypy`   | Type all methods             |
| **Linting**    | `ruff`   | Also used for formatting     |
