### Install Development Dependencies with Poetry (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Installs project dependencies, including development tools, using Poetry. This command creates a virtual environment with all necessary packages.

```shell
poetry install --with=dev
```

--------------------------------

### TOML Configuration Example for FawltyDeps

Source: https://github.com/tweag/fawltydeps/blob/main/docs/configuration.md

An example of a comprehensive pyproject.toml configuration for FawltyDeps, demonstrating settings for code directories, dependency files, ignored unused packages, and output format.

```toml
[tool.fawltydeps]
code = ["myproject"]  # Only search for imports under ./myproject
deps = ["pyproject.toml"]  # Only look for declared dependencies here
ignore_unused = ["black"]  # We use `black`, but we don't intend to import it
output_format = "human_detailed"  # Detailed report by default

```

--------------------------------

### Generate and store configuration in pyproject.toml

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

Automatically generate a TOML configuration section for your project based on current settings, which can be copied directly into pyproject.toml.

```shell
fawltydeps --generate-toml-config
```

```toml
[tool.fawltydeps]
# Default options are commented...
ignore_unused = ["black", "pylint"]
```

--------------------------------

### Pre-commit Hook Configuration and Installation

Source: https://context7.com/tweag/fawltydeps/llms.txt

Configures FawltyDeps as a pre-commit hook in a .pre-commit-config.yaml file and provides commands to install and run the hooks manually.

```yaml
repos:
  - repo: https://github.com/tweag/FawltyDeps
    rev: v0.20.0
    hooks:
      - id: fawltydeps
        args: [--check-undeclared]
```

```bash
# Install pre-commit hooks
pre-commit install

# Run manually
pre-commit run fawltydeps --all-files
```

--------------------------------

### Analyze individual packages in a monorepo

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

To avoid overwhelming reports in a monorepo, run FawltyDeps on each package directory individually rather than at the root.

```shell
fawltydeps libX
```

--------------------------------

### Ignore specific unused dependencies

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

Exclude development tools like linters or formatters from the unused dependency report by specifying them via the command line or configuration file.

```shell
fawltydeps --ignore-unused black pylint
```

--------------------------------

### Configure pre-commit hook

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

Integrate FawltyDeps into your development workflow by adding it to the .pre-commit-config.yaml file to automatically check for undeclared or unused dependencies.

```yaml
repos:
  - repo: https://github.com/tweag/FawltyDeps
    rev: v0.20.0
    hooks:
      - id: check-undeclared
      - id: check-unused
```

--------------------------------

### Activate Poetry Development Shell (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Activates the virtual environment created by Poetry, providing access to all installed development dependencies. Commands can be run directly without 'poetry run'.

```shell
poetry shell
```

--------------------------------

### Analyze undeclared dependencies with detailed reporting

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

Run FawltyDeps with the detailed flag to identify the exact file and line number of undeclared imports, which helps in debugging dependency issues.

```shell
fawltydeps --detailed
```

--------------------------------

### Analyze Python code via standard input

Source: https://github.com/tweag/fawltydeps/blob/main/docs/how_to_guides.md

Use the --code - flag to pipe Python code directly into FawltyDeps for analysis, useful for clipboard content or automated script outputs.

```shell
cat some/source/of/python/code | fawltydeps --code -
# or
fawltydeps --code - < some/source/of/python/code
# or
fawltydeps --code -
```

--------------------------------

### Resolve package names to import names using FawltyDeps

Source: https://context7.com/tweag/fawltydeps/llms.txt

Demonstrates how to set up resolvers and map package names to their corresponding import names. This is useful for identifying which packages provide specific modules in a project.

```python
from fawltydeps.packages import (
	setup_resolvers,
	resolve_dependencies,
	LocalPackageResolver,
	SysPathPackageResolver,
	UserDefinedMapping,
	pyenv_sources,
)
from pathlib import Path

# Setup resolvers with custom mapping
resolvers = list(setup_resolvers(
	custom_mapping={"scikit-learn": ["sklearn"], "pillow": ["PIL"]},
	pyenv_srcs=pyenv_sources(Path(".venv")),
	use_current_env=True,
	install_deps=False,
))

# Resolve dependencies to their import names
dependencies = {"requests", "numpy", "scikit-learn"}
resolved = resolve_dependencies(dependencies, resolvers)

for name, package in resolved.items():
	print(f"{name} -> imports: {package.import_names}")
	print(f"  Resolved with: {package.resolved_with.__name__}")
```

