`SystemUtils`: System Utilities#

class my.utils.SystemUtils.SystemUtils#: Methods that deal with low-level system resources & APIs.

`I` Date & Time#

classmethod SystemUtils.posix(val: int | float | datetime | None = None) → datetime#

Convert a timestamp or datetime to UTC datetime.

Parameters:: val – Unix timestamp (int/float), datetime object, or None for current time. Naive datetimes are interpreted as UTC; aware datetimes are converted to UTC.
Returns:: Timezone-aware datetime in UTC.

Examples

Everything becomes an aware UTC datetime:

>>> from my import ut
>>> ut.posix(0)
datetime.datetime(1970, 1, 1, 0, 0, tzinfo=datetime.timezone.utc)

classmethod SystemUtils.posix_since(val: int | float | datetime | None = None) → timedelta#

Calculate time elapsed since a given timestamp.

Parameters:: val – Unix timestamp (int/float), datetime object, or None.
Returns:: Timedelta representing elapsed time, or zero when val is None.

Examples

A missing value yields zero; Unix epoch remains a real timestamp:

>>> from my import ut
>>> ut.posix_since(None)
datetime.timedelta(0)
>>> ut.posix_since(0).total_seconds() > 0
True

classmethod SystemUtils.milliseconds(val: int | float | datetime | timedelta | None = None) → int#

Convert a timedelta, datetime, or numeric timestamp to milliseconds.

Parameters:: val – A timedelta, a datetime, a numeric timestamp, or None for the current time. A numeric value < 10 is treated as already being in seconds (e.g. a small relative duration) rather than a Unix timestamp, and scaled up.
Returns:: The equivalent millisecond count, rounded to the nearest integer.

Examples

A timedelta and a datetime both convert directly:

>>> from datetime import timedelta, datetime, timezone
>>> from my import ut
>>> ut.milliseconds(timedelta(seconds=1))
1000
>>> ut.milliseconds(datetime(1970, 1, 2, tzinfo=timezone.utc))
86400000

`II` Filesystem#

classmethod SystemUtils.validate_dir(*paths: Annotated[Path, PathType(path_type=dir)]) → bool#

Validate that all provided paths are existing directories.

Parameters:: *paths – One or more directory paths to validate.
Returns:: True if all paths are valid directories.
Raises:: AssertionError – If any path is invalid or not a directory.

Examples

Existing directories pass:

>>> from pathlib import Path
>>> from my import ut
>>> ut.validate_dir(Path('/tmp'))
True

classmethod SystemUtils.validate_file(*paths: Annotated[Path, PathType(path_type=file)]) → bool#

Validate that all provided paths are existing files.

Parameters:: *paths – One or more file paths to validate.
Returns:: True if all paths are valid files.
Raises:: AssertionError – If any path is invalid or not a file.

Examples

Only real files pass:

>>> import tempfile
>>> from pathlib import Path
>>> from my import ut
>>> file = Path(tempfile.mkdtemp()) / 'data.txt'
>>> _ = file.write_text('hi')
>>> ut.validate_file(file)
True

classmethod SystemUtils.path_sub(path: Path, old: str, new: str) → Path#

Substitute a path component with a new value.

Parameters:

path – Path object to modify.
old – Path component to replace.
new – Replacement path component.

Returns:

New Path with substitution applied, or original if old not found.

Examples

Swap a single component:

>>> from pathlib import Path
>>> from my import ut
>>> ut.path_sub(Path('/repo/src/app.py'), 'src', 'lib')
PosixPath('/repo/lib/app.py')

`III` Terminal#

classmethod SystemUtils.get_terminal_width() → int#

Get the current terminal width in characters.

Returns:: Terminal width (defaults to 100 if unavailable).

classmethod SystemUtils.terminal_linewrap(text: str, indent: int = 0) → str#

Wrap text to fit within terminal width.

Parameters:

text – Text to wrap.
indent – Number of characters to reserve for indentation (default: 0).

Returns:

