# Lgger - A simple package for logging
A simple logging package, aimed to help with writing log files. This is the first
package, that I have ever created and is to be used in future projects of mine.
Any ideas for improvements and criticism is welcomed.
## Setup:
As a lazy person, the setup is one of the more unpleasant parts of each
project. This is why I have made this package to work with minimal setup required.
All that needs to be done is to install the package and import it.
Using pip:
```
pip install git+https://github.com/IllusionLife/lgger.git
```
When used, the package will set temporary enviromental variables, which
can be overwritten for customization. Those enviromental variables are
intended to create a configuration file by using the [Lgger template] file.
The enviromental variables are being set in the [env file] and here is the list
of what each variable is being used for:
| Env variable | Config variable | Intended use | Changable | Default value |
|------------------------|:------------------------|:-------------------------------------------------------:|:---------:|:----------------------------------:|
| LGGER_TMPL | | Stores to the templates folder | | ${package_dir}/lgger/templates |
| LGGER_CONF_TMPL | | Stores the name of Lgger config template file | | lgger.conf.template |
| LGGER_LOG_NAME | default_filename | Default log name if none is being provided in the code. | Y | log_%Y-%m-%d `date format` |
| LGGER_LOG_EXTN | default_file_extension | Default log file extention. | Y | .log |
| LGGER_LOG_DIR | default_log_folder | Default log directory. | Y | ./logging |
| LGGER_ENC | log_encoding | Default log encoding. | Y | utf-8 |
| LGGER_TIMESTAMP_FORMAT | datetimeformat | Log timestamp, used inside the log. | Y | %Y-%b-%d %H:%M:%S:%f `date format` |
| LGGER_CWD | | Stores the current working directory. | | ${getcwd()} |
If you need to change the default values, you can either:
* change the `${LGGER_LOG_DIR}/lgger.conf` file directly
(if the .conf file is created already).
* or change the env variables and create the configuration file
* After setting the variables, you can delete the old configuration file
and create a `Lgger()` object or use the `log(msg)` function, which
will create the conf file automatically.
* or call `resolve_template()`, which will do the same as above.
## How to use:
After installing and importing the package, you can use the `log(msg)` directly, which
will create a log file according to the configuration file mentioned above.
You can also create a custom log file by creating a `Lgger()` object. I will provide demonstrations
for both here:
### Using `log(msg, lvl=None, *args)`
Too lazy to create, store and handle a `Lgger()` object? Then don't.
By calling log("Your message"), the package will create a log folder
in your pre-configured directory (by default
the current working directory) in a separate folder.
```
import lgger
lgger.log("Hello World!")
```
You can also select a log level/severity and add any additional parameters to
be printed at the end of the log message. For more info on the log severity, please
check the [Log level / Severity] section.
```
import lgger
lgger.log("This is an error!", LogLvl.ERROR)
lgger.log("string", LogLvl.DEBUG, {more: "data"})
```
### Using the `create_log(filename, filepath)` function
If you want to create a `Lgger()` object, that writes in a different
folder or has a different filename, then this is what you should use.
This will create an object, assign it as the default logger for the
current session and run any `log(msg)` from this object. This is the recommended
way to create a `Lgger()` object.
The function takes a number of optional parameters:
* `filename: str` - Name of the log file *(By default = None, config)*
* `filepath: str` - Directory path *(By default = None, config)*
### Using a `Lgger(filename, filepath)` object
You can also create the object directly by calling the `Lgger()`. This will
create an object similarly to the `create_log()` function, but will not assign it as a global variable, making the
decorators ignore the current object and creating a new `Lgger()` object
using the default values.
## Log level / Severity:
Just as any other logging library out there, I have added a level/severity
system to the logs. You can add logs as INFO, debug using DEBUG or an error
with ERROR.
All those are saved in the `LogLvl` class and to use it, you just have to
provide the argument in the log function in the following format:
`LogLvl.{level}`.
The levels are as follows:
| Level | Value | Example | Usage |
|:---------:|:-----:|----------------|---------------------------------------------------------------------------------------------------------------------|
| DEBUG | 0 | LogLvl.DEBUG | Used to track information for developers. |
| INFO | 1 | LogLvl.INFO | Used to log general information. |
| WARNING | 2 | LogLvl.WARNING | A warning message, pointing to a discrepancy that should not affect the process, but could lead to possible issues. |
| ERROR | 3 | LogLvl.ERROR | This is used for errors or error messages, that doesn't lead to the application to stop. |
| FATAL | 4 | LogLvl.FATAL | This is an error log, which if used prior to an application failure due to an exception or something else. |
Please note that the provided usage is imperative. You can use them as you wish.
## Methods
`Lgger()` has a few methods, that can be used:
* `log(msg, level)` - used to log a message on a level/severity, provided by
the user
* `msg: str` - (***Required***) Log message to be added to log
* `lvl: LogLvl` - Log level/severity *(By default = None, config)*
* `log_debug(msg: str)`, `log_info(msg: str)`
, `log_warn(msg: str)`, `log_error(msg: str)`, `log_fatal(msg: str)`
\- used to log a message with a certain level/severity
* `msg: str` - (***Required***) Log message to be added to log
### Decorators
Now, this is most probably the most useful part of this whole package.
In order to keep track of what is being provided to the functions, how much time
or whatever needs to be checked/tracked in the future, there are decorators
that will do this. For the time being, I made them work with a global
`Lgger()` object, that is stored in the package. They are also stackable, meaning
you can use more than one decorator to the same function.
* `@time_performance` - This will time the approximate execution time for
the called function. The time is tracked in seconds, with a precision to
the microseconds.
* `@log_args` - This decorator will log the arguments, provided in the
called function. Both *args and **kwargs will be logged.
* `@log_return` - This decorator will log the return value of the
called function.
[Lgger template]: https://github.com/IllusionLife/lgger/tree/main/lgger/templates/lgger.conf.template
[env file]: https://github.com/IllusionLife/lgger/tree/main/lgger/env.py
[Log level / Severity]: https://github.com/IllusionLife/lgger/tree/main#log-level-/-severity
Raw data
{
"_id": null,
"home_page": "https://github.com/IllusionLife/lgger",
"name": "lgger",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.7",
"maintainer_email": null,
"keywords": "logging, simple, files",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/69/fd/26b3c2c8eb7201d909f4ee3810ee40d4eb323d4c8913629795b266dfa12c/lgger-0.1.5.tar.gz",
"platform": null,
"description": "# Lgger - A simple package for logging\r\n\r\n![Lgger background](./lgger/img/lgger_background.png \"Lgger background image\")\r\n\r\nA simple logging package, aimed to help with writing log files. This is the first \r\npackage, that I have ever created and is to be used in future projects of mine.\r\n\r\nAny ideas for improvements and criticism is welcomed.\r\n\r\n## Setup:\r\nAs a lazy person, the setup is one of the more unpleasant parts of each\r\nproject. This is why I have made this package to work with minimal setup required.\r\nAll that needs to be done is to install the package and import it.\r\n\r\nUsing pip:\r\n```\r\npip install git+https://github.com/IllusionLife/lgger.git\r\n```\r\n\r\nWhen used, the package will set temporary enviromental variables, which \r\ncan be overwritten for customization. Those enviromental variables are\r\nintended to create a configuration file by using the [Lgger template] file.\r\n\r\nThe enviromental variables are being set in the [env file] and here is the list\r\nof what each variable is being used for:\r\n\r\n| Env variable | Config variable | Intended use | Changable | Default value |\r\n|------------------------|:------------------------|:-------------------------------------------------------:|:---------:|:----------------------------------:|\r\n| LGGER_TMPL | | Stores to the templates folder | | ${package_dir}/lgger/templates |\r\n| LGGER_CONF_TMPL | | Stores the name of Lgger config template file | | lgger.conf.template |\r\n| LGGER_LOG_NAME | default_filename | Default log name if none is being provided in the code. | Y | log_%Y-%m-%d `date format` |\r\n| LGGER_LOG_EXTN | default_file_extension | Default log file extention. | Y | .log |\r\n| LGGER_LOG_DIR | default_log_folder | Default log directory. | Y | ./logging |\r\n| LGGER_ENC | log_encoding | Default log encoding. | Y | utf-8 |\r\n| LGGER_TIMESTAMP_FORMAT | datetimeformat | Log timestamp, used inside the log. | Y | %Y-%b-%d %H:%M:%S:%f `date format` |\r\n| LGGER_CWD | | Stores the current working directory. | | ${getcwd()} |\r\n\r\nIf you need to change the default values, you can either:\r\n* change the `${LGGER_LOG_DIR}/lgger.conf` file directly\r\n (if the .conf file is created already).\r\n* or change the env variables and create the configuration file\r\n * After setting the variables, you can delete the old configuration file\r\n and create a `Lgger()` object or use the `log(msg)` function, which\r\n will create the conf file automatically.\r\n * or call `resolve_template()`, which will do the same as above.\r\n\r\n## How to use:\r\nAfter installing and importing the package, you can use the `log(msg)` directly, which\r\nwill create a log file according to the configuration file mentioned above.\r\nYou can also create a custom log file by creating a `Lgger()` object. I will provide demonstrations\r\nfor both here:\r\n\r\n### Using `log(msg, lvl=None, *args)`\r\n\r\nToo lazy to create, store and handle a `Lgger()` object? Then don't.\r\nBy calling log(\"Your message\"), the package will create a log folder\r\nin your pre-configured directory (by default\r\nthe current working directory) in a separate folder.\r\n```\r\nimport lgger\r\n\r\nlgger.log(\"Hello World!\")\r\n```\r\n\r\nYou can also select a log level/severity and add any additional parameters to\r\nbe printed at the end of the log message. For more info on the log severity, please\r\ncheck the [Log level / Severity] section.\r\n```\r\nimport lgger\r\n\r\nlgger.log(\"This is an error!\", LogLvl.ERROR)\r\nlgger.log(\"string\", LogLvl.DEBUG, {more: \"data\"})\r\n```\r\n\r\n### Using the `create_log(filename, filepath)` function\r\n\r\nIf you want to create a `Lgger()` object, that writes in a different\r\nfolder or has a different filename, then this is what you should use.\r\n\r\nThis will create an object, assign it as the default logger for the\r\ncurrent session and run any `log(msg)` from this object. This is the recommended\r\nway to create a `Lgger()` object.\r\n\r\nThe function takes a number of optional parameters:\r\n * `filename: str` - Name of the log file *(By default = None, config)*\r\n * `filepath: str` - Directory path *(By default = None, config)*\r\n\r\n\r\n### Using a `Lgger(filename, filepath)` object\r\n\r\nYou can also create the object directly by calling the `Lgger()`. This will\r\ncreate an object similarly to the `create_log()` function, but will not assign it as a global variable, making the\r\ndecorators ignore the current object and creating a new `Lgger()` object\r\nusing the default values.\r\n\r\n## Log level / Severity:\r\nJust as any other logging library out there, I have added a level/severity\r\nsystem to the logs. You can add logs as INFO, debug using DEBUG or an error\r\nwith ERROR.\r\n\r\nAll those are saved in the `LogLvl` class and to use it, you just have to\r\nprovide the argument in the log function in the following format:\r\n`LogLvl.{level}`.\r\n\r\nThe levels are as follows:\r\n\r\n| Level | Value | Example | Usage |\r\n|:---------:|:-----:|----------------|---------------------------------------------------------------------------------------------------------------------|\r\n| DEBUG | 0 | LogLvl.DEBUG | Used to track information for developers. |\r\n| INFO | 1 | LogLvl.INFO | Used to log general information. |\r\n| WARNING | 2 | LogLvl.WARNING | A warning message, pointing to a discrepancy that should not affect the process, but could lead to possible issues. |\r\n| ERROR | 3 | LogLvl.ERROR | This is used for errors or error messages, that doesn't lead to the application to stop. |\r\n| FATAL | 4 | LogLvl.FATAL | This is an error log, which if used prior to an application failure due to an exception or something else. |\r\n\r\nPlease note that the provided usage is imperative. You can use them as you wish.\r\n\r\n## Methods\r\n`Lgger()` has a few methods, that can be used:\r\n * `log(msg, level)` - used to log a message on a level/severity, provided by\r\n the user\r\n * `msg: str` - (***Required***) Log message to be added to log\r\n * `lvl: LogLvl` - Log level/severity *(By default = None, config)*\r\n * `log_debug(msg: str)`, `log_info(msg: str)`\r\n , `log_warn(msg: str)`, `log_error(msg: str)`, `log_fatal(msg: str)`\r\n \\- used to log a message with a certain level/severity\r\n * `msg: str` - (***Required***) Log message to be added to log\r\n\r\n### Decorators\r\n\r\nNow, this is most probably the most useful part of this whole package.\r\nIn order to keep track of what is being provided to the functions, how much time\r\nor whatever needs to be checked/tracked in the future, there are decorators\r\nthat will do this. For the time being, I made them work with a global\r\n`Lgger()` object, that is stored in the package. They are also stackable, meaning\r\nyou can use more than one decorator to the same function.\r\n\r\n* `@time_performance` - This will time the approximate execution time for\r\nthe called function. The time is tracked in seconds, with a precision to\r\nthe microseconds.\r\n* `@log_args` - This decorator will log the arguments, provided in the\r\ncalled function. Both *args and **kwargs will be logged.\r\n* `@log_return` - This decorator will log the return value of the\r\ncalled function.\r\n\r\n\r\n[Lgger template]: https://github.com/IllusionLife/lgger/tree/main/lgger/templates/lgger.conf.template\r\n[env file]: https://github.com/IllusionLife/lgger/tree/main/lgger/env.py\r\n[Log level / Severity]: https://github.com/IllusionLife/lgger/tree/main#log-level-/-severity\r\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for writing logs to log files.",
"version": "0.1.5",
"project_urls": {
"Homepage": "https://github.com/IllusionLife/lgger"
},
"split_keywords": [
"logging",
" simple",
" files"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a0f6e710847be380ab5b75a40ab22943e7a1c3520e1bc0dce68ef88ea9ae8695",
"md5": "dfa0a6eb6681cef873cb5b8e6407b0b9",
"sha256": "0fccb6ca9995f4ac1cdfae524556737905e80337a27fb8a7b38aab1068d66f6f"
},
"downloads": -1,
"filename": "lgger-0.1.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "dfa0a6eb6681cef873cb5b8e6407b0b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.7",
"size": 4867,
"upload_time": "2024-07-27T13:31:17",
"upload_time_iso_8601": "2024-07-27T13:31:17.505180Z",
"url": "https://files.pythonhosted.org/packages/a0/f6/e710847be380ab5b75a40ab22943e7a1c3520e1bc0dce68ef88ea9ae8695/lgger-0.1.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "69fd26b3c2c8eb7201d909f4ee3810ee40d4eb323d4c8913629795b266dfa12c",
"md5": "4373c68284f50cd90685f0b071af8cc7",
"sha256": "60f5228094f28f8f975791116dc0c855daff8317dd71fe5790136605d6613279"
},
"downloads": -1,
"filename": "lgger-0.1.5.tar.gz",
"has_sig": false,
"md5_digest": "4373c68284f50cd90685f0b071af8cc7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.7",
"size": 11871,
"upload_time": "2024-07-27T13:31:18",
"upload_time_iso_8601": "2024-07-27T13:31:18.966075Z",
"url": "https://files.pythonhosted.org/packages/69/fd/26b3c2c8eb7201d909f4ee3810ee40d4eb323d4c8913629795b266dfa12c/lgger-0.1.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-27 13:31:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "IllusionLife",
"github_project": "lgger",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "lgger"
}
JSON
