Reference

See Apple’s documentation for further information about macOS logging.

Constants

Log objects

pyoslog.OS_LOG_DEFAULT: os_log_t = The shared disabled log.

pyoslog.OS_LOG_DISABLED: os_log_t = The shared default log.

Log levels/types

pyoslog.OS_LOG_TYPE_DEBUG: int = The debug log level.

pyoslog.OS_LOG_TYPE_INFO: int = The informational log level.

pyoslog.OS_LOG_TYPE_DEFAULT: int = The default log level.

pyoslog.OS_LOG_TYPE_ERROR: int = The error log level.

pyoslog.OS_LOG_TYPE_FAULT: int = The fault log level.

Methods

pyoslog.is_supported() → bool

Unified logging is only present in macOS 10.12 and later, but it is nicer to not have to check OS type or version strings when installing or importing pyoslog. Use this method at runtime to check whether the module is supported.

It is important to note that if is_supported() is False then none of the module’s other methods or constants will exist.

pyoslog.log(*message: Any, log_object: os_log_t = OS_LOG_DEFAULT, log_type: int = OS_LOG_TYPE_DEFAULT) → None

A helper method, equivalent to os_log_with_type() with pyoslog.OS_LOG_DEFAULT and pyoslog.OS_LOG_TYPE_DEFAULT, but with default keyword arguments for convenience.

pyoslog.os_log(log_object: os_log_t, *message: Any) → None

Sends a default-level message to the logging system. See the native method documentation.

pyoslog.os_log_create(subsystem: str, category: str) → os_log_t

Creates a custom log object. See the native method documentation.

pyoslog.os_log_debug(log_object: os_log_t, *message: Any) → None

Sends a debug-level message to the logging system. See the native method documentation.

pyoslog.os_log_debug_enabled(log_object: os_log_t) → bool

Returns a bool value that indicates whether debug-level logging is enabled for a specified log object. See the native method documentation.

pyoslog.os_log_error(log_object: os_log_t, *message: Any) → None

Sends an error-level message to the logging system. See the native method documentation.

pyoslog.os_log_fault(log_object: os_log_t, *message: Any) → None

Sends a fault-level message to the logging system. See the native method documentation.

pyoslog.os_log_info(log_object: os_log_t, *message: Any) → None

Sends an info-level message to the logging system. See the native method documentation.

pyoslog.os_log_info_enabled(log_object: os_log_t) → bool

Returns a bool value that indicates whether info-level logging is enabled for a specified log object. See the native method documentation.

pyoslog.os_log_type_enabled(log_object: os_log_t, log_type: int) → bool

Returns a bool value that indicates whether the log can write messages with the specified log type. See the native method documentation.

pyoslog.os_log_with_type(log_object: os_log_t, log_type: int, *message: Any) → None

Sends a message at a specified level, such as default, info, debug, error or fault, to the logging system. See the native method documentation.

Handler

class pyoslog.Handler(subsystem: str | None = None, category: str = 'default')

This logging Handler forwards all messages to pyoslog. The logging level is converted to the matching pyoslog.OS_LOG_TYPE_* type, and messages outputted to the unified log.

The default output level is pyoslog.OS_LOG_TYPE_DEFAULT. This can be configured as normal via setLevel().

The default output behaviour is to log to pyoslog.OS_LOG_DEFAULT. This can be configured either by calling setSubsystem(), or by providing these arguments when creating a Handler instance.

If a subsystem is provided, a custom os_log object is created using that subsystem. If a category is also provided, it will be used; otherwise, 'default' is used as the category name. If no subsystem is provided, pyoslog.OS_LOG_DEFAULT is used, and the category parameter is ignored.

Parameters:

• subsystem (Optional[str]) – The subsystem for os_log (e.g., 'com.example.myapp'). If subsystem is None or not provided, pyoslog.OS_LOG_DEFAULT is used.

• category (str = 'default') – The category for os_log. Used only if subsystem is not None. Defaults to 'default' if not provided.

setSubsystem(subsystem: str, category: str = 'default') → None

Sets the subsystem (typically reverse DNS notation), and optionally a category to allow further filtering.