contaix.util

General utilities for contaix

This module provides core utility functions used throughout the contaix package, including:

• File path handling (fullpath)

• URL detection and content retrieval (is_url, url_to_contents)

• File saving utilities (save_to_file_and_return_file)

• Basic helper functions (identity)

Functions

fullpath(path)	Returns the full path of the given path.
identity(x)	Returns the input unchanged.
is_url(path)	Check if the given path is a URL.
remove_improperly_double_newlines(string, *)	Remove improperly double newlines from a string.
save_to_file_and_return_file([obj, encoder, key])	Save encoder(obj) to a file using a random name in rootdir (or a temp directory if not provided).
source_first_arg_from_clipboard_if_none(func)	Decorator that sources a string argument from the clipboard when it's None and copies the function's return value back to the clipboard when the keyword argument copy_to_clipboard is truthy.
url_to_contents(url, *[, kind, timeout])	Fetch the content from a URL.

contaix.util.fullpath(path)

Returns the full path of the given path.

Parameters:

path (str) – The path to convert to a full path.

Returns:

The full path.

Return type:

str

Example

>>> fullpath('~/Downloads')
'/home/user/Downloads'

>>> fullpath('.')
'/home/user/python_projects/aix/aix'

contaix.util.identity(x)

Returns the input unchanged.

Parameters:

x – Any input

Returns:

The input unchanged

contaix.util.is_url(path)

Check if the given path is a URL.

Parameters:

path (str) – Path to check

Returns:

True if the path is a URL, False otherwise

Return type:

bool

contaix.util.remove_improperly_double_newlines(string, *, copy_to_clipboard=True)

Remove improperly double newlines from a string.

Delegates to dn.repair.remove_improperly_double_newlines for the pure transform, adding clipboard integration via the decorator.

Parameters:

string (str | None) – The input string.

Returns:

The string with improperly double newlines removed.

Return type:

str

Example

>>> text = "This is a test.\n\nThis should be one newline.\n  \nThis too."
>>> result = remove_improperly_double_newlines(text, copy_to_clipboard=False)
>>> assert result == 'This is a test.\n\nThis should be one newline.\nThis too.'

contaix.util.save_to_file_and_return_file(obj=None, *, encoder=<function identity>, key=None)

Save encoder(obj) to a file using a random name in rootdir (or a temp directory if not provided). Returns the full path to the saved file. If obj is None, returns a partial function with preconfigured encoder and rootdir.

Parameters:

• obj – The object to save. If None, return a partial function.

• encoder – A function to encode the object into text or bytes. Defaults to identity.

• key (str | Callable) – The key (by default, filepath) to write to. If None, a temporary file is created. If a string starting with ‘*’, the ‘*’ is replaced with a unique temporary filename. If a string that has a ‘*’ somewhere in the middle, what’s on the left of if is used as a directory and the ‘*’ is replaced with a unique temporary filename. For example ‘/tmp/*_file.ext’ would be replaced with ‘/tmp/oiu8fj9873_file.ext’. If a callable, it will be called with obj as input to get the key. One use case is to use a function that generates a key based on the object.

Returns:

Full path to the saved file, or a partial function if obj is None.

Return type:

str

Examples

>>> from pathlib import Path
>>> filepath = save_to_file_and_return_file("hello world")
>>> import os
>>> Path(filepath).read_text()
'hello world'

The default encoder is identity, so you can save binary data as well:

>>> filepath = save_to_file_and_return_file(b"binary data", encoder=lambda x: x)
>>> Path(filepath).read_bytes()
b'binary data'

contaix.util.source_first_arg_from_clipboard_if_none(func)

Decorator that sources a string argument from the clipboard when it’s None and copies the function’s return value back to the clipboard when the keyword argument copy_to_clipboard is truthy.

The wrapped function must accept a parameter named string. It may also accept a keyword-only parameter named copy_to_clipboard (default True).

contaix.util.url_to_contents(url, *, kind='binary', timeout=10)

Fetch the content from a URL.

Parameters:

• url (str) – The URL to fetch.

• kind (str) – The kind of content to fetch (‘text’, ‘binary’, or ‘response’). Defaults to ‘binary’.

• timeout (int) – Timeout for the request in seconds. Default is 10 seconds.

Returns:

The content of the URL if successful, None otherwise.

Return type:

Optional[bytes]