| Name | pylogfunctionusage JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | LogFunctionUsage in pylogfunctionusage is a Python decorator designed to enhance the logging capabilities of your functions by wrapping them in a try: block. It logs function usage, including calls, exceptions, and results, to an SQLite table |
| upload_time | 2024-08-26 20:30:43 |
| maintainer | Ambroise Dobosz |
| docs_url | None |
| author | Ambroise Dobosz |
| requires_python | >=3.6 |
| license | Copyright (c) 2024 Ambroise Dobosz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
logfunctionusage
logging
monitoring
pylogfunctionusage
sql
sqlite
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# `pylogfunctionusage`
## Project Description
**LogFunctionUsage** is a Python decorator designed to enhance the logging capabilities of your programs functions by wrapping functions in a `try:` block. It logs function usage, including calls, exceptions, and results, to an SQLite table, making it easier to monitor and debug your code.
## Purpose
This module was originally written to monitor complex calculations during a master's thesis project. The need for precise and efficient logging arose, leading to the development of a solution that integrates seamlessly with SQLite databases. This enables comprehensive monitoring and debugging without significant performance overhead.
## Features
- **Database Configuration**: Customize the SQLite database name used for logging.
- **Table Name Customization**: Specify the table name for storing logs.
- **Error Handling**: Choose whether the program continues or stops on an error.
- **Log Table Refresh**: Option to clear the log table with each program run.
- **Error Printing**: Configure whether errors are printed to the console.
- **Result Logging**: Optionally log the results of functions.
- **Robustness**: Choose between committing logs immediately or at the end of the program.
- **Live Monitoring**: Enable live monitoring of program execution.
- **Write-Ahead Logging (WAL)**: Significant speedup for massive function calls, but use with caution.
## Performance
**LogFunctionUsage** is optimized for speed by using pure SQL expressions, which contrasts with tools based on ORM systems like SQLAlchemy. This approach ensures faster logging. On laptop with simple functions:
- Adds approximately 0.7ms (0.0007s) to function run time in WAL mode.
- Adds approximately 3ms (0.003s) to function run time in normal mode.
### Limitations
As this module relies on sqlite db it doesn't support async code.
## Difference Over the `logging` Module
While the Python `logging` module is versatile and powerful, **LogFunctionUsage** offers specific advantages for function-level logging:
- **Granular Control**: Logs detailed function execution data, including arguments, keyword arguments, results, and exceptions.
- **SQL Storage**: Logs are stored in an SQLite table, making them easily accessible for querying and integration with other tools.
- **Performance**: Faster logging performance due to direct SQL expressions.
## Integration with Visualization Tools
The sql table with logs can be plugged into any visualization or reporting tool, such as:
- **Dash**
- **PowerBI**
- **Tableau**
This flexibility allows for advanced analysis, monitoring and visualization of function execution data.
## Simplicity
Using this module is incredibly simple. All you need is to decorate your functions, and the logging is taken care of. No complex setup or extensive configuration is required.
## Installation
you can clone the repository and install it from source:
```bash
pip install pylogfunctionusage
```
```bash
git clone https://github.com/Ambroise-D/pylogfunctionusage.git
cd pylogfunctionusage
python setup.py install
```
or copy file pylogfunctionusage.py to your project and simply use it!
## Dependencies
**LogFunctionUsage** does not require any additional packages beyond the standard Python library. It uses built-in modules such as sqlite3, ensuring that you can use it without needing to install external dependencies.
## Usage
### Basic Usage
Create an instance of LogFunctionUsage and use it across your code:
```python
from pylogfunctionusage import LogFunctionUsage
log = LogFunctionUsage()
OR
log = LogFunctionUsage(db_name='your_database_name.db',
table_name='function_logs',
if_raise=False,
print_error=True,
refresh_log_table=True,
log_results=False,
robust=True,
live_monitor=False,
wal=False)
@log
def func_to_log(x, y="y"):
return "some results"
```
### Error Handling Example
```python
@LogFunctionUsage(if_raise=True)
def function_to_log():
print(1/0) # This will throw an error due to 'if_raise = True'
```
## SQL Logging
Logs are saved to an SQLite table with the following columns:
- **function_name:** Name of the function.
- **type:** Type of call (Start, End, or Except).
- **code_line:** Line of code that called the function.
- **timestamp:** Time of function call.
- **args:** Argument names passed to the function.
- **kwargs:** Keyword arguments passed to the function.
- **result:** Results and exceptions of the function.
#### Example log looks like:
| id | function_name | type | code_line | timestamp | args | kwargs | result |
|:---:|:-----------------------:|:-----:|:---------:|:-------------------:|:---------------:|:------------:|:----------------:|
| 1 | func_to_log | START | 42 | 2024-04-20 16:20:00 | "('some_str',)" | "{'y': 'y'}" | None |
| 2 | func_to_log | END | 42 | 2024-04-20 16:20:42 | "('some_str',)" | "{'y': 'y'}" | 'some results' |
## Bugs report
Please submit an issue on GitHub.
## Contributing
We welcome contributions to the LogFunctionUsage project! If you have ideas, suggestions, or improvements, or if you want to participate in the development of this module, please feel free to open an issue or submit a pull request on our GitHub repository. Your contributions help us enhance the functionality and usability of the module, and we appreciate your input.
## License
This project is licensed under the **MIT** License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "pylogfunctionusage",
"maintainer": "Ambroise Dobosz",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "LogFunctionUsage, logging, monitoring, pylogfunctionusage, sql, sqlite",
"author": "Ambroise Dobosz",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/6d/93/ce20cef654226ceb752c9e166ff08c757fd42579ea52922a90cf768b2560/pylogfunctionusage-0.1.1.tar.gz",
"platform": null,
"description": "# `pylogfunctionusage`\n\n## Project Description\n\n**LogFunctionUsage** is a Python decorator designed to enhance the logging capabilities of your programs functions by wrapping functions in a `try:` block. It logs function usage, including calls, exceptions, and results, to an SQLite table, making it easier to monitor and debug your code.\n\n## Purpose\n\nThis module was originally written to monitor complex calculations during a master's thesis project. The need for precise and efficient logging arose, leading to the development of a solution that integrates seamlessly with SQLite databases. This enables comprehensive monitoring and debugging without significant performance overhead.\n\n## Features\n\n- **Database Configuration**: Customize the SQLite database name used for logging.\n- **Table Name Customization**: Specify the table name for storing logs.\n- **Error Handling**: Choose whether the program continues or stops on an error.\n- **Log Table Refresh**: Option to clear the log table with each program run.\n- **Error Printing**: Configure whether errors are printed to the console.\n- **Result Logging**: Optionally log the results of functions.\n- **Robustness**: Choose between committing logs immediately or at the end of the program.\n- **Live Monitoring**: Enable live monitoring of program execution.\n- **Write-Ahead Logging (WAL)**: Significant speedup for massive function calls, but use with caution.\n\n## Performance\n\n**LogFunctionUsage** is optimized for speed by using pure SQL expressions, which contrasts with tools based on ORM systems like SQLAlchemy. This approach ensures faster logging. On laptop with simple functions:\n\n- Adds approximately 0.7ms (0.0007s) to function run time in WAL mode.\n- Adds approximately 3ms (0.003s) to function run time in normal mode.\n\n### Limitations \nAs this module relies on sqlite db it doesn't support async code.\n\n## Difference Over the `logging` Module\n\nWhile the Python `logging` module is versatile and powerful, **LogFunctionUsage** offers specific advantages for function-level logging:\n\n- **Granular Control**: Logs detailed function execution data, including arguments, keyword arguments, results, and exceptions.\n- **SQL Storage**: Logs are stored in an SQLite table, making them easily accessible for querying and integration with other tools.\n- **Performance**: Faster logging performance due to direct SQL expressions.\n\n## Integration with Visualization Tools\n\nThe sql table with logs can be plugged into any visualization or reporting tool, such as:\n\n- **Dash**\n- **PowerBI**\n- **Tableau**\n\n\nThis flexibility allows for advanced analysis, monitoring and visualization of function execution data.\n\n## Simplicity\n\nUsing this module is incredibly simple. All you need is to decorate your functions, and the logging is taken care of. No complex setup or extensive configuration is required.\n\n\n## Installation\n\nyou can clone the repository and install it from source:\n\n```bash\npip install pylogfunctionusage\n```\n```bash\ngit clone https://github.com/Ambroise-D/pylogfunctionusage.git\ncd pylogfunctionusage\npython setup.py install\n```\n\nor copy file pylogfunctionusage.py to your project and simply use it!\n\n## Dependencies\n**LogFunctionUsage** does not require any additional packages beyond the standard Python library. It uses built-in modules such as sqlite3, ensuring that you can use it without needing to install external dependencies.\n\n## Usage\n### Basic Usage\nCreate an instance of LogFunctionUsage and use it across your code:\n\n```python\nfrom pylogfunctionusage import LogFunctionUsage\n\nlog = LogFunctionUsage()\n\nOR\n\nlog = LogFunctionUsage(db_name='your_database_name.db',\n table_name='function_logs',\n if_raise=False,\n print_error=True,\n refresh_log_table=True,\n log_results=False,\n robust=True,\n live_monitor=False,\n wal=False)\n\n\n@log\ndef func_to_log(x, y=\"y\"):\n return \"some results\"\n```\n### Error Handling Example\n```python\n@LogFunctionUsage(if_raise=True)\ndef function_to_log():\n print(1/0) # This will throw an error due to 'if_raise = True'\n```\n\n## SQL Logging\nLogs are saved to an SQLite table with the following columns: \n- **function_name:** Name of the function.\n- **type:** Type of call (Start, End, or Except).\n- **code_line:** Line of code that called the function.\n- **timestamp:** Time of function call.\n- **args:** Argument names passed to the function.\n- **kwargs:** Keyword arguments passed to the function.\n- **result:** Results and exceptions of the function.\n\n#### Example log looks like:\n\n| id | function_name | type | code_line | timestamp | args | kwargs | result |\n|:---:|:-----------------------:|:-----:|:---------:|:-------------------:|:---------------:|:------------:|:----------------:|\n| 1 | func_to_log | START | 42 | 2024-04-20 16:20:00 | \"('some_str',)\" | \"{'y': 'y'}\" | None | \n| 2 | func_to_log | END | 42 | 2024-04-20 16:20:42 | \"('some_str',)\" | \"{'y': 'y'}\" | 'some results' | \n\n## Bugs report\nPlease submit an issue on GitHub.\n\n## Contributing\nWe welcome contributions to the LogFunctionUsage project! If you have ideas, suggestions, or improvements, or if you want to participate in the development of this module, please feel free to open an issue or submit a pull request on our GitHub repository. Your contributions help us enhance the functionality and usability of the module, and we appreciate your input. \n\n## License\nThis project is licensed under the **MIT** License - see the LICENSE file for details.",
"bugtrack_url": null,
"license": "Copyright (c) 2024 Ambroise Dobosz Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.",
"summary": "LogFunctionUsage in pylogfunctionusage is a Python decorator designed to enhance the logging capabilities of your functions by wrapping them in a try: block. It logs function usage, including calls, exceptions, and results, to an SQLite table",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/Ambroise-D/pylogfunctionusage",
"Issues": "https://github.com/Ambroise-D/pylogfunctionusage/issues"
},
"split_keywords": [
"logfunctionusage",
" logging",
" monitoring",
" pylogfunctionusage",
" sql",
" sqlite"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "675551b5674d0dcb0481a9036311ccf84c507da91e4c20e3f542b7b57aaca65a",
"md5": "e3c534465df7d981e448f1fe86d3b6d4",
"sha256": "ad6e635540a36773d98d26cbd27a63f678d03c489ba80a94e44f9e8547d3d8e0"
},
"downloads": -1,
"filename": "pylogfunctionusage-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3c534465df7d981e448f1fe86d3b6d4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 7972,
"upload_time": "2024-08-26T20:30:42",
"upload_time_iso_8601": "2024-08-26T20:30:42.401074Z",
"url": "https://files.pythonhosted.org/packages/67/55/51b5674d0dcb0481a9036311ccf84c507da91e4c20e3f542b7b57aaca65a/pylogfunctionusage-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6d93ce20cef654226ceb752c9e166ff08c757fd42579ea52922a90cf768b2560",
"md5": "e27dcce02f879c6a35786dff694346fc",
"sha256": "4238a76812fcc8fd86e5ca9d42a05f4c2dfa7460e5a8f4ab58662fa256a0d1f8"
},
"downloads": -1,
"filename": "pylogfunctionusage-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "e27dcce02f879c6a35786dff694346fc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 8005,
"upload_time": "2024-08-26T20:30:43",
"upload_time_iso_8601": "2024-08-26T20:30:43.603136Z",
"url": "https://files.pythonhosted.org/packages/6d/93/ce20cef654226ceb752c9e166ff08c757fd42579ea52922a90cf768b2560/pylogfunctionusage-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-26 20:30:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Ambroise-D",
"github_project": "pylogfunctionusage",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pylogfunctionusage"
}
