pybragerone.utils¶

Library utilities.

This module provides utility functions for the pybragerone library, organized into categories:

Task Management:

spawn() - Background task spawning with error handling

JSON Utilities:

json_preview() - Single-line JSON preview with length limits
log_json_payload() - Debug logging for JSON payloads
save_json_payload() - Save JSON to UTF-8 files
summarize_top_level() - Quick structural summary of JSON objects

Functions

`json_preview`(obj, *[, maxlen])	Return a single-line JSON preview trimmed to maxlen with no indent.
`log_json_payload`(logger, tag, payload, *[, ...])	Log a one-line JSON payload preview at the DEBUG level.
`save_json_payload`(payload, path)	Write the JSON payload to a UTF-8 file and return the path.
`spawn`(coro, name, log)	Spawn a background task and track it in bg_tasks set.
`summarize_top_level`(obj)	Return a quick summary of a top-level JSON-like object.

pybragerone.utils.json_preview(obj: Any, *, maxlen: int = 2000)[source]¶

Return a single-line JSON preview trimmed to maxlen with no indent.

Converts any Python object to a compact JSON string representation, truncating if necessary. Safe for any input type.

Parameters:

obj (Any) – Any Python object to preview.
maxlen (int) – Maximum length of the returned string (default: 2000).

Returns:

str – A single-line JSON string, possibly truncated with “…”.

Return type:

str

Example

>>> json_preview({"key": "value", "numbers": [1, 2, 3]})
'{"key":"value","numbers":[1,2,3]}'

pybragerone.utils.log_json_payload(logger: Logger, tag: str, payload: Any, *, maxlen: int = 2000)[source]¶

Log a one-line JSON payload preview at the DEBUG level.

Return type:

None

Parameters:

logger (Logger)
tag (str)
payload (Any)
maxlen (int)

pybragerone.utils.save_json_payload(payload: Any, path: str | Path)[source]¶

Write the JSON payload to a UTF-8 file and return the path.

Return type:

Path

Parameters:

payload (Any)
path (str | Path)

pybragerone.utils.spawn(coro: Coroutine[Any, Any, Any], name: str, log: Logger)[source]¶

Spawn a background task and track it in bg_tasks set.

Parameters:

coro (Coroutine[Any, Any, Any]) – The coroutine to execute as a background task.
name (str) – Descriptive name for the task (used in logging).
log (Logger) – Logger instance for error reporting.

Return type:

None

Note

Tasks are automatically cleaned up on completion or cancellation. Exceptions are logged but don’t crash the application.

pybragerone.utils.summarize_top_level(obj: Any)[source]¶

Return a quick summary of a top-level JSON-like object.

This function inspects the provided object and produces a simple overview.

For dictionaries: lists the first ten top-level keys and counts elements.
For lists: reports the number of elements and the type of the first item.
For scalar values: records the concrete type name.

Parameters:: obj (Any) – The JSON-like object to summarize. Typically a dict, list, or scalar (str, int, float, bool).
Returns:: dict[str, Any] – A dictionary describing the top-level structure.
Return type:: dict[str, Any]

Example

>>> summarize_top_level({"a": 1, "b": 2})
{'type': 'dict', 'keys': ['a', 'b'], 'len': 2}
>>> summarize_top_level([1, 2, 3])
{'type': 'list', 'len': 3, 'first_type': 'int'}
>>> summarize_top_level("hello")
{'type': 'str'}