feat: v3.0.3

Author: ddc

README.md

@@ -7,10 +7,14 @@
 [![Build Status](https://img.shields.io/endpoint.svg?url=https%3A//actions-badge.atrox.dev/ddc/ddcLogs/badge?ref=main&style=plastic&label=build&logo=none)](https://actions-badge.atrox.dev/ddc/ddcLogs/goto?ref=main)
 
 
-# Logs
-+ Parameters for all classes are declared as OPTIONAL falling back to [.env](./ddcLogs/.env.example) file variables
-+ Default settings can be checked here: [settings.py](ddcLogs/settings.py)
 
+# Logs
++ Parameters for all classes are declared as OPTIONAL 
++ If any [.env](./ddcLogs/.env.example) variable is omitted, it falls back to default values here: [settings.py](ddcLogs/settings.py)
++ Timezone parameter can also accept `localtime`, default to `UTC`
+  + This parameter is only to display the timezone datetime inside the log file
+  + For timed rotation, only UTC and localtime are supported, meaning it will rotate at UTC or localtime
+    + env variable to change between UTC and localtime is `LOG_ROLL_OVER_AT_UTC` and default to True
 
 
 
@@ -31,12 +35,13 @@ logger = BasicLog(
     appname = "app",
     encoding = "UTF-8",
     datefmt = "%Y-%m-%dT%H:%M:%S",
-    utc = True,
+    timezone = "America/Sao_Paulo",
     showlocation = False, # This will show the filename and the line number where the message originated
 ).init()
 logger.warning("This is a warning example")
 ```
-
+#### Example of output
+`[2024-10-08T19:08:56.918-0300]:[WARNING]:[app]:This is a warning example`
 
 
 # SizeRotatingLog
@@ -55,13 +60,14 @@ logger = SizeRotatingLog(
     daystokeep = 7,
     encoding = "UTF-8",
     datefmt = "%Y-%m-%dT%H:%M:%S",
-    utc = True,
+    timezone = "America/Chicago",
     streamhandler = True, # Add stream handler along with file handler
     showlocation = False # This will show the filename and the line number where the message originated
 ).init()
 logger.warning("This is a warning example")
 ```
-
+#### Example of output
+`[2024-10-08T19:08:56.918-0500]:[WARNING]:[app]:This is a warning example`
 
 
 
@@ -85,19 +91,17 @@ logger = TimedRotatingLog(
     daystokeep = 7,
     encoding = "UTF-8",
     datefmt = "%Y-%m-%dT%H:%M:%S",
-    utc = True,
+    timezone = "UTC",
     streamhandler = True, # Add stream handler along with file handler
     showlocation = False # This will show the filename and the line number where the message originated
 ).init()
 logger.warning("This is a warning example")
 ```
+#### Example of output
+`[2024-10-08T19:08:56.918-0000]:[WARNING]:[app]:This is a warning example`
 
 
 
-### Example of output
-`[2024-10-08T19:08:56.918]:[WARNING]:[app]:This is a warning example`
-
-
 
 # Source Code
 ### Build
@@ -120,6 +124,7 @@ Released under the [MIT License](LICENSE)
 
 
 
+
 # Buy me a cup of coffee
 + [GitHub Sponsor](https://github.com/sponsors/ddc)
 + [ko-fi](https://ko-fi.com/ddcsta)

ddcLogs/.env.example

@@ -1,17 +1,18 @@
 LOG_LEVEL=DEBUG
-LOG_UTC=True
+LOG_TIMEZONE=UTC
 LOG_ENCODING=UTF-8
 LOG_APPNAME=app
 LOG_FILENAME=app.log
-LOG_DIRECTORY=./logs
+LOG_DIRECTORY=/app/logs
 LOG_DAYS_TO_KEEP=30
 LOG_STREAM_HANDLER=True
 LOG_SHOW_LOCATION=False
 LOG_DATE_FORMAT=%Y-%m-%dT%H:%M:%S
 
-# TimedRotatingLog
-LOG_ROTATING_WHEN=midnight
-LOG_ROTATING_FILE_SUFIX=%Y%m%d
-
 # SizeRotatingLog
 LOG_MAX_FILE_SIZE_MB=10
+
+# TimedRotatingLog
+LOG_ROTATE_WHEN=midnight
+LOG_ROTATE_AT_UTC=True
+LOG_ROTATE_FILE_SUFIX=%Y%m%d

ddcLogs/basic_log.py

@@ -1,9 +1,12 @@
 # -*- encoding: utf-8 -*-
 import logging
-import time
 from typing import Optional
-from .log_utils import get_format, get_level
-from .settings import LogSettings
+from ddcLogs.log_utils import (
+    get_format,
+    get_level,
+    get_timezone,
+)
+from ddcLogs.settings import LogSettings
 
 
 class BasicLog:
@@ -13,26 +16,23 @@ def __init__(
         appname: Optional[str] =  None,
         encoding: Optional[str] = None,
         datefmt: Optional[str] = None,
-        utc: Optional[bool] = None,
+        timezone: Optional[str] = None,
         showlocation: Optional[bool] = None,
     ):
         _settings = LogSettings()
         self.level = get_level(level or _settings.level)
         self.appname = appname or _settings.appname
         self.encoding = encoding or _settings.encoding
         self.datefmt = datefmt or _settings.date_format
-        self.utc = utc or _settings.utc
+        self.timezone = timezone or _settings.timezone
         self.showlocation = showlocation or _settings.show_location
 
     def init(self):
-        if self.utc:
-            logging.Formatter.converter = time.gmtime
-
-        formatt = get_format(self.showlocation, self.appname)
-        logging.basicConfig(level=self.level,
-                            datefmt=self.datefmt,
-                            encoding=self.encoding,
-                            format=formatt)
         logger = logging.getLogger(self.appname)
         logger.setLevel(self.level)
+        logging.Formatter.converter = get_timezone(self.timezone)
+        _format = get_format(self.showlocation, self.appname, self.timezone)
+        logging.basicConfig(datefmt=self.datefmt,
+                            encoding=self.encoding,
+                            format=_format)
         return logger

ddcLogs/log_utils.py

@@ -7,6 +7,9 @@
 import sys
 import time
 from datetime import datetime, timedelta
+from time import struct_time
+from typing import Any, Callable
+import pytz
 
 
 def get_stream_handler(
@@ -24,17 +27,16 @@ def get_logger_and_formatter(
     name: str,
      datefmt: str,
      show_location: bool,
-     utc: bool,
+     timezone: str,
 ) -> [logging.Logger, logging.Formatter]:
 
     logger = logging.getLogger(name)
     for handler in logger.handlers[:]:
         logger.removeHandler(handler)
 
-    formatt = get_format(show_location, name)
+    formatt = get_format(show_location, name, timezone)
     formatter = logging.Formatter(formatt, datefmt=datefmt)
-    if utc:
-        formatter.converter = time.gmtime
+    formatter.converter = get_timezone(timezone)
     return logger, formatter
 
 
@@ -79,7 +81,8 @@ def remove_old_logs(logs_dir: str, days_to_keep: int) -> None:
 
 def list_files(directory: str, ends_with: str) -> tuple:
     """
-    List all files in the given directory and returns them in a list sorted by creation time in ascending order
+    List all files in the given directory
+        and returns them in a list sorted by creation time in ascending order
     :param directory:
     :param ends_with:
     :return: tuple
@@ -219,7 +222,7 @@ def get_log_path(directory: str, filename: str) -> str:
     return log_file_path
 
 
-def get_format(show_location: bool, name: str | None) -> str:
+def get_format(show_location: bool, name: str, timezone: str) -> str:
     _debug_fmt = ""
     _logger_name = ""
 
@@ -229,7 +232,12 @@ def get_format(show_location: bool, name: str | None) -> str:
     if show_location:
         _debug_fmt = "[%(filename)s:%(funcName)s:%(lineno)d]:"
 
-    fmt = f"[%(asctime)s.%(msecs)03d]:[%(levelname)s]:{_logger_name}{_debug_fmt}%(message)s"
+    if timezone == "localtime":
+        utc_offset = time.strftime("%z")
+    else:
+        utc_offset = datetime.now(pytz.timezone(timezone)).strftime("%z")
+
+    fmt = f"[%(asctime)s.%(msecs)03d{utc_offset}]:[%(levelname)s]:{_logger_name}{_debug_fmt}%(message)s"
     return fmt
 
 
@@ -265,3 +273,15 @@ def gzip_file(source, output_partial_name) -> gzip:
         except OSError as e:
             write_stderr(f"Unable to delete_file old source log file | {source} | {repr(e)}")
             raise e
+
+
+def get_timezone(time_zone: str) -> (Callable[[float | None, Any], struct_time] |
+                                     Callable[[Any], struct_time]):
+
+    match time_zone.lower():
+        case "utc":
+            return time.gmtime
+        case "localtime":
+            return time.localtime
+        case _:
+            return lambda *args: datetime.now(tz=pytz.timezone(time_zone)).timetuple()

ddcLogs/settings.py

@@ -19,7 +19,7 @@ class LogLevel(str, Enum):
 
 
 class LogSettings(BaseSettings):
-    """ settings defined here with fallback to reading ENV variables """
+    """ If any ENV variable is omitted, it falls back to default values here """
     load_dotenv()
 
     level: Optional[LogLevel] = Field(default=LogLevel.INFO)
@@ -29,15 +29,16 @@ class LogSettings(BaseSettings):
     encoding: Optional[str] = Field(default="UTF-8")
     date_format: Optional[str] = Field(default="%Y-%m-%dT%H:%M:%S")
     days_to_keep: Optional[int] = Field(default=30)
-    utc: Optional[bool] = Field(default=True)
+    timezone: Optional[str] = Field(default="UTC")
     stream_handler: Optional[bool] = Field(default=True) # Add stream handler along with file handler
     show_location: Optional[bool] = Field(default=False) # This will show the filename and the line number where the message originated
 
     # SizeRotatingLog
     max_file_size_mb: Optional[int] = Field(default=10)
 
     # TimedRotatingLog
-    rotating_when: Optional[str] = Field(default="midnight")
-    rotating_file_sufix: Optional[str] = Field(default="%Y%m%d")
+    rotate_when: Optional[str] = Field(default="midnight")
+    rotate_at_utc: Optional[bool] = Field(default=True)
+    rotate_file_sufix: Optional[str] = Field(default="%Y%m%d")
 
     model_config = SettingsConfigDict(env_prefix="LOG_", env_file=".env", extra="allow")

ddcLogs/size_rotating.py

@@ -2,7 +2,7 @@
 import logging.handlers
 import os
 from typing import Optional
-from .log_utils import (
+from ddcLogs.log_utils import (
     check_directory_permissions,
     check_filename_instance,
     get_level, get_log_path,
@@ -12,7 +12,7 @@
     list_files,
     remove_old_logs, write_stderr,
 )
-from .settings import LogSettings
+from ddcLogs.settings import LogSettings
 
 
 class SizeRotatingLog:
@@ -26,7 +26,7 @@ def __init__(
         daystokeep: Optional[int] = None,
         encoding: Optional[str] = None,
         datefmt: Optional[str] = None,
-        utc: Optional[bool] = None,
+        timezone: Optional[str] = None,
         streamhandler: Optional[bool] = None,
         showlocation: Optional[bool] = None,
     ):
@@ -39,7 +39,7 @@ def __init__(
         self.daystokeep = daystokeep or _settings.days_to_keep
         self.encoding = encoding or _settings.encoding
         self.datefmt = datefmt or _settings.date_format
-        self.utc = utc or _settings.utc
+        self.timezone = timezone or _settings.timezone
         self.streamhandler = streamhandler or _settings.stream_handler
         self.showlocation = showlocation or _settings.show_location
 
@@ -51,7 +51,7 @@ def init(self):
         logger, formatter = get_logger_and_formatter(self.appname,
                                                      self.datefmt,
                                                      self.showlocation,
-                                                     self.utc)
+                                                     self.timezone)
         logger.setLevel(self.level)
 
         for file in self.filenames:

ddcLogs/timed_rotating.py

@@ -2,17 +2,17 @@
 import logging.handlers
 import os
 from typing import Optional
-from .log_utils import (
+from ddcLogs.log_utils import (
     check_directory_permissions,
     check_filename_instance,
     get_level,
     get_log_path,
     get_logger_and_formatter,
     get_stream_handler,
     gzip_file,
-    remove_old_logs
+    remove_old_logs,
 )
-from .settings import LogSettings
+from ddcLogs.settings import LogSettings
 
 
 class TimedRotatingLog:
@@ -33,23 +33,25 @@ def __init__(
         daystokeep: Optional[int] = None,
         encoding: Optional[str] = None,
         datefmt: Optional[str] = None,
-        utc: Optional[bool] = None,
+        timezone: Optional[str] = None,
         streamhandler: Optional[bool] = None,
         showlocation: Optional[bool] = None,
+        rotateatutc: Optional[bool] = None,
     ):
         _settings = LogSettings()
         self.level = get_level(level or _settings.level)
         self.appname = appname or _settings.appname
         self.directory = directory or _settings.directory
         self.filenames = filenames or (_settings.filename,)
-        self.when = when or _settings.rotating_when
-        self.sufix = sufix or _settings.rotating_file_sufix
+        self.when = when or _settings.rotate_when
+        self.sufix = sufix or _settings.rotate_file_sufix
         self.daystokeep = daystokeep or _settings.days_to_keep
         self.encoding = encoding or _settings.encoding
         self.datefmt = datefmt or _settings.date_format
-        self.utc = utc or _settings.utc
+        self.timezone = timezone or _settings.timezone
         self.streamhandler = streamhandler or _settings.stream_handler
         self.showlocation = showlocation or _settings.show_location
+        self.rotateatutc = rotateatutc or _settings.rotate_at_utc
 
     def init(self):
         check_filename_instance(self.filenames)
@@ -58,7 +60,7 @@ def init(self):
         logger, formatter = get_logger_and_formatter(self.appname,
                                                      self.datefmt,
                                                      self.showlocation,
-                                                     self.utc)
+                                                     self.timezone)
         logger.setLevel(self.level)
 
         for file in self.filenames:
@@ -68,7 +70,7 @@ def init(self):
                 filename=log_file_path,
                 encoding=self.encoding,
                 when=self.when,
-                utc=self.utc,
+                utc=self.rotateatutc,
                 backupCount=self.daystokeep
             )
             file_handler.suffix = self.sufix
@@ -86,7 +88,6 @@ def init(self):
 
         return logger
 
-
 class GZipRotatorTimed:
     def __init__(self, dir_logs: str, days_to_keep: int):
         self.dir = dir_logs