# cjm-tqdm-capture


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

## Install

``` bash
pip install cjm-tqdm-capture
```

## Project Structure

    nbs/
    ├── patch_tqdm.ipynb    # Provides the patching mechanism to intercept tqdm and emit callbacks with that progress information
    └── progress_info.ipynb # Defines the data structure used to represent progress state

Total: 2 notebooks

## Module Dependencies

``` mermaid
graph LR
    patch_tqdm[patch_tqdm<br/>patch tqdm]
    progress_info[progress_info<br/>progress info]

    patch_tqdm --> progress_info
```

*1 cross-module dependencies detected*

## CLI Reference

No CLI commands found in this project.

## Module Overview

Detailed documentation for each module in the project:

### patch tqdm (`patch_tqdm.ipynb`)

> Provides the patching mechanism to intercept tqdm and emit callbacks
> with that progress information

#### Import

``` python
from cjm_tqdm_capture.patch_tqdm import (
    patch_tqdm
)
```

#### Functions

``` python
def _make_callback_class(
    BaseTqdm,  # Base tqdm class to extend with callback functionality
    default_cb: Optional[Callable[[ProgressInfo], None]],
    min_update_interval: float = 0.1,  # Minimum time between callback invocations (seconds)
    min_delta_pct: float = 1.0,      # emit only if pct moves by >= this
    emit_initial: bool = False       # whether to emit at 0%
)
    "Create a tqdm subclass that emits progress callbacks during iteration"
```

``` python
@contextmanager
def patch_tqdm(
    progress_callback: Optional[Callable[[ProgressInfo], None]],  # Function to call with progress updates
    min_update_interval: float = 0.1,  # Minimum time between callback invocations (seconds)
    min_delta_pct: float = 10.0,   # e.g., only every ~10%
    emit_initial: bool = False  # Whether to emit callback at 0% progress
)
    "Context manager that patches tqdm to emit progress callbacks"
```

### progress info (`progress_info.ipynb`)

> Defines the data structure used to represent progress state

#### Import

``` python
from cjm_tqdm_capture.progress_info import (
    ProgressInfo
)
```

#### Classes

``` python
@dataclass
class ProgressInfo:
    "Structured progress information"
    
    progress: float  # Percentage completion (0-100)
    current: Optional[int]  # Current iteration count
    total: Optional[int]  # Total iterations expected
    rate: Optional[str]  # Processing rate (e.g., "50.5 it/s")
    elapsed: Optional[str]  # Time elapsed since start
    remaining: Optional[str]  # Estimated time remaining
    description: Optional[str]  # Progress bar description/label
    raw_output: str = ''  # Raw output string (if any)
    timestamp: float  # Unix timestamp when created
    
```
