Metadata-Version: 2.4
Name: dbt-toolbox
Version: 0.2.0
Summary: Productivity, warehous cost and QoL improvements for your dbt development
Author-email: Erik Munkby <erik.munkby@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Erik Munkby
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: jinja2>=3.1.6
Requires-Dist: loguru>=0.7.3
Requires-Dist: sqlglot[rs]>=26.25.3
Requires-Dist: tomli>=2.2.1
Requires-Dist: typer>=0.16.0
Requires-Dist: yamlium>=0.1.3
Description-Content-Type: text/markdown

# dbt-toolbox

A powerful CLI toolkit that supercharges your dbt development workflow with intelligent caching, dependency analysis, and enhanced documentation generation.

## 🚀 What Makes dbt-toolbox Amazing

**Smart Caching & Performance**
- Lightning-fast model parsing with intelligent cache invalidation
- Persistent Jinja environment caching for instant macro resolution
- Dependency graph caching for rapid upstream/downstream analysis

**Enhanced dbt Commands**
- `dt build` - Drop-in replacement for `dbt build` with enhanced output and performance
- `dt run` - Drop-in replacement for `dbt run` with smart execution and caching
- Target-specific options for environment control
- Intelligent pre/post processing hooks

**Intelligent Documentation**
- `dt docs` - YAML documentation generator with smart column inheritance
- Automatically inherits descriptions from upstream models and macros
- Tracks column changes (additions, removals, reordering) between runs
- One-click clipboard integration

**Dependency Intelligence**
- Lightweight DAG implementation for model and macro relationships
- Efficient upstream/downstream traversal
- Node type tracking and statistics
- Perfect for impact analysis and refactoring

**Configuration**
- Multi-source settings hierarchy (env vars > TOML > dbt profiles > defaults)
- Dynamic dbt profile and target integration
- Source tracking for all configuration values

## 🛠️ Installation

```bash
# Using uv
uv add dbt-toolbox

# Or install with pip
pip install dbt-toolbox
```

## ⚡ Quick Start

```bash
# Initialize and explore your project
dt settings                    # View all configuration

# Enhanced dbt commands with caching
dt build                      # Build with intelligent caching
dt run --model +my_model+     # Support for most dbt selection syntax
dt build --target prod        # Build against production target

# Analyze cache and dependencies
dt analyze                    # Analyze all models
dt analyze --model customers+ # Analyze specific model selection

# Generate documentation YAML
dt docs --model customers     # Generate docs for specific model
dt docs -m orders --clipboard # Copy to clipboard
```

## 📋 Core Commands

| Command | Description |
|---------|-------------|
| `dt build` | Enhanced dbt build with caching and better output |
| `dt run` | Enhanced dbt run with intelligent execution and caching |
| `dt docs` | Generate YAML documentation with smart inheritance |
| `dt analyze` | Analyze cache state and model dependencies without execution |
| `dt clean` | Clear all cached data with detailed reporting |
| `dt settings` | Inspect configuration from all sources |

## 🏗️ Key Features

### Intelligent Caching System
dbt-toolbox caches parsed models, macros, and Jinja environments in `.dbt_toolbox/` directory with smart invalidation based on file changes and project configuration.

### Dependency Graph Analysis
Lightweight DAG implementation provides efficient model relationship tracking:
- Upstream/downstream dependency resolution
- Node type classification (models, macros, sources)
- Impact analysis for refactoring

### Enhanced CLI Experience
- Colored output with progress indicators
- Global options that work across all commands
- Command shadowing for seamless dbt integration
- Comprehensive error handling and reporting

### Smart Documentation Generation
The `dt docs` command intelligently inherits column descriptions from:
- Upstream model columns with matching names
- Macro parameters that reference the columns
- Existing schema.yml documentation

## 📚 Documentation

- [CLI Reference](./CLI.md) - Detailed command documentation and examples
- [Contributing Guide](./CONTRIBUTING.md) - Development setup and guidelines

## 🧪 Testing Integration

dbt-toolbox includes a testing module for your dbt projects:

```python
from dbt_toolbox.testing import check_column_documentation

def test_model_documentation():
    """Ensure all model columns are documented."""
    result = check_column_documentation()
    if result:
        pytest.fail(result)
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for development setup, coding standards, and contribution guidelines.

## 📄 License

[MIT License](LICENSE) - Feel free to use this project in your own work.

## 🙏 Acknowledgments

Built with modern Python tooling:
- [Typer](https://typer.tiangolo.com/) for the CLI framework
- [SQLGlot](https://sqlglot.com/) for SQL parsing and optimization
- [Jinja2](https://jinja.palletsprojects.com/) for template processing
- [yamlium](https://github.com/erikmunkby/yamlium) for YAML manipulation and generation
- [uv](https://docs.astral.sh/uv/) for dependency management