| Name | felling JSON |
| Version |
0.1.6
JSON |
| download |
| home_page | None |
| Summary | A simple package to easily create consistent logs |
| upload_time | 2024-09-19 08:57:52 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT |
| keywords |
log
logging
logs
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# felling :evergreen_tree:
> **felling** *verb*: to cut down
> Synonyms: Logging
[](https://pypi.org/project/felling/)[](https://anaconda.org/conda-forge/felling)[](https://github.com/this-josh/felling/blob/main/LICENSE)[](https://github.com/this-josh/felling/actions/workflows/python-package.yml)[](https://github.com/this-josh/felling/actions/workflows/codeql-analysis.yml)[](https://codecov.io/gh/this-josh/felling)[](https://github.com/this-josh/felling/issues)[](https://github.com/psf/black)[](https://discord.com/channels/816786912383729694)
Felling easily improves repeatability and debugging of code by always initially logging some runtime metadata and ensuring logs are always written to a file in an easy to read format.
## Example usage
```python
import felling
felling.configure()
# Done!
```
## Issues
If you find any bugs/have any request, please feel free to add a GitHub ticket. It’s only through your ideas that felling can reach its full potential.
## Usage
1. Install the package with `pip install felling`
2. The package only needs to be imported once per runtime, in ```__main__``` run the following code
```python
import felling
felling.configure()
```
Logs will saved in `./logs/{time_ran}_{file_name}.log` where file_name will be the name of the file ```__main__``` unless a file_name is passed into ```felling.configure```
At this point your logs are now configured for this run time and you can log as normal.
## Logging in Python :snake:
This is a basic explanation of logging in python, none of this is specific to felling.
First, you must import logging and name your logger, this is usually done by:
```python
import logging
logger = logging.getLogger(__name__)
```
Now you can write logs, there are a few different levels which you can use. They are, in ascending order of severity:
```python
logger.debug('lowest level')
logger.info(message)
logger.warning(message)
logger.error(message)
logger.critical(message)
```
If you wish for execution information to be put into the log it can be done by:
```python
logger.error('Everything has failed', exc_info = True)
```
Try and excepts can also be handled properly, for example:
```python
try:
float('this cannot be a float')
except ValueError as e:
logger.exception('your message here')
raise
except Exception as e:
logger.exception(e.args)
raise
```
*Line 3* `logger.exception('your message here')` will log your message, the error message and its full traceback.
*Line 6* will then catch all other exceptions and log them, *Note* catching specific error is generally preferred.
### Testing
When running tests logging can be easily turned off if desired. In the file `tests/__init__.py` write:
```python
logging.disable()
```
By default this disables all logs of level critical and lower, felling is capable of reading this status and won't generate any empty log files.
# Now go and write some beautiful logs :sunrise_over_mountains:
## felling additional features
`felling.configure()` has a lot more features than outlined in the basic summary above, they can be seen below
### Initial logs
For repeatability it can be useful to have some metadata about each run time. When configuring felling it will log:
1. The users username
2. The most recent git commit hash for `__main__`'s repo, its fine if it isn’t a git repo.
3. The git remote status from `git remote show origin`
### `log_path`
```python
import felling
felling.configure(log_path = './logs')
```
When configuring a `pathlib.Path` or a `str` path can be provide as the directory to save logs to, if none is provided `'./logs'` will be used
### `log_file_name`
```python
import felling
felling.configure(log_file_name = 'logs_for_foo')
```
When configuring, a custom log file name can be passed
### `file_log_level` and `std_log_level`
```python
import felling
felling.configure(file_log_level ='ERROR', std_out_log_level = 40)
```
Log levels can be provided either as a string (`“ERROR”`) or integer (`40`) as defined [here](https://docs.python.org/3/library/logging.html#logging-levels). `file_log_level` defines the minimum log level which will be written to the log file, while `std_out_log_level` defines the minimum log level which will be written to the std output (your terminal)
### `error_only_modules`
```python
import felling
import pandas
felling.configure(error_only_modules = pandas)
```
If some packages are writing lots of logs you’re not interested in a specific error_only handler can be set up. In the above example only pandas error logs will be used. Some packages have control for their verbosity of logging, however, setting it up with felling works for all packages and is comprehensive.
### `modules_to_debug`
```python
import felling
import pandas
felling.configure(modules_to_debug = pandas)
```
Similar to [error_only_modules](## `error_only_modules`) you can specify modules which you would like debug logs to be interpreted
### `package_versions_to_log`
```python
import felling
import pandas
felling.configure(package_versions_to_log = pandas)
```
For repeatability it can be helpful to log package versions, packages passed to `package_versions_to_log` will have their version numbers logged while running initial logs
### Comparing log files
Have you refactored some code? Do you not have 100% test coverage? Of course not “it’s only experimental code” :wink: We all know what you have done. We can compare before and after log files to add some extra validity to your code change or to easily find where things change
*Note: This is **absolutely** not a replacement to testing, and will only provide any benefit if you have comprehensive debug logs*
#### How to run
The following script will run the comparison.
```shell
python -m felling {str_to_first_log_file} {str_to_second_log_file} [-v]
```
If all is identical it’ll let you know, otherwise it will print the first 100 differences. If you’d like more than 100 differences pass `-v`
## Isn’t felling a bit simple?
> Simple is better than complex.
*`python -c import this ` - Tim Peters*
Wherever possible `felling` will be kept as simple as possible, for now I am proud it is requirements free. A lot of the difficulty in setting this up has been gathering an understanding of logging in Python and the initial setup of logging.json.
## Other advantages:
* If you have too many print statement you'll lose them in your stdout but still have them in a log file
Raw data
{
"_id": null,
"home_page": null,
"name": "felling",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "log, logging, logs",
"author": null,
"author_email": "Josh Kirk <felling@joshkirk.co.uk>",
"download_url": "https://files.pythonhosted.org/packages/5a/fe/c9398f27d2bbc4c3fafede7d61a50b2c312f6ccfd1146068f3c22c98e33b/felling-0.1.6.tar.gz",
"platform": null,
"description": "# felling :evergreen_tree:\n\n> **felling** *verb*: to cut down \n> \tSynonyms: Logging\n\n[](https://pypi.org/project/felling/)[](https://anaconda.org/conda-forge/felling)[](https://github.com/this-josh/felling/blob/main/LICENSE)[](https://github.com/this-josh/felling/actions/workflows/python-package.yml)[](https://github.com/this-josh/felling/actions/workflows/codeql-analysis.yml)[](https://codecov.io/gh/this-josh/felling)[](https://github.com/this-josh/felling/issues)[](https://github.com/psf/black)[](https://discord.com/channels/816786912383729694)\n\t\n\n\nFelling easily improves repeatability and debugging of code by always initially logging some runtime metadata and ensuring logs are always written to a file in an easy to read format.\n\n## Example usage\n\n```python\nimport felling\nfelling.configure()\n# Done!\n```\n\n## Issues\n\nIf you find any bugs/have any request, please feel free to add a GitHub ticket. It\u2019s only through your ideas that felling can reach its full potential.\n\n## Usage\n\n1. Install the package with `pip install felling`\n\n2. The package only needs to be imported once per runtime, in ```__main__``` run the following code \n ```python\n import felling\n felling.configure()\n ```\n Logs will saved in `./logs/{time_ran}_{file_name}.log` where file_name will be the name of the file ```__main__``` unless a file_name is passed into ```felling.configure```\n At this point your logs are now configured for this run time and you can log as normal.\n\n\n## Logging in Python :snake:\n\nThis is a basic explanation of logging in python, none of this is specific to felling.\n\nFirst, you must import logging and name your logger, this is usually done by: \n\n\n```python\nimport logging\nlogger = logging.getLogger(__name__)\n```\n\nNow you can write logs, there are a few different levels which you can use. They are, in ascending order of severity:\n ```python\n logger.debug('lowest level')\n logger.info(message)\n logger.warning(message)\n logger.error(message)\n logger.critical(message)\n ```\n If you wish for execution information to be put into the log it can be done by:\n ```python\n logger.error('Everything has failed', exc_info = True)\n ```\n\nTry and excepts can also be handled properly, for example:\n```python\ntry:\n float('this cannot be a float') \nexcept ValueError as e:\n logger.exception('your message here')\n raise\nexcept Exception as e:\n logger.exception(e.args)\n raise\n```\n*Line 3* `logger.exception('your message here')` will log your message, the error message and its full traceback. \n\n*Line 6* will then catch all other exceptions and log them, *Note* catching specific error is generally preferred.\n\n### Testing\nWhen running tests logging can be easily turned off if desired. In the file `tests/__init__.py` write:\n```python\nlogging.disable()\n```\nBy default this disables all logs of level critical and lower, felling is capable of reading this status and won't generate any empty log files. \n\n# Now go and write some beautiful logs :sunrise_over_mountains:\n\n## felling additional features\n\n`felling.configure()` has a lot more features than outlined in the basic summary above, they can be seen below\n\n### Initial logs\n\nFor repeatability it can be useful to have some metadata about each run time. When configuring felling it will log:\n\n1. The users username\n2. The most recent git commit hash for `__main__`'s repo, its fine if it isn\u2019t a git repo.\n3. The git remote status from `git remote show origin`\n\n### `log_path`\n\n```python\nimport felling\nfelling.configure(log_path = './logs')\n```\n\nWhen configuring a `pathlib.Path` or a `str` path can be provide as the directory to save logs to, if none is provided `'./logs'` will be used\n\n### `log_file_name`\n\n```python\nimport felling\nfelling.configure(log_file_name = 'logs_for_foo')\n```\n\nWhen configuring, a custom log file name can be passed\n\n### `file_log_level` and `std_log_level`\n\n```python\nimport felling\nfelling.configure(file_log_level ='ERROR', std_out_log_level = 40)\n```\n\nLog levels can be provided either as a string (`\u201cERROR\u201d`) or integer (`40`) as defined [here](https://docs.python.org/3/library/logging.html#logging-levels). `file_log_level` defines the minimum log level which will be written to the log file, while `std_out_log_level` defines the minimum log level which will be written to the std output (your terminal)\n\n### `error_only_modules`\n\n```python\nimport felling\nimport pandas\nfelling.configure(error_only_modules = pandas)\n```\n\nIf some packages are writing lots of logs you\u2019re not interested in a specific error_only handler can be set up. In the above example only pandas error logs will be used. Some packages have control for their verbosity of logging, however, setting it up with felling works for all packages and is comprehensive. \n\n### `modules_to_debug`\n\n```python\nimport felling\nimport pandas\nfelling.configure(modules_to_debug = pandas)\n```\n\nSimilar to [error_only_modules](## `error_only_modules`) you can specify modules which you would like debug logs to be interpreted\n\n### `package_versions_to_log`\n\n\n```python\nimport felling\nimport pandas\nfelling.configure(package_versions_to_log = pandas)\n```\n\nFor repeatability it can be helpful to log package versions, packages passed to `package_versions_to_log` will have their version numbers logged while running initial logs\n\n### Comparing log files\n\nHave you refactored some code? Do you not have 100% test coverage? Of course not \u201cit\u2019s only experimental code\u201d :wink: We all know what you have done. We can compare before and after log files to add some extra validity to your code change or to easily find where things change\n\n*Note: This is **absolutely** not a replacement to testing, and will only provide any benefit if you have comprehensive debug logs* \n\n#### How to run\n\nThe following script will run the comparison.\n\n```shell\npython -m felling {str_to_first_log_file} {str_to_second_log_file} [-v]\n```\n\nIf all is identical it\u2019ll let you know, otherwise it will print the first 100 differences. If you\u2019d like more than 100 differences pass `-v`\n\n## Isn\u2019t felling a bit simple?\n\n> Simple is better than complex.\n\n\u200b\t*`python -c import this ` - Tim Peters*\n\nWherever possible `felling` will be kept as simple as possible, for now I am proud it is requirements free. A lot of the difficulty in setting this up has been gathering an understanding of logging in Python and the initial setup of logging.json. \n\n\n## Other advantages:\n* If you have too many print statement you'll lose them in your stdout but still have them in a log file\n ",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple package to easily create consistent logs",
"version": "0.1.6",
"project_urls": {
"Source": "https://github.com/this-josh/felling",
"Tracker": "https://github.com/this-josh/felling/issues"
},
"split_keywords": [
"log",
" logging",
" logs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "192179d4ed9d9884e3a6a1fb34c86bf647c7755b9b23963fff46e3bbcd27ce6a",
"md5": "c8905370287676a72ed4b4690ae8a597",
"sha256": "6c2bcf23f3d2ae817ee412b6869a1a9b1a57978540a151b6ce3670536e80a343"
},
"downloads": -1,
"filename": "felling-0.1.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8905370287676a72ed4b4690ae8a597",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 11986,
"upload_time": "2024-09-19T08:57:51",
"upload_time_iso_8601": "2024-09-19T08:57:51.410651Z",
"url": "https://files.pythonhosted.org/packages/19/21/79d4ed9d9884e3a6a1fb34c86bf647c7755b9b23963fff46e3bbcd27ce6a/felling-0.1.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5afec9398f27d2bbc4c3fafede7d61a50b2c312f6ccfd1146068f3c22c98e33b",
"md5": "b3be5200cd6f2c654db30018aea64e96",
"sha256": "6820561c2020d0ca9799366d606e2db028ded44e3a1b150958c9bb756da438c0"
},
"downloads": -1,
"filename": "felling-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "b3be5200cd6f2c654db30018aea64e96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 21362,
"upload_time": "2024-09-19T08:57:52",
"upload_time_iso_8601": "2024-09-19T08:57:52.462633Z",
"url": "https://files.pythonhosted.org/packages/5a/fe/c9398f27d2bbc4c3fafede7d61a50b2c312f6ccfd1146068f3c22c98e33b/felling-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-19 08:57:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "this-josh",
"github_project": "felling",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "felling"
}
