feat: Add file_mode and file_encoding parameters to get_logger for finer control over the way a simple logger handles files.

Author: MPCodeWriter21

CHANGELOG.md

@@ -6,6 +6,26 @@ Help this project by [Donation](DONATE.md)
 Changes
 -------
 
+### v3.2.0
+
+Add `file_mode` and `file_encoding` parameters to `get_logger` for finer control over
+the way a simple logger handles files.
+
+For even more control you can still define Logger, Handlers, and Formatters manually.
+
+#### Example
+
+```python
+import log21
+
+logger = log21.get_logger(
+    "My File Logger", show_level=False, show_time=True, file="myapp.log", file_mode="a",
+    file_encoding="utf-8"
+)
+
+logger.info("Hello World!")
+```
+
 ### v3.1.0
 
 Change the way `argumentify` handles function parameters to argument-parser arguments

README.md

@@ -69,140 +69,26 @@ pip install git+https://github.com/MPCodeWriter21/log21
 Changelog
 ---------
 
-### v3.1.0
+### v3.2.0
 
-Change the way `argumentify` handles function parameters to argument-parser arguments
-conversion.
+Add `file_mode` and `file_encoding` parameters to `get_logger` for finer control over
+the way a simple logger handles files.
 
-+ `POSITIONAL_ONLY` and `VAR_POSITIONAL` parameters will be positional arguments.
-+ `POSITIONAL_OR_KEYWORD` and `KEYWORD_ONLY` parameters have flags assigned to them.
-+ `POSITIONAL_OR_KEYWORD` parameters will be required if at least one `KEYWORD_ONLY`
-  parameter is there, otherwise they are optional.
-+ `VAR_KEYWORD` parameters are still not supported.
+For even more control you can still define Logger, Handlers, and Formatters manually.
 
-#### Example 1
+#### Example
 
 ```python
-def main(path: Path, /, output: Path, *, verbose: bool = False):
-    """Process a file.
+import log21
 
-    :param path: The input file path
-    :param output: The output file
-    :param verbose: Write more logs to the standard output.
-    """
-    ...
-
-
-if __name__ == "__main__":
-    argumentify(main)
-```
-
-The help looks like this:
-
-```help
-usage: test.py [-h] --output OUTPUT [--verbose] path
-
-Process a file.
-
-positional arguments:
-  path              The input file path
-
-options:
-  -h, --help
-                        show this help message and exit
-  --output OUTPUT, -o OUTPUT
-                        The output file
-  --verbose, -v
-                        Write more logs to the standard output.
-
-```
-
-_Note that `path` and `output` are required._
-
-#### Example 2
-
-```python
-def main(output: Path, /, *inputs: Path):
-    """Process multiple files into one.
-
-    :param output: The output file
-    :param inputs: The path to the input files
-    """
-    # Since `inputs` is a VAR_POSITIONAL, while being a positional argument, it can have
-    # zero length which is in many cases not intended.
-    # You might want to add a check for its length and raise an ArgumentError if it does
-    # not match your needs
-
-    # Check if at least one input has been passed and mark the argument as required
-    # if len(inputs) < 1:
-    #     raise RequiredArgumentError("inputs")
-
-    # Raise an error unless at least two inputs are present
-    if len(inputs) < 2:
-        raise ArgumentError(message="You need to pass at least two files as input.")
-    ...
-```
-
-The help looks like this:
-
-```help
-usage: test.py [-h] output [inputs ...]
-
-Process multiple files into one.
-
-positional arguments:
-  output            The output file
-  inputs            The path to the input files
-
-options:
-  -h, --help
-                        show this help message and exit
+logger = log21.get_logger(
+    "My File Logger", show_level=False, show_time=True, file="myapp.log", file_mode="a",
+    file_encoding="utf-8"
+)
 
+logger.info("Hello World!")
 ```
 