Text wrapped to terminal width minus indent.

Examples

Re-wrap prose to the current terminal (width varies by session):

>>> from my import ut
>>> ut.terminal_linewrap('A very long paragraph ...')
'A very long\nparagraph ...'

static SystemUtils.auto_confirm() → None#

Enable auto-confirmation mode for all confirmation prompts.

Examples

Make every subsequent confirm() return True (skipped: flips global state):

>>> from my import ut
>>> ut.auto_confirm()
>>> ut.confirm('Proceed?')
True

static SystemUtils.zsh_colorize(text: str, color: str, bold: bool = False, italic: bool = False, underline: bool = False) → str#

Wrap text in zsh color codes with optional styles.

Parameters:

text – Text to colorize.
color – Zsh color name or code.
bold – If True, apply bold style (default: False).
italic – If True, apply italic style (default: False).
underline – If True, apply underline style (default: False).

Returns:

Colorized text with zsh codes, or original text if color is empty.

Examples

Wrap text in zsh prompt-expansion codes, plus ANSI styling:

>>> from my import ut
>>> ut.zsh_colorize('hi', 'red')
'%F{red}hi%f'
>>> ut.zsh_colorize('hi', 'red', bold=True)
'\x1b[1m%F{red}hi%f\x1b[22m'

classmethod SystemUtils.print_in_color(text: str, **kwargs: Any) → None#

Print colored text using zsh prompt expansion.

Note

Requires zsh to be available in the system PATH. text is passed as an argv value (never interpolated into a shell string), so it reaches print -P via $1 and cannot trigger $(...)/backtick command substitution.

Parameters:

text – Text with zsh color codes already present.
**kwargs – Additional arguments for print().

Examples

Render zsh color codes to the terminal:

>>> from my import ut
>>> ut.print_in_color(ut.zsh_colorize('done', 'green'))
done

static SystemUtils.confirm(prompt: str, default_no: bool = False) → bool#

Prompt user for confirmation with y/n input.

Parameters:

prompt – Question to display to user.
default_no – If True, default to ‘no’ (default: False defaults to ‘yes’).

Returns:

True if user confirms, False otherwise. Always True if auto-confirm enabled.

Examples

Prompt interactively (unless auto_confirm() was enabled):

>>> from my import ut
>>> ut.confirm('Overwrite?')
Overwrite? [Y/n] y
True

static SystemUtils.is_installed(*modules: str) → bool#

Check if specified Python modules are installed.

Parameters:: *modules – Importable module names to check.
Returns:: True if every module imports cleanly, False otherwise.

Examples

Probe for optional dependencies:

>>> from my import ut
>>> ut.is_installed('json')
True
>>> ut.is_installed('not_a_module')
False

static SystemUtils.mock_if_uninstalled(target: str, *dependencies: str) → bool#

Mock the target module if any of the specified dependencies are not installed.

Parameters:

target – Module name to replace with a MagicMock in sys.modules.
*dependencies – Modules that must all be installed to leave the target untouched.

Returns:

True if all dependencies are installed, False if the target was mocked.

Examples

Stub out an optional integration when its backend is missing:

>>> from my import ut
>>> ut.mock_if_uninstalled('my_pkg.viz', 'matplotlib')
False

classmethod SystemUtils.multiprint(*items: Any, title: str = '', lines: Iterable[str] | None = None, data: dict | BaseModel | set | Sequence | None = None, indent: int = 0, indent_range: tuple[int, int] = (0, 0), shorten: bool = False, quiet: bool = False, margins: tuple[int, int] = (0, 1), **kwargs: Any) → str#

Flexibly print multiple lines with a few convenient features for plaintext formatting.

Parameters:

*items – Items to print after being converted to strings.
title – Title line(s) to print before any indented content. Sets indent to 4 if unset.
lines – Additional lines to print (in addition to the items), as an iterable of strings.
data – Additional key-value pairs to print as “key: value” lines after the items.
indent – Number of spaces to indent each line by.
indent_range – Optional subset of line indices to apply the indent to.
shorten – If true, apply some basic shortening techniques to the output.
quiet – Do not print anything to stdout, just return the formatted string.
margins – Number of newlines to print before and after the content.
**kwargs – Additional keyword arguments to pass to print().

