status-update 1.1.0

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

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

pip install status-update

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

pip install psutil

---

Decorators

• @status_update — logs when a function starts, completes, and how long it took
• @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

import logging
from status_update import status_update

logging.basicConfig(level=logging.INFO)

@status_update
def load_data():
    ...

With a custom logger:

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

import logging
from status_update import memory_track

logging.basicConfig(level=logging.INFO)

@memory_track
def run_simulation():
    ...

With a custom logger:

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:

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:

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

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 [e-mail]