Feature/Log file

CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+-   `LogFile` - Offers a similar API to the Python builtin loggers for logging to a custom file.
+-   `setup_file_logging()` - Setup file logging for the application.
+-   `handle_uncaught_exceptions()` - Installs a collector for logging uncaught exceptions.
+
+### Changed
+
+-   The documentation generator clears the `./docs` folder before generating the documentation.
+
 ## [0.2.0] - 2023-09-11
 
 ### Added

docs/README.md

@@ -12,13 +12,17 @@
 - [`toolbox.files.json_file`](./toolbox.files.json_file.md#module-toolboxfilesjson_file): A simple API for reading and writing JSON files.
 - [`toolbox.files.path`](./toolbox.files.path.md#module-toolboxfilespath): A collection of utilities around file paths.
 - [`toolbox.files.pickle_file`](./toolbox.files.pickle_file.md#module-toolboxfilespickle_file): A simple API for reading and writing pickle files.
+- [`toolbox.logging`](./toolbox.logging.md#module-toolboxlogging): The `logging` package provides several utilities for logging purpose.
+- [`toolbox.logging.config`](./toolbox.logging.config.md#module-toolboxloggingconfig): A collection of utilities for logging purpose.
+- [`toolbox.logging.log_file`](./toolbox.logging.log_file.md#module-toolboxlogginglog_file): A custom logger that writes directly to a file.
 
 ## Classes
 
 - [`csv_file.CSVFile`](./toolbox.files.csv_file.md#class-csvfile): Offers a simple API for reading and writing CSV files.
 - [`file_manager.FileManager`](./toolbox.files.file_manager.md#class-filemanager): Offers a simple API for reading and writing files.
 - [`json_file.JSONFile`](./toolbox.files.json_file.md#class-jsonfile): Offers a simple API for reading and writing JSON files.
 - [`pickle_file.PickleFile`](./toolbox.files.pickle_file.md#class-picklefile): Offers a simple API for reading and writing pickle files.
+- [`log_file.LogFile`](./toolbox.logging.log_file.md#class-logfile): Offers a similar API to the Python builtin loggers for logging to a custom file.
 
 ## Functions
 
@@ -38,6 +42,8 @@
 - [`path.get_module_path`](./toolbox.files.path.md#function-get_module_path): Gets the path to the given module.
 - [`pickle_file.read_pickle_file`](./toolbox.files.pickle_file.md#function-read_pickle_file): Loads a list of objects from a file.
 - [`pickle_file.write_pickle_file`](./toolbox.files.pickle_file.md#function-write_pickle_file): Writes a list of objects to a file.
+- [`config.handle_uncaught_exceptions`](./toolbox.logging.config.md#function-handle_uncaught_exceptions): Installs a collector for logging uncaught exceptions.
+- [`config.setup_file_logging`](./toolbox.logging.config.md#function-setup_file_logging): Setup the application log to a file logger.
 
 
 ---

docs/toolbox.logging.config.md

@@ -0,0 +1,103 @@
+<!-- markdownlint-disable -->
+
+<a href="../toolbox/logging/config.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+# <kbd>module</kbd> `toolbox.logging.config`
+A collection of utilities for logging purpose. 
+
+
+
+**Examples:**
+ ```python
+from toolbox.logging import setup_file_logging, handle_uncaught_exceptions
+
+setup_file_logging('path/to/file.log')
+handle_uncaught_exceptions()
+
+def main() -> None:
+     ...
+
+if __name__ == "__main__":
+     main()
+``` 
+
+**Global Variables**
+---------------
+- **LOG_FILE**
+- **LOG_FORMAT**
+- **LOG_ENCODING**
+
+---
+
+<a href="../toolbox/logging/config.py#L30"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `setup_file_logging`
+
+```python
+setup_file_logging(
+    filename: str = 'app.log',
+    level: int = 20,
+    encoding: str = 'utf-8',
+    log_format: str = '%(asctime)s %(levelname)s:%(name)s:%(message)s',
+    **kwargs
+) → None
+```
+
+Setup the application log to a file logger. 
+
+By default, a file will be created in the current working directory, named 'app.log'. 
+
+
+
+**Args:**
+
+ - <b>`filename`</b> (str, optional):  The filename of the log file. Defaults to LOG_FILE. 
+ - <b>`level`</b> (int, optional):  The log level to accept. Defaults to logging.INFO. 
+ - <b>`encoding`</b> (str, optional):  The file encoding. Defaults to LOG_ENCODING. 
+ - <b>`log_format`</b> (str, optional):  The format for each log event. Defaults to LOG_FORMAT. 
+
+
+
+**Examples:**
+ ```python
+from toolbox.logging import setup_file_logging
+
+setup_file_logging('path/to/file.log')
+``` 
+
+
+---
+
+<a href="../toolbox/logging/config.py#L63"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `handle_uncaught_exceptions`
+
+```python
+handle_uncaught_exceptions() → None
+```
+
+Installs a collector for logging uncaught exceptions. 
+
+When an exception is not handled in the code, it will be logged with the message: 'Uncaught exception: <exception message>'. 
+
+
+
+**Examples:**
+ ```python
+from toolbox.logging import handle_uncaught_exceptions
+
+handle_uncaught_exceptions()
+
+def main() -> None:
+     ...
+
+if __name__ == "__main__":
+     main()
+``` 
+
+
+
+
+---
+
+_This file was automatically generated via [lazydocs](https://github.com/ml-tooling/lazydocs)._