Returns:

The constructed multiline string.

Examples

Compose a titled block; quiet returns it without printing:

>>> from my import ut
>>> out = ut.multiprint('a', 'b', title='Letters:', quiet=True)
>>> print(out, end='')
Letters:
    a
    b

static SystemUtils.debug_fence(content: Any, mark: str = '-', width: int = -1, indent: int = 0) → Generator#

Context manager for printing debug information with a clear visual fence.

Parameters:

content – Header content to display in the middle of the fence’s start.
mark – Character(s) to use for the fence lines.
width – Total width of the fence lines. Leave empty to try to infer terminal width.
indent – Number of spaces to indent the fence lines.

Examples

Fence a noisy block of output:

>>> from my import ut
>>> with ut.debug_fence('start', width=20):
...     print('body')
--------------------
------ start -------
body
--------------------

classmethod SystemUtils.path(raw: str | Path | None) → Path#

Attempt to resolve path with a flexible set of intuitive, iterative steps.

Parameters:: raw – A path which may or may not be absolute, existent, or even valid.
Returns:: Ideally a resolved version of that same path, else NOWHERE. NOWHERE is the single, non-traversable sentinel used across my for “no path”: it reports exists() as False and yields nothing from traversal methods.

Examples

Expand and resolve; unusable input collapses to the NOWHERE sentinel:

>>> from my import ut
>>> ut.path('~/notes.txt').is_absolute()
True
>>> ut.path(None)
NOWHERE

classmethod SystemUtils.log(*args: Any, _level: int = 0, **kwargs: Any) → None#

Log the provided collection of strings, applying common-sense transformations.

Nested iterables are flattened and stringified before joining, so info(), warn(), and error() all accept loosely-structured arguments.

Parameters:

*args – Values (or nested iterables of values) to join into one message.
_level – Numeric logging level to emit at.
**kwargs – Reserved for logger compatibility; currently unused.

Examples

Compose one message from loose parts:

>>> from my import ut
>>> ut.info('loaded', [1, 2], 'records')

classmethod SystemUtils.info(*args: Any, **kwargs: Any) → None#: Log the provided collection of strings at the INFO level.

classmethod SystemUtils.error(*args: Any, **kwargs: Any) → None#: Log the provided collection of strings at the ERROR level.

classmethod SystemUtils.warn(*args: Any, **kwargs: Any) → None#: Log the provided collection of strings at the WARNING level.

`IV` File I/O#

classmethod SystemUtils.from_file(file: str | bytes | Path | None) → dict#

classmethod SystemUtils.from_file(file: str | bytes | Path | None, tvar: type[F], cast: bool = True) → F

Load data from local JSON, YAML, TOML, or Pickle file, then cast to target type.

In order to cast between the by-far two most common expected types–dict and list–Typist will wrap uncastable values in a dict (w/ one key, 'content') or a list (w/ one value).

Parameters:

file – Path to the file to load. Note that raw content is NOT accepted here.
tvar – Target type to cast the loaded data to (dict by default). Like cast(), you can use complex, nested types here if desired.
cast – If True, try to coerce unexpected types before raising an error.

Returns:

Loaded and cast data from the file.

Examples

Round-trip a mapping through YAML on disk:

>>> import tempfile
>>> from pathlib import Path
>>> from my import ut
>>> file = Path(tempfile.mkdtemp()) / 'cfg.yaml'
>>> ut.to_file({'name': 'basis', 'tags': ['a', 'b']}, file)
>>> ut.from_file(file)
{'name': 'basis', 'tags': ['a', 'b']}

Save data to local JSON, YAML, TOML, or Pickle file (depending on file suffix).

Parameters:

data – The data to save.
file – Path to the file to save. Note that raw strings are NOT allowed here.