-#### Example 3
-
-```python
-def main(first_name: str, last_name: str, output: Path, verbose: bool = False):
-    """Write a greeting message.
-
-    :param first_name: The first name of the user to greet (optional)
-    :param last_name: The last name of the user to greet (optional)
-    :param output: The output file (stdout if none is provided)
-    :param verbose: If provided, will write the debug logs to stdout
-    """
-    ...
-
-
-if __name__ == "__main__":
-    argumentify(main)
-```
-
-The help looks like this:
-
-```help
-usage: test.py [-h] [--first-name FIRST_NAME] [--last-name LAST_NAME] [--output OUTPUT]
-               [--verbose]
-
-Write a greeting message.
-
-options:
-  -h, --help
-                        show this help message and exit
-  --first-name FIRST_NAME, -f FIRST_NAME
-                        The first name of the user to greet (optional)
-  --last-name LAST_NAME, -l LAST_NAME
-                        The last name of the user to greet (optional)
-  --output OUTPUT, -o OUTPUT
-                        The output file (stdout if none is provided)
-  --verbose, -v
-                        If provided, will write the debug logs to stdout
-
-```
-
-_Note that all the options are optional and default to None. `verbose` is False by
-default since a default value is provided for it in function definition._
-
 [Full CHANGELOG](https://github.com/MPCodeWriter21/log21/blob/master/CHANGELOG.md)
 
 Usage Examples

pyproject.toml

@@ -23,7 +23,7 @@ dependencies = [
     "webcolors",
     "docstring-parser"
 ]
-version = "3.1.0"
+version = "3.2.0"
 
 [build-system]
 requires = ["uv_build>=0.8.15,<0.9.0"]

src/log21/__init__.py

@@ -31,7 +31,7 @@
 # yapf: enable
 
 __author__ = 'CodeWriter21 (Mehrad Pooryoussof)'
-__version__ = '3.1.0'
+__version__ = '3.2.0'
 __github__ = 'https://GitHub.com/MPCodeWriter21/log21'
 __all__ = [
     'ColorizingStreamHandler', 'DecolorizingFileHandler', 'ColorizingFormatter',
@@ -60,7 +60,8 @@ def _prepare_formatter(
     colorize_time_and_level: bool = True,
     level_names: _Optional[_Mapping[int, str]] = None,
     level_colors: _Optional[_Mapping[int, tuple[str, ...]]] = None,
-    formatter_class: _Type[_logging.Formatter] = ColorizingFormatter
+    formatter_class: _Type[_logging.Formatter] = ColorizingFormatter,
+    prefix_carriage_return: bool = True,
 ) -> _logging.Formatter:
     # Prepares a formatting if the fmt was None
     if not fmt:
@@ -70,7 +71,8 @@ def _prepare_formatter(
             fmt = '[%(levelname)s] ' + fmt
         if show_time:
             fmt = '[%(asctime)s] ' + fmt
-        fmt = '\r' + fmt
+        if prefix_carriage_return:
+            fmt = '\r' + fmt
 
     if level_colors and not issubclass(formatter_class, ColorizingFormatter):
         warning(
@@ -116,7 +118,10 @@ def get_logger(
     override: bool = False,
     level_names: _Optional[_Mapping[int, str]] = None,
     level_colors: _Optional[_Mapping[int, tuple[str, ...]]] = None,
-    file: _Optional[_Union[_os.PathLike, str]] = None
+    # TODO: Rename file to file_path in one future update
+    file: _Optional[_Union[_os.PathLike, str]] = None,
+    file_mode: _Optional[str] = None,
+    file_encoding: _Optional[str] = None,
 ) -> Logger:
     """Returns a logging.Logger with colorizing support.
 
@@ -182,7 +187,9 @@ def get_logger(
     :param level_names: Mapping[int, str] = None: You can specify custom level names.
     :param level_colors: Mapping[int, Tuple[str, ...]] = None: You can specify custom
         level colors.
-    :param file: Union[os.PathLike, str] = None: The file to log to
+    :param file: Union[os.PathLike, str] = None: The file path to log to
+    :param file_mode: str = None: The mode to open file at (Defaults to 'a')
+    :param file_encoding: str = None: The file encoding
     :return: log21.Logger
     """
     if not isinstance(name, str):
@@ -209,7 +216,9 @@ def get_logger(
         _manager.addLogger(name, logger)
 
         if file:
-            file_handler = FileHandler(file)
+            file_handler = DecolorizingFileHandler(
+                file, mode=file_mode or 'a', encoding=file_encoding
+            )
             file_formatter = _prepare_formatter(
                 fmt,
                 style,
@@ -218,7 +227,8 @@ def get_logger(
                 show_time,
                 False,
                 level_names,
-                formatter_class=DecolorizingFormatter
+                formatter_class=DecolorizingFormatter,
+                prefix_carriage_return=False,
             )
             file_handler.setFormatter(file_formatter)
             logger.addHandler(file_handler)