Metadata-Version: 2.4
Name: status-update
Version: 1.2.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

# status_update

[![Downloads](https://static.pepy.tech/badge/status-update)](https://pepy.tech/projects/status-update)
[![GitHub](https://img.shields.io/badge/GitHub-status_update-181717?logo=github)](https://github.com/MaikyMaik112/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, how much memory it consumes, and what it returns.

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
- [`@inspect_output`](#inspect_output) — logs the type and structure of any function's return value

---

## `@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 |

---

## `@inspect_output`

Logs the type and structure of any function's return value automatically.
No more manual `print(type(result))` or `print(result.shape)` scattered across your codebase.

Supports all native Python types, datetime objects, pandas DataFrames and Series, and numpy arrays.
Any unrecognised type is safely labelled as an exotic object.

### Usage

```python
import logging
from status_update import inspect_output

logging.basicConfig(level=logging.INFO)

@inspect_output
def build_features(df):
    ...
```

With a custom logger:

```python
import logging
from status_update import inspect_output

logger = logging.getLogger('myapp')

@inspect_output(logger=logger)
def build_features(df):
    ...
```

### Output by type

```
# int, float, bool
INFO  [price_option]    Output — float | Value: 3.141592653589793
INFO  [count_trades]    Output — int | Value: 142
INFO  [is_valid]        Output — bool | Value: True

# str
INFO  [get_label]       Output — str | Length: 18 | Preview: "AAPL_2026_Q1_close"

# None
INFO  [save_results]    Output — None

# list, tuple, set — single type
INFO  [load_tickers]    Output — list | Length: 152 | Contains: str
INFO  [get_params]      Output — tuple | Length: 3 | Contains: float

# list, tuple, set — mixed types
INFO  [load_mixed]      Output — list | Length: 8 | Contains: multiple types

# dict
INFO  [get_config]      Output — dict | Keys: 8 | Sample: alpha, beta, gamma (+5 more)

# datetime, date, timedelta
INFO  [get_timestamp]   Output — datetime | Value: 2026-04-20 14:32:01
INFO  [get_expiry]      Output — date | Value: 2026-12-19
INFO  [get_duration]    Output — timedelta | Duration: 2 hours, 30 minutes

# numpy
INFO  [run_simulation]  Output — ndarray | Shape: (10000, 50) | dtype: float64
INFO  [build_matrix]    Output — matrix | Shape: (4, 4) | dtype: float32

# pandas
INFO  [build_features]  Output — DataFrame | Shape: (9847, 24) | Columns: date, open, close, vol, ret (+19 more)
INFO  [get_series]      Output — Series | Length: 9847 | Name: "close" | dtype: float64

# exotic / unknown
INFO  [run_model]       Output — Exotic object — BlackScholesModel
```

---

## Stacking all three decorators

All three decorators are designed to stack cleanly:

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

logging.basicConfig(level=logging.INFO)

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

Output:

```
INFO     Started   [run_pipeline].
INFO     [run_pipeline] Memory started   | System: 3.2 GB / 16.0 GB (20%)
INFO     [run_pipeline] Output — DataFrame | Shape: (9847, 24) | Columns: date, open, close, vol, ret (+19 more)
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