Examples

The suffix picks the serialization format:

>>> import tempfile
>>> from pathlib import Path
>>> from my import ut
>>> file = Path(tempfile.mkdtemp()) / 'data.json'
>>> ut.to_file([1, 2], file)
>>> ut.from_json(file, list)
[1, 2]

classmethod SystemUtils.from_json(file: str | bytes | Path | None) → dict#

classmethod SystemUtils.from_json(file: str | bytes | Path | None, tvar: type[F], cast: bool = True) → F

Load data from JSON file or string, then cast to target type. See from_file().

Parameters:

file – Path to the file to load, or raw JSON string/bytes.
tvar – Target type to cast the loaded data to (dict by default). Like cast(), you can use complex, nested types here if desired.
cast – If False, data that doesn’t match the expected return type raises an error.

Returns:

Loaded and cast data from the file/string.

Examples

Parse a raw string, casting to the requested type:

>>> from my import ut
>>> ut.from_json('{"a": 1}')
{'a': 1}
>>> ut.from_json('[1, 2]', list)
[1, 2]

classmethod SystemUtils.is_pathy(text: str) → bool#

Heuristic check for whether a string looks like a file path.

Parameters:: text – Candidate string.
Returns:: True if the string is path-length and contains path-like markers.

Examples

Separate paths from prose:

>>> from my import ut
>>> ut.is_pathy('~/notes/todo.md')
True
>>> ut.is_pathy('hello')
False

classmethod SystemUtils.from_yaml(file: str | bytes | Path | None) → dict#

classmethod SystemUtils.from_yaml(file: str | bytes | Path | None, tvar: type[F], cast: bool = True) → F

Load data from YAML file or string, then cast to target type. See from_file().

Note

Complete markdown fences tagged yaml or yml are unwrapped case-insensitively; spaces around the tag and surrounding block are ignored.

Parameters:

file – Path to the file to load, or raw YAML string/bytes.
tvar – Target type to cast the loaded data to (dict by default). Like cast(), you can use complex, nested types here if desired.
cast – If False, data that doesn’t match the expected return type raises an error.

Returns:

Loaded and cast data from the file/string.

Raises:

ValueError – If an input beginning with a markdown fence is not a complete yaml or yml block.

Examples

Parse raw or markdown-fenced YAML:

>>> from my import ut
>>> ut.from_yaml('a: 1\nb: [x, y]')
{'a': 1, 'b': ['x', 'y']}
>>> ut.from_yaml('```YML\nanswer: 42\n```')
{'answer': 42}

classmethod SystemUtils.from_toml(file: str | bytes | Path | None) → dict#

classmethod SystemUtils.from_toml(file: str | bytes | Path | None, tvar: type[F], cast: bool = True) → F

Load data from TOML file or string, then cast to target type. See from_file().

Parameters:

file – Path to the file to load, or raw TOML string/bytes.
tvar – Target type to cast the loaded data to (dict by default). Like cast(), you can use complex, nested types here if desired.
cast – If False, data that doesn’t match the expected return type raises an error.

Returns:

Loaded and cast data from the file/string.

Examples

Parse an in-memory TOML string:

>>> from my import ut
>>> ut.from_toml('x = 1')
{'x': 1}

classmethod SystemUtils.from_pickle(file: str | bytes | Path | None) → dict#

classmethod SystemUtils.from_pickle(file: str | bytes | Path | None, tvar: type[F], cast: bool = True) → F

Load data from Pickle file or bytes, then cast to target type. See from_file().

Parameters:

file – Path to the file to load, or raw Pickle bytes/string.
tvar – Target type to cast the loaded data to (dict by default). Like cast(), you can use complex, nested types here if desired.
cast – If False, data that doesn’t match the expected return type raises an error.

Returns:

Loaded and cast data from the file/string.

Examples

Round-trip through Pickle bytes:

>>> from my import ut
>>> ut.from_pickle(ut.to_pickle([1, 2]), list)
[1, 2]

