Metadata-Version: 2.4
Name: status-update
Version: 1.1.0
Summary: A lightweight Python library of decorators for code tracking, debugging, and performance diagnostics.
Author-email: Alexandru-Gabriel Michiduță <michidutaalexandru1995@yahoo.ro>
License: Attribution-Required Free License
Keywords: logging,decorator,debugging,performance,memory,tracking,monitoring,profiling,utilities,devtools
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: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Debuggers
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: full
Requires-Dist: psutil>=5.9; extra == "full"
Dynamic: license-file

# status_update

> A lightweight Python library of decorators for code tracking, debugging, and performance diagnostics.

No external dependencies. No configuration. Drop a decorator on any function and immediately understand what your code is doing, how long it takes, and how much memory it consumes.

Built for developers who need clarity in complex, computational codebases.

---

## Installation

```bash
pip install status-update
```

For full system memory tracking, also install the optional dependency:

```bash
pip install psutil
```

---

## Decorators

- [`@status_update`](#status_update) — logs when a function starts, completes, and how long it took
- [`@memory_track`](#memory_track) — tracks memory consumption before, during, and after execution

---

## `@status_update`

Logs the start, completion, and elapsed time of any function.
Handles sub-second runs up to multi-day batch jobs with clean, human-readable output.

### Usage

```python
import logging
from status_update import status_update

logging.basicConfig(level=logging.INFO)

@status_update
def load_data():
    ...
```

With a custom logger:

```python
import logging
from status_update import status_update

logger = logging.getLogger('myapp')

@status_update(logger=logger)
def run_model():
    ...
```

### Output

Normal completion:

```
INFO     Started   [load_data].
INFO     Completed [load_data] in 2 minutes, 14 seconds.
```

On exception:

```
INFO     Started   [load_data].
ERROR    Failed    [load_data] after 1 minute, 3 seconds. Error: connection timeout.
```

Elapsed time scales automatically:

| Duration | Output |
|---|---|
| Under 1 second | `< 1 second` |
| 45 seconds | `45 seconds` |
| 90 seconds | `1 minute, 30 seconds` |
| 3661 seconds | `1 hour, 1 minute, 1 second` |
| 90061 seconds | `1 day, 1 hour, 1 minute, 1 second` |

---

## `@memory_track`

Tracks memory consumption across the full lifecycle of a function.
Logs a snapshot before execution, peak memory reached, net delta, and a running session total.

If `psutil` is installed, also provides real-time system memory context and fires threshold warnings in a background thread the moment usage crosses a critical level.

### Usage

```python
import logging
from status_update import memory_track

logging.basicConfig(level=logging.INFO)

@memory_track
def run_simulation():
    ...
```

With a custom logger:

```python
import logging
from status_update import memory_track

logger = logging.getLogger('myapp')

@memory_track(logger=logger)
def run_simulation():
    ...
```

Reset the session accumulator between pipeline runs:

```python
memory_track.reset_session()
```

### Output

Without `psutil` (process-level tracking only):

```
INFO     [run_simulation] Memory started.
INFO     [run_simulation] Memory completed | Peak: 840.0 MB | Net: +210.0 MB | Session: +210.0 MB
```

With `psutil` (full system context):

```
INFO     [run_simulation] Memory started   | System: 3.2 GB / 16.0 GB (20%)
INFO     [run_simulation] Memory completed | Peak: 840.0 MB | Net: +210.0 MB | Session: +210.0 MB | System: 3.4 GB / 16.0 GB (21%)
```

### Real-time threshold warnings

When `psutil` is installed, a background thread monitors system memory throughout execution and fires each warning exactly once per function call:

```
INFO     [run_simulation] Memory started   | System: 3.2 GB / 16.0 GB (20%)
WARNING  [run_simulation] Memory at 75%    | System: 12.1 GB / 16.0 GB (75%)
WARNING  [run_simulation] Memory at 85%    | System: 13.6 GB / 16.0 GB (85%)
CRITICAL [run_simulation] Memory at 95%    | System: 15.2 GB / 16.0 GB (95%)
INFO     [run_simulation] Memory completed | Peak: 11.2 GB | Net: +1.8 GB | Session: +2.0 GB | System: 13.1 GB / 16.0 GB (82%)
```

If memory reaches 100%:

```
CRITICAL [run_simulation] ⚠ Memory saturated — process will likely be killed | System: 16.0 GB / 16.0 GB (100%)
```

### Threshold reference

| Level | Log level | Meaning |
|---|---|---|
| 50% | `INFO` | OS memory pressure begins |
| 75% | `WARNING` | Measurable performance degradation |
| 85% | `WARNING` | Swap usage likely, significant slowdown |
| 95% | `CRITICAL` | Imminent failure territory |
| 100% | `CRITICAL` | Memory saturated |

---

## Stacking both decorators

`@status_update` and `@memory_track` are designed to stack cleanly:

```python
import logging
from status_update import status_update, memory_track

logging.basicConfig(level=logging.INFO)

@status_update
@memory_track
def run_pipeline():
    ...
```

Output:

```
INFO     Started   [run_pipeline].
INFO     [run_pipeline] Memory started   | System: 3.2 GB / 16.0 GB (20%)
INFO     [run_pipeline] Memory completed | Peak: 2.1 GB | Net: +300.0 MB | Session: +300.0 MB | System: 3.5 GB / 16.0 GB (22%)
INFO     Completed [run_pipeline] in 1 minute, 42 seconds.
```

---

## Session tracking across a pipeline

```python
from status_update import memory_track

memory_track.reset_session()

@memory_track
def load_data(): ...

@memory_track
def run_simulation(): ...

@memory_track
def clean_results(): ...

load_data()
run_simulation()
clean_results()
```

Output:

```
INFO  [load_data]      Memory completed | Peak: 840.0 MB | Net: +210.0 MB | Session: +210.0 MB | System: 3.4 GB / 16.0 GB (21%)
INFO  [run_simulation] Memory completed | Peak: 11.2 GB  | Net: +1.8 GB  | Session: +2.0 GB  | System: 13.1 GB / 16.0 GB (82%)
INFO  [clean_results]  Memory completed | Peak: 120.0 MB | Net: -1.1 GB  | Session: +900.0 MB | System: 12.0 GB / 16.0 GB (75%)
```

---

## License

Free to use and modify for any purpose.
Professional or organisational use requires crediting the original author:

> *"status_update library by Alexandru-Gabriel Michiduță"*

© 2026 Alexandru-Gabriel Michiduță
Improvements and suggestions are always welcome at michidutaalexandru1995@yahoo.ro