--------------------------------

### Define Custom Mapping File

Source: https://context7.com/tweag/fawltydeps/llms.txt

Create a TOML file to map package names to import names when they differ, ensuring accurate dependency resolution.

```toml
langchain-core = ["langchain_core"]
scikit-learn = ["sklearn"]
python-dotenv = ["dotenv"]
pillow = ["PIL"]
opencv-python = ["cv2"]
beautifulsoup4 = ["bs4"]
multiple-modules = ["module1", "module2"]
```

--------------------------------

### Extract Dependencies from Declaration Files

Source: https://context7.com/tweag/fawltydeps/llms.txt

Parse various dependency declaration formats like pyproject.toml, requirements.txt, or setup.py.

```python
from fawltydeps.extract_deps import parse_source, validate_deps_source
from fawltydeps.types import ParserChoice
from pathlib import Path

deps_source = validate_deps_source(Path("pyproject.toml"))
if deps_source:
    for dep in parse_source(deps_source):
        print(f"Dependency: {dep.name} from {dep.source}")

deps_source = validate_deps_source(Path("requirements.txt"), parser_choice=ParserChoice.REQUIREMENTS_TXT)
if deps_source:
    for dep in parse_source(deps_source):
        print(f"Requirement: {dep.name}")
```

--------------------------------

### Manage Dependencies via CLI

Source: https://context7.com/tweag/fawltydeps/llms.txt

Commands to perform dependency analysis, auto-install missing packages, and utilize custom mapping files for resolution.

```bash
fawltydeps --install-deps
fawltydeps --custom-mapping-file my_mapping.toml
```

--------------------------------

### Map dependencies using a local Python environment

Source: https://github.com/tweag/fawltydeps/blob/main/docs/explanation.md

Demonstrates how to use the --pyenv flag to specify a virtual environment for dependency resolution. This command maps dependencies defined in pyproject.toml to imports found within the specified environment.

```shell
fawltydeps --code my_package/ --deps pyproject.toml --pyenv /path/to/project/venv
```

--------------------------------

### Generate Configuration Template

Source: https://context7.com/tweag/fawltydeps/llms.txt

Generates a boilerplate TOML configuration file for FawltyDeps settings.

```bash
fawltydeps --generate-toml-config
```

--------------------------------

### Configure FawltyDeps via pyproject.toml

Source: https://context7.com/tweag/fawltydeps/llms.txt

Persistent configuration for project settings, including ignored dependencies, custom mappings, and analysis behavior.

```toml
[tool.fawltydeps]
code = ["src/myproject"]
deps = ["pyproject.toml"]
ignore_unused = ["black", "mypy", "pytest", "ruff"]
ignore_undeclared = ["optional_module"]
output_format = "human_detailed"
actions = ["check_undeclared", "check_unused"]
exclude = [".*", "tests/"]
verbosity = 0
install_deps = false

[tool.fawltydeps.custom_mapping]
scikit-learn = ["sklearn"]
python-dotenv = ["dotenv"]
pillow = ["PIL"]
opencv-python = ["cv2"]
beautifulsoup4 = ["bs4"]
```

--------------------------------

### Run Nox Tests for Specific Python Version (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Runs the 'tests' Nox session specifically for Python version 3.9, assuming it is installed locally. This is useful for targeted testing.

```shell
nox -s tests-3.9
```

--------------------------------

### Specify Python environment for dependency analysis

Source: https://github.com/tweag/fawltydeps/blob/main/docs/FAQ.md

Demonstrates how to manually point FawltyDeps to a specific Python environment directory when the tool cannot automatically detect project dependencies.

```bash
fawltydeps --pyenv /path/to/your/project/.venv
```

--------------------------------

### CLI Execution of FawltyDeps

Source: https://context7.com/tweag/fawltydeps/llms.txt

