log.transport

import log

Everything here is re-exported by log, so import log is enough and the names are called as log.*. Importing log.transport on its own works too and reaches the same definitions.

The Transport base class every log sink (console, file, or a custom subclass) is built on, plus the registry of active transports and the shared dispatch loop every level function writes through. These live in the same file as Transport itself (rather than off in dispatch.zu alongside default_transport()) specifically so Transport.close() can remove itself from the registry without a cross-file call back into a file that in turn depends on this one: console.zu/file.zu need Transport from here, and dispatch.zu needs ConsoleTransport from console.zu, so a Transport depending on dispatch.zu for remove_transport() would be a genuine import cycle. Keeping the registry here instead keeps every dependency pointing one direction.

Functions

add_transport()

log.add_transport(transport)

Adds a new transport service to the list of registered transports. If the transport has been previously added, this function will do nothing.

Parameters

• transport (log.Transport)

remove_transport()

log.remove_transport(transport)

Removes the given transport service from the list of registered transports.

Parameters

• transport (log.Transport)

Classes

Transport

class log.Transport

The Transport class acts as the base class for log transports and handle the actual logging of the specified log records.

Transport.set_level()

log.Transport.set_level(level)

Sets the threshold level for this transport to handle. Logging messages which are less severe than level will be ignored. Unless overridden by the transport implementation, when a handler is created, the level is set to [[log.None]] (which causes all messages to be processed).

Parameters

• level (log.LogLevel)

Returns — self

Transport.get_level()

log.Transport.get_level() -> [[log.LogLevel]]

The threshold level of this transport. The default level is [[log.LogLevel.None]].

Returns [[log.LogLevel]]

Transport.set_max_level()

log.Transport.set_max_level(level)

Sets the maximum threshold level for this transport to handle. Logging messages which are more severe than level will be ignored. Unless overridden by the transport implementation, when a handler is created, the maximum level is set to [[log.Critical]] (which causes all messages to be processed).

Parameters

• level (log.LogLevel)

Returns — self

Transport.get_max_level()

log.Transport.get_max_level() -> [[log.LogLevel]]

The maximum threshold level of this transport. The default maximum level is [[log.Critical]].

Returns [[log.LogLevel]]

Transport.set_name()

log.Transport.set_name(name)

Sets the name of the current transport.

Parameters

• name (string)

Returns — self

Transport.get_name()

log.Transport.get_name() -> string

Returns the name of the current transport. By default, name will be equal to the name of the directory containing the root file.

Returns string

Transport.set_time_format()

log.Transport.set_time_format(format)

Sets the time formatting string used by the transport when [[log.Transport.show_time]] is set to true.

Parameters

• format (string)

Returns — self

Transport.get_time_format()

log.Transport.get_time_format() -> string

Returns the time formatting string used by the current transport. The default value is c.

Returns string

Transport.show_name()

log.Transport.show_name(show)

Enable or disable showing transport names in the logs based on the passed boolean value.

Parameters

• show (bool)

Returns — self

Transport.show_time()

log.Transport.show_time(show)

Enables or disables showing logging time in the logs based on the passed boolean value.

Parameters

• show (bool)

Returns — self

Transport.show_level()

log.Transport.show_level(show)

Enable or disable showing transport log level in the logs based on the passed boolean value.

Parameters

• show (bool)

Returns — self

Transport.set_formatter()

log.Transport.set_formatter(formatter)

Sets a formatter function that overrides a transports format() function.

The formatter function is a function that when it is set overrides the transports default format method and must MUST have the contract def my_function(records, level, transport). The transport parameter here is the instance of the current transport. See [[log.Transport.format]] for what records, and level means.

Parameters

• formatter (function)

Returns — self

Transport.get_formatter()

log.Transport.get_formatter() -> ?function

Returns the format method override that has been set for the current transport or nil if none has been set.

Returns ?function

Transport.can_log()

log.Transport.can_log(level) -> bool

Returns a boolean value which indicates if a message of severity level can be processed by this transport.

[[log.LogLevel.None]] is a documented escape hatch that bypasses level filtering entirely (only enable()/disable() still applies to it): see the module doc’s “quick logging” section.

Parameters

• level (log.LogLevel)

Returns bool

Transport.enable()

log.Transport.enable()

Enables and starts processing of logs by the current transport.

Returns — self

Transport.disable()

log.Transport.disable()

Disables and stops the current transport from processing further logs.

Returns — self

Transport.format()

log.Transport.format(records, level, context) -> any

Formats the log records for the current level for writing to the transport’s stream. The default implementation of this method is exactly as seen when using the [[log.default_transport]] which logs to the console. The method should be overridden by subclasses to get a custom formatting.

When the last element of records is a dict, it’s treated as structured fields rather than a plain message argument and rendered as trailing key=value pairs: log.info('processing', { user_id: 5 }) renders as ... processing user_id=5. Fields bound via a [[log.Logger]] (through context) are merged in the same way.

IMPORTANT!

The result of this function will be passed into the [[log.Transport.write()]] function so transport implementations MUST ensure to expect the same type as is returned from this function in the [[log.Transport.write()]] function message parameter.

Transport implementations should be aware of the following available private fields in the transport class:

• [[log.LogLevel]] self._level - string self._log_name - bool self._show_name - bool self._show_time - bool self._show_level

Parameters

• records (list[any])
• level (log.LogLevel)
• context (?dict) — Optional {name: ?string, fields: dict}, supplied by a [[log.Logger]] call; absent for the flat module-level log.info()-style calls.

Returns any

Transport.write()

log.Transport.write(message, level)

Do whatever it takes to actually log the specified logging record. This method is intended to be implemented by subclasses and so raises an Error if called directly from Transport.

Parameters

• message (any)
• level (log.LogLevel)

Raises NotImplementedError

Transport.flush()

log.Transport.flush()

Ensure all logging output has been flushed to the target stream. This default version does nothing and is intended to be implemented by subclasses.

Transport.close()

log.Transport.close()

Tidy up any resources used by the transport. This default version does no output but removes the handler from an internal list of handlers. Subclasses should ensure that this gets called from overridden close() methods.