cement.utils.misc

Misc utilities.

class cement.utils.misc._SafeFileHandler(filename, mode='a', encoding=None, delay=False, errors=None)

Bases: FileHandler

A logging.FileHandler that never lets a file I/O failure reach the host application.

Framework logging (see minimal_logger()) is a silent development aid enabled via CEMENT_FRAMEWORK_LOG_FILE. A misconfigured or unwritable path – a directory, an existing read-only file, a disk that fills up mid-run, a path removed while running – must not crash the application or spam its stderr. Any error raised while opening or writing the log file is swallowed.

emit(record: LogRecord) → None

Emit a record.

If the stream was not opened because ‘delay’ was specified in the constructor, open it before calling the superclass’s emit.

If stream is not open, current mode is ‘w’ and _closed=True, record will not be emitted (see Issue #42378).

handleError(record: LogRecord) → None

Handle errors which occur during an emit() call.

This method should be called from handlers when an exception is encountered during an emit() call. If raiseExceptions is false, exceptions get silently ignored. This is what is mostly wanted for a logging system - most users will not care about errors in the logging system, they are more interested in application errors. You could, however, replace this with a custom handler if you wish. The record which was being processed is passed in to this method.

cement.utils.misc.init_defaults(*sections: str) → dict[str, Any]

Returns a standard dictionary object to use for application defaults. If sections are given, it will create a nested dict for each section name. This is sometimes more useful, or cleaner than creating an entire dict set (often used in testing).

Parameters:

sections – Section keys to create nested dictionaries for.

Returns:

Dictionary of nested dictionaries (sections)

Return type:

dict

Example

from cement import App, init_defaults

defaults = init_defaults('myapp', 'section2', 'section3')
defaults['myapp']['debug'] = False
defaults['section2']['foo'] = 'bar
defaults['section3']['foo2'] = 'bar2'

app = App('myapp', config_defaults=defaults)

cement.utils.misc.is_true(item: Any) → bool

Given a value, determine if it is one of [True, 'true', 'yes', 'y', 'on', '1', 1,] (note: strings are converted to lowercase before comparison).

Parameters:

item – The item to convert to a boolean.

Returns:

True if item equates to a true-ish value, False

otherwise

Return type:

bool

cement.utils.misc.minimal_logger(namespace: str, debug: bool = False) → MinimalLogger

Setup just enough for cement to be able to do debug logging. This is the logger used by the Cement framework, which is setup and accessed before the application is functional (and more importantly before the applications log handler is usable).

Framework logging is toggled by the usual switches (CEMENT_LOG, debug=True, --debug, or the deprecated CEMENT_FRAMEWORK_LOGGING). When framework logging is enabled, setting the CEMENT_FRAMEWORK_LOG_FILE environment variable to a path also writes that output to the given file (in addition to the console). Setting the variable alone does not enable logging, and an unwritable/invalid path is ignored rather than raising.

Parameters:

namespace (str) – The logging namespace. This is generally __name__ or anything you want.

Keyword Arguments:

debug (bool) – Toggle debug output.

Returns:

A Logger object

Return type:

object

Example

from cement.utils.misc import minimal_logger
LOG = minimal_logger('cement')
LOG.debug('This is a debug message')

cement.utils.misc.rando(salt: str | None = None) → str

Generate a random hash for whatever purpose. Useful for testing or any other time that something random is required.

Parameters:

salt (str) – Optional salt, if None then random.random() is used.

Returns:

Random hash

Return type:

str

Example

from cement.utils.misc import rando

rando('dAhn49amvnah3m')

cement.utils.misc.random() → x in the interval [0, 1).

cement.utils.misc.wrap(text: str, width: int = 77, indent: str = '', long_words: bool = False, hyphens: bool = False) → str

Wrap text for cleaner output (this is a simple wrapper around textwrap.TextWrapper in the standard library).

Parameters:

text (str) – The text to wrap

Keyword Arguments:

• width (int) – The max width of a line before breaking

• indent (str) – String to prefix subsequent lines after breaking

• long_words (bool) – Whether or not to break on long words

• hyphens (bool) – Whether or not to break on hyphens

Returns:

The wrapped string

Return type:

str