From 6fc4cebbfe11b915f4c4e5168773abfef5ccf647 Mon Sep 17 00:00:00 2001 From: Sven Heidemann Date: Mon, 17 May 2021 17:45:22 +0200 Subject: [PATCH] Added docs for cpl.logging --- src/cpl/logging/logger_abc.py | 98 +++++++++++++++++------------ src/cpl/logging/logger_service.py | 85 +++++++++++++++---------- src/cpl/logging/logging_settings.py | 1 + 3 files changed, 112 insertions(+), 72 deletions(-) diff --git a/src/cpl/logging/logger_abc.py b/src/cpl/logging/logger_abc.py index 98ef4eb9..a6bfa72f 100644 --- a/src/cpl/logging/logger_abc.py +++ b/src/cpl/logging/logger_abc.py @@ -2,81 +2,101 @@ from abc import abstractmethod, ABC class LoggerABC(ABC): + r"""ABC for :class:`cpl.logging.logger_service.Logger`""" @abstractmethod def __init__(self): - """ - ABC for logging - """ ABC.__init__(self) @abstractmethod def header(self, string: str): - """ - Writes a header message - :param string: - :return: + r"""Writes a header message + + Parameter + --------- + string: :class:`str` + String to write as header """ pass @abstractmethod def trace(self, name: str, message: str): - """ - Writes a trace message - :param name: - :param message: - :return: + r"""Writes a trace message + + Parameter + --------- + name: :class:`str` + Message name + message: :class:`str` + Message string """ pass @abstractmethod def debug(self, name: str, message: str): - """ - Writes a debug message - :param name: - :param message: - :return: + r"""Writes a debug message + + Parameter + --------- + name: :class:`str` + Message name + message: :class:`str` + Message string """ pass @abstractmethod def info(self, name: str, message: str): - """ - Writes an information - :param name: - :param message: - :return: + r"""Writes an information + + Parameter + --------- + name: :class:`str` + Message name + message: :class:`str` + Message string """ pass @abstractmethod def warn(self, name: str, message: str): - """ - Writes an warning - :param name: - :param message: - :return: + r"""Writes an warning + + Parameter + --------- + name: :class:`str` + Message name + message: :class:`str` + Message string """ pass @abstractmethod def error(self, name: str, message: str, ex: Exception = None): - """ - Writes an error - :param name: - :param message: - :param ex: - :return: + r"""Writes an error + + Parameter + --------- + name: :class:`str` + Error name + message: :class:`str` + Error message + ex: :class:`Exception` + Thrown exception """ pass @abstractmethod def fatal(self, name: str, message: str, ex: Exception = None): - """ - Writes an error and exits - :param name: - :param message: - :param ex: - :return: + r"""Writes an error and ends the program + + Parameter + --------- + name: :class:`str` + Error name + message: :class:`str` + Error message + ex: :class:`Exception` + Thrown exception """ pass diff --git a/src/cpl/logging/logger_service.py b/src/cpl/logging/logger_service.py index 4c04a5d2..b27e1320 100644 --- a/src/cpl/logging/logger_service.py +++ b/src/cpl/logging/logger_service.py @@ -13,14 +13,19 @@ from cpl.time.time_format_settings import TimeFormatSettings class Logger(LoggerABC): + r"""Service for logging + + Parameter + --------- + logging_settings: :class:`cpl.logging.logging_settings.LoggingSettings` + Settings for the logger + time_format: :class:`cpl.time.time_format_settings.TimeFormatSettings` + Time format settings + env: :class:`cpl.environment.application_environment_abc.ApplicationEnvironmentABC` + Environment of the application + """ def __init__(self, logging_settings: LoggingSettings, time_format: TimeFormatSettings, env: ApplicationEnvironmentABC): - """ - Service for logging - :param logging_settings: - :param time_format: - :param app_runtime: - """ LoggerABC.__init__(self) self._env = env @@ -38,9 +43,11 @@ class Logger(LoggerABC): self.create() def _get_datetime_now(self) -> str: - """ - Returns the date and time by given format - :return: + r"""Returns the date and time by given format + + Returns + ------- + Date and time in given format """ try: return datetime.datetime.now().strftime(self._time_format_settings.date_time_format) @@ -48,9 +55,11 @@ class Logger(LoggerABC): self.error(__name__, 'Cannot get time', ex=e) def _get_date(self) -> str: - """ - Returns the date by given format - :return: + r"""Returns the date by given format + + Returns + ------- + Date in given format """ try: return datetime.datetime.now().strftime(self._time_format_settings.date_format) @@ -58,10 +67,7 @@ class Logger(LoggerABC): self.error(__name__, 'Cannot get date', ex=e) def create(self) -> None: - """ - Creates path tree and logfile - :return: - """ + r"""Creates path tree and logfile""" """ path """ try: @@ -81,11 +87,12 @@ class Logger(LoggerABC): except Exception as e: self._fatal_console(__name__, 'Cannot open log file', ex=e) - def _append_log(self, string): - """ - Writes to logfile - :param string: - :return: + def _append_log(self, string: str): + r"""Writes to logfile + + Parameter + --------- + string: :class:`str` """ try: # open log file and append always @@ -99,12 +106,20 @@ class Logger(LoggerABC): self._fatal_console(__name__, f'Cannot append log file, message: {string}', ex=e) def _get_string(self, name: str, level: LoggingLevelEnum, message: str) -> str: - """ - Returns input as log entry format - :param name: - :param level: - :param message: - :return: + r"""Returns input as log entry format + + Parameter + --------- + name: :class:`str` + Name of the message + level: :class:`cpl.logging.logging_level_enum.LoggingLevelEnum` + Logging level + message: :class:`str` + Log message + + Returns + ------- + Formatted string for logging """ log_level = level.name return f'<{self._get_datetime_now()}> [ {log_level} ] [ {name} ]: {message}' @@ -209,12 +224,16 @@ class Logger(LoggerABC): exit() def _fatal_console(self, name: str, message: str, ex: Exception = None): - """ - Writes an error to console only - :param name: - :param message: - :param ex: - :return: + r"""Writes an error to console only + + Parameter + --------- + name: :class:`str` + Error name + message: :class:`str` + Error message + ex: :class:`Exception` + Thrown exception """ output = '' if ex is not None: diff --git a/src/cpl/logging/logging_settings.py b/src/cpl/logging/logging_settings.py index 20f87650..6b7128e1 100644 --- a/src/cpl/logging/logging_settings.py +++ b/src/cpl/logging/logging_settings.py @@ -9,6 +9,7 @@ from cpl.logging.logging_settings_name_enum import LoggingSettingsNameEnum class LoggingSettings(ConfigurationModelABC): + r"""Representation of logging settings""" def __init__(self): ConfigurationModelABC.__init__(self)