morphfits.utils.logs
====================

.. py:module:: morphfits.utils.logs

.. autoapi-nested-parse::

   Logging setup and utility functions.



Attributes
----------

.. autoapisummary::

   morphfits.utils.logs.LOGGER_MAX_BYTES
   morphfits.utils.logs.LOGGER_BACKUP_COUNT
   morphfits.utils.logs.LOGGING_DATE_FORMAT
   morphfits.utils.logs.LOGGING_COLOUR_ESCAPES


Classes
-------

.. autoapisummary::

   morphfits.utils.logs.UTCFormatter
   morphfits.utils.logs.FileFormatter
   morphfits.utils.logs.StreamFormatter


Functions
---------

.. autoapisummary::

   morphfits.utils.logs.resolve_record_name
   morphfits.utils.logs.create_logger


Module Contents
---------------

.. py:data:: LOGGER_MAX_BYTES
   :value: 1000000


   Default maximum bytes to be stored in each log file.

.. py:data:: LOGGER_BACKUP_COUNT
   :value: 100


   Default number of log files before rotation.

.. py:data:: LOGGING_DATE_FORMAT
   :value: '%Y-%m-%dT%H:%M:%S'


   Default logging date format, in ISO-8601 compliant format, e.g.
   `2024-05-01T12:43:21`.

.. py:data:: LOGGING_COLOUR_ESCAPES

   Colour codes for terminal.

.. py:function:: resolve_record_name(name: str) -> str

   Resolve a log record's module name to a more legible name, if it wasn't
   already.

   :param name: Record module name, e.g. `tqdm.tqdm`.
   :type name: str

   :returns: Legible record name.
   :rtype: str


.. py:class:: UTCFormatter(datefmt: str = LOGGING_DATE_FORMAT)

   Bases: :py:obj:`logging.Formatter`


   Logging formatter which uses GMT (UTC).

   :param logging.Formatter: Base formatter class to convert log records to text.
   :type logging.Formatter: class

   .. attribute:: converter

      Time converter.

      :type: function


   .. py:attribute:: converter


.. py:class:: FileFormatter(datefmt: str = LOGGING_DATE_FORMAT)

   Bases: :py:obj:`UTCFormatter`


   Logfile formatter which uses UTC.

   :param UTCFormatter: Base formatter class which uses UTC time.
   :type UTCFormatter: class


   .. py:method:: format(record: logging.LogRecord) -> str

      Format a log record as a str.

      :param record: Log record to format (line in log).
      :type record: logging.LogRecord

      :returns: Formatted log record.
      :rtype: str



.. py:class:: StreamFormatter(datefmt: str = LOGGING_DATE_FORMAT)

   Bases: :py:obj:`UTCFormatter`


   Stream log formatter which uses UTC.

   :param UTCFormatter: Base formatter class which uses UTC time.
   :type UTCFormatter: class


   .. py:method:: format(record: logging.LogRecord) -> str

      Format a log record as a coloured str for display.

      :param record: Log record to format (line in log).
      :type record: logging.LogRecord

      :returns: Formatted log record.
      :rtype: str



.. py:function:: create_logger(logger: logging.Logger = logging.getLogger(), filename: str | pathlib.Path = '.log', level: str = logging._levelToName[DEBUG], max_bytes: int = LOGGER_MAX_BYTES, backup_count: int = LOGGER_BACKUP_COUNT) -> logging.Logger

   Create or update a logger object with a rotating file and stream handler.

   :param logger: Logger object to create or update, by default a new logger.
   :type logger: Logger, optional
   :param filename: Name or path to file to log to, by default `.log`.
   :type filename: str | Path, optional
   :param level: Logging level to output, by default `WARNING`.
   :type level: str, optional
   :param max_bytes: Maximum bytes to be stored in each log file, by default 1,000,000.
   :type max_bytes: int, optional
   :param backup_count: Count of log files before rotation (first one is overwritten with new
                        data), by default 4.
   :type backup_count: int, optional

   :returns: Logger object for this program.
   :rtype: Logger