utils#

openplaces utilities module

General-purpose utility functions for formatting, display, and debugging.

Functions#

pretty_print(→ str | None)

Pretty print nested dictionaries, lists, and Python class instances.

format_list(items[, nmax, sep])

Format list to short string, making sure start and end are shown

inspect_table(→ pandas.DataFrame)

Print an output summary and return a transposed row sample.

short_number(x[, round_to, suffix, sep, base])

Convert a large number to a short string for display.

Module Contents#

openplaces.utils.pretty_print(obj: Any, indent: int = 2, max_depth: int = 10, return_string: bool = False, _current_depth: int = 0) → str | None#

Pretty print nested dictionaries, lists, and Python class instances.

Converts dataclasses and objects with __dict__ to dictionaries recursively, then formats them in YAML-style (no quotes around keys, indentation-based).

By default, prints the output directly. Set return_string=True to get the string instead.

Parameters:

  • obj (Any) – Object to print (dict, list, dataclass, or any class instance)

  • indent (int, default=2) – Number of spaces per indentation level

  • max_depth (int, default=10) – Maximum nesting depth to prevent infinite recursion

  • return_string (bool, default=False) – If True, return the formatted string instead of printing it

  • _current_depth (int) – Internal parameter for tracking recursion depth

Returns:

If return_string=True, returns formatted string. Otherwise prints and returns None.

Return type:

str | None

Examples

>>> from dataclasses import dataclass
>>> @dataclass
... class Person:
...     name: str
...     age: int
>>>
>>> data = {'people': [Person('Alice', 30), Person('Bob', 25)]}
>>> pretty_print(data)
>>>
>>> # Get string without printing
>>> s = pretty_print(data, return_string=True)
openplaces.utils.format_list(items: list, nmax: int = 7, sep: str = ', ')#

Format list to short string, making sure start and end are shown

[1, 2, 3, 4, 5, 6, 7] > ‘1, 2, 3, 4, 5, 6, 7’

[1, 2, 3, 4, 5, 6, 7, 8] > ‘1, 2, 3, …, 6, 7, 8’

openplaces.utils.inspect_table(data: pandas.DataFrame, n: int = 5, columns: list[str] | None = None, random_state: int | None = None) → pandas.DataFrame#

Print an output summary and return a transposed row sample.

openplaces.utils.short_number(x, round_to=0, suffix='', sep=' ', base=1000)#

Convert a large number to a short string for display.

Examples: 14124521 -> ‘14 M’, or ‘14.1 M’ with round_to=1.

Parameters:

  • x (numeric) – Number to format.

  • round_to (int) – Number of decimal digits to display.

  • suffix (str) – Suffix appended after the unit (e.g. a base unit such as ‘B’ for bytes).

  • sep (str) – Separator between number and unit.

  • base (int) – Scaling factor between units; use 1024 for computer storage.