Serialize data to a YAML string. See to_file() for general details.

Parameters:

data – The data to serialize.
wrap – If True, wrap the output in markdown backticks for YAML.
**kwargs – Additional keyword arguments to pass to srsly.yaml_dumps().

Returns:

YAML string representation of the data.

Examples

Serialize with the project’s block-style indentation:

>>> from my import ut
>>> print(ut.to_yaml({'a': 1, 'b': [1, 2]}), end='')
a: 1
b:
    - 1
    - 2

Serialize data to a JSON string. See to_file() for general details.

Parameters:

data – The data to serialize.
wrap – If True, wrap the output in markdown backticks for JSON.
**kwargs – Additional keyword arguments to pass to srsly.json_dumps().

Returns:

JSON string representation of the data.

Examples

Serialize with 4-space indentation:

>>> from my import ut
>>> print(ut.to_json({'a': 1}))
{
    "a":1
}

Serialize data to a TOML string. See to_file() for general details.

Parameters:

data – The data to serialize.
wrap – If True, wrap the output in markdown backticks for TOML.
**kwargs – Additional keyword arguments to pass to tomli_w.dumps().

Returns:

TOML string representation of the data.

Examples

Serialize a mapping:

>>> from my import ut
>>> print(ut.to_toml({'x': 1}), end='')
x = 1

Serialize data to Pickle bytes. See to_file() for general details.

Parameters:

data – The data to serialize.
**kwargs – Additional keyword arguments to pass to pickle.dumps().

Returns:

Pickle byte representation of the data.

Examples

Feed the bytes straight back to from_pickle():

>>> from my import ut
>>> ut.from_pickle(ut.to_pickle({'a': 1}))
{'a': 1}

classmethod SystemUtils.serialize(data: object, full: bool = False) → Any#

Thin wrapper around Typist.serialize() – see there for usage info.

Examples

Reduce rich types to JSON-friendly forms:

>>> from datetime import datetime, UTC
>>> from my import ut
>>> ut.serialize({3, 1, 2})
[1, 2, 3]
>>> ut.serialize(datetime(2026, 1, 1, tzinfo=UTC))
'2026-01-01T00:00:00'

`V` Shell#

static SystemUtils.ex(*args: str | list[str], cwd: str | Path | None = None, **kwargs: Any) → str | None#

Execute the given command as a shell-interpreted subprocess.

Any exception (including a non-zero exit) is swallowed; a caller that needs to distinguish “failed” from “produced no output” should shell out directly instead.

Parameters:

*args – Command and arguments to execute. Can be multiple strings or lists of strings.
cwd – Optional working directory to execute the command in.
**kwargs – Additional keyword arguments that are parsed into command line options (see _clean_shell_args()).

Returns:

The stripped stdout (or stderr, if stdout was empty) on success, else None.

Examples

Run a trivial command and capture its output:

>>> from my import ut
>>> ut.ex('echo', 'hi')
'hi'

classmethod SystemUtils.execute(*args: str | list[str], **kwargs: Any) → str | None#: Alias of ex(). Execute the given command as a shell-interpreted subprocess.

async static SystemUtils.exa(*args: str | Iterable[str], cwd: str | Path | None = None, **kwargs: Any) → str | None#

Execute the given command as a shell-interpreted subprocess, asynchronously.

See ex() for the argument/return contract; this is its asyncio counterpart.

Examples

>>> import asyncio
>>> from my import ut
>>> asyncio.run(ut.exa('echo', 'hi'))
'hi'

async classmethod SystemUtils.execute_async(*args: str, **kwargs: Any) → str | None#: Alias of exa(). Execute the given command as an async shell subprocess.

SystemUtils: System Utilities#

I Date & Time#

II Filesystem#

III Terminal#

IV File I/O#

V Shell#

`SystemUtils`: System Utilities#

`I` Date & Time#

`II` Filesystem#

`III` Terminal#

`IV` File I/O#

`V` Shell#