status-update 1.2.0

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

status_update

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

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
• @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

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

---

@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

import logging
from status_update import inspect_output

logging.basicConfig(level=logging.INFO)

@inspect_output
def build_features(df):
    ...

With a custom logger:

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:

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

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]