Shows how to invoke the FawltyDeps main entry point programmatically via the sys module or standard CLI execution.

```python
import sys
from fawltydeps.main import main
sys.exit(main(["--check", "my_project/"]))
```

--------------------------------

### Configure FawltyDeps analysis settings

Source: https://context7.com/tweag/fawltydeps/llms.txt

Explains how to programmatically configure the Settings object to control analysis behavior, including output formats, exclusion patterns, and custom mappings.

```python
from fawltydeps.settings import Settings, Action, OutputFormat, DEFAULT_IGNORE_UNUSED
from pathlib import Path

# Create settings with all options
settings = Settings(
	actions={Action.REPORT_UNDECLARED, Action.REPORT_UNUSED},
	output_format=OutputFormat.JSON,
	code={Path("src/")},
	deps={Path("pyproject.toml"), Path("requirements.txt")},
	ignore_unused=DEFAULT_IGNORE_UNUSED | {"custom_dev_tool"},
	exclude={".*", "tests/", "__pycache__/"},
	custom_mapping={"opencv-python": ["cv2"]}
)

# Load settings from pyproject.toml
Settings.config_file = Path("pyproject.toml")
settings_from_file = Settings()
```

--------------------------------

### Programmatic Dependency Analysis using Python API

Source: https://context7.com/tweag/fawltydeps/llms.txt

Demonstrates how to use the FawltyDeps Python API to configure analysis settings, perform checks, and handle exit codes based on identified dependency issues.

```python
from fawltydeps.settings import Settings, Action
from fawltydeps.analysis import Analysis
from fawltydeps.main import assign_exit_code
from pathlib import Path

settings = Settings(
    code={Path(".")},
    actions={Action.REPORT_UNDECLARED, Action.REPORT_UNUSED},
)
analysis = Analysis.create(settings)
exit_code = assign_exit_code(analysis)

if exit_code == 0:
    print("No dependency issues found!")
elif exit_code == 3:
    print(f"Found undeclared deps: {[d.name for d in analysis.undeclared_deps]}")
elif exit_code == 4:
    print(f"Found unused deps: {[d.name for d in analysis.unused_deps]}")
```

--------------------------------

### Exclude paths from FawltyDeps analysis

Source: https://github.com/tweag/fawltydeps/blob/main/docs/usage.md

Demonstrates how to use the --exclude and --exclude-from options to skip specific directories or file patterns during dependency scanning. Patterns follow .gitignore syntax.

```shell
fawltydeps --exclude tests/
fawltydeps --exclude tests/ ".*"
fawltydeps --exclude-from my_excludes.txt
fawltydeps --code my_dir --exclude "*.ipynb"
```

--------------------------------

### Enter Nix Shell with Poetry Environment (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Activates a development shell using Nix, which provides Poetry and all supported Python versions. This offers an isolated development environment.

```shell
nix-shell
```

--------------------------------

### Calculate undeclared and unused dependencies

Source: https://context7.com/tweag/fawltydeps/llms.txt

Shows how to use the check module to compare project imports against declared dependencies. It identifies missing dependencies and those that are declared but never imported.

```python
from fawltydeps.check import calculate_undeclared, calculate_unused
from fawltydeps.packages import setup_resolvers, resolve_dependencies
from fawltydeps.settings import Settings
from fawltydeps.types import ParsedImport, DeclaredDependency, Location
from pathlib import Path

# Sample data
imports = [
	ParsedImport(name="requests", source=Location(Path("app.py"), lineno=1)),
	ParsedImport(name="pandas", source=Location(Path("app.py"), lineno=2)),
	ParsedImport(name="sklearn", source=Location(Path("ml.py"), lineno=1)),
]

declared_deps = [
	DeclaredDependency(name="requests", source=Location(Path("requirements.txt"))),
	DeclaredDependency(name="numpy", source=Location(Path("requirements.txt"))),
]

# Setup resolvers and resolve dependencies
resolvers = list(setup_resolvers(use_current_env=True))
resolved = resolve_dependencies(
	{d.name for d in declared_deps},
	resolvers
)

# Create settings
settings = Settings(
	ignore_undeclared=set(),
	ignore_unused={"black", "mypy"},
)

# Calculate undeclared dependencies
undeclared = calculate_undeclared(imports, resolved, resolvers, settings)
for dep in undeclared:
	print(f"Undeclared: {dep.name}")

# Calculate unused dependencies
unused = calculate_unused(imports, declared_deps, resolved, settings)
for dep in unused:
	print(f"Unused: {dep.name}")
```

--------------------------------

### Parse Code from Standard Input

Source: https://context7.com/tweag/fawltydeps/llms.txt

Demonstrates how to pipe Python code directly into FawltyDeps for import analysis, useful for CI/CD pipelines or quick checks.

```bash
echo "import requests" | fawltydeps --list-imports --code -
echo "import foo" | fawltydeps --list-imports --code - file.py
```

--------------------------------

### Ignore specific dependencies in FawltyDeps

Source: https://github.com/tweag/fawltydeps/blob/main/docs/usage.md

Shows how to suppress warnings for undeclared or unused dependencies using the --ignore-undeclared and --ignore-unused flags, supporting wildcard patterns.

```shell
fawltydeps --ignore-undeclared some_module some_other_module
fawltydeps --ignore-unused black mypy some_other_module
fawltydeps --ignore-unused types-* *pre-commit*
```

--------------------------------

### List Nox Sessions (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Lists all available automation sessions defined in the Nox configuration. This helps in understanding the available workflows for testing and linting.

```shell
nox --list
```

--------------------------------

### Programmatic Analysis with Python API

Source: https://context7.com/tweag/fawltydeps/llms.txt

Use the Analysis class to perform dependency checks programmatically and output results in various formats.

```python
from fawltydeps.main import Analysis
from fawltydeps.settings import Settings, Action, OutputFormat
from pathlib import Path

settings = Settings(
    code={Path("src/myproject")},
    deps={Path("pyproject.toml")},
    actions={Action.REPORT_UNDECLARED, Action.REPORT_UNUSED},
    output_format=OutputFormat.HUMAN_DETAILED,
    ignore_unused={"black", "mypy", "pytest"},
)

analysis = Analysis.create(settings)
analysis.print_human_readable(sys.stdout, detailed=True)
analysis.print_json(sys.stdout)
```

--------------------------------

### Check Formatting with Nox (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Runs the 'format' Nox session to check code formatting using ruff format. It reports any files that do not adhere to the project's formatting standards.

```shell
nox -s format
```

--------------------------------

### Run All Nox Sessions (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes all defined Nox sessions, including tests and linters, across supported Python versions. This is a comprehensive way to check the project's health.

```shell
nox
```

--------------------------------

### Run Pytest Unit Tests (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes all unit tests using Pytest. This command is typically run within the Poetry shell or after activating the virtual environment.

```shell
pytest
```

--------------------------------

### Run Ruff Formatter (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes the Ruff formatter to automatically format the code in the current directory according to project standards. This ensures consistent code style.

```shell
ruff format .
```

--------------------------------

### Run Nox Tests Session (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes the 'tests' Nox session, which runs unit tests on all supported Python versions available locally. This ensures compatibility across different Python environments.

```shell
nox -s tests
```

--------------------------------

### Run Nox Sessions with Virtualenv Reuse (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Runs all Nox sessions while reusing existing virtual environments. This can significantly speed up subsequent runs by avoiding re-creation of environments.

```shell
nox -R
```

--------------------------------

### Run Nox Integration Tests for Specific Python Version (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes the 'integration_tests' Nox session for Python version 3.11. This allows for focused testing of integration scenarios.

```shell
nox -s integration_tests-3.11
```

--------------------------------

### Run Nox Linting Session (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Runs the 'lint' Nox session, which executes linters like mypy and ruff check across all supported Python versions. This ensures code quality and style consistency.

```shell
nox -s lint
```

--------------------------------

### Run Mypy Static Type Checking (Shell)

Source: https://github.com/tweag/fawltydeps/blob/main/docs/CONTRIBUTING.md

Executes Mypy for static type checking across the project. This helps in catching type-related errors before runtime.

```shell
mypy
```