# Wrap Logger
A library to wrap around objects and modules in Python and log property
accesses and calls.
`pip install wrap-logger`
## Rationale
In some cases when programming, errors can break things to the point where
you have no idea where things went wrong, for example, crashing the runtime
environment before a backtrace can be printed. In these cases, it can be
extremely useful to log changes to data that are potentially related to the
issue, but doing so can be tedious and slow. I needed a simple solution to
easily inject logging into objects, and so I created `wrap-logger`.
## Usage
Using `wrap-logger` is simple. Simply call the `wrap` function, which will
return a wrapped version.
### With a module
```py
import foo
from wrap_logger import wrap
# Now all function calls and global reads/writes will be logged
foo = wrap(foo)
# Getting a property causes things to be logged
foo.bar
# [WRAP LOG] > Get foo.bar
# [WRAP LOG] < Get foo.bar: gave 42
# Same for setting properties
obj.bar = 43
# [WRAP LOG] > Set foo.bar: 42 -> 43
# [WRAP LOG] < Set foo.bar
# And calling functions
obj.echo('hello world')
# [WRAP LOG] > Call foo.echo('hello world')
# [WRAP LOG] < Call foo.echo('hello world'): returned 'hello world'
```
### With a class
```py
from wrap_logger import wrap
class Simple:
def __init__(self) -> None:
self.value = 42
# Wrap an instance of the object
obj = wrap(Simple())
```
### Without Pip
`wrap-logger` requires no dependencies, and can even function with some parts
of the standard library missing. Simply head over to the releases tab where the
`wrap-logger.zip` file is attached, then extract it into a new folder within
your project, where you can import it easily.
Here is an example file structure:
```txt
+ program.py
+ wrap_logger/ (you create this folder and place the files into it)
+ __init__.py
+ __wrap_logger.py
+ etc
```
You should then be able to use it normally:
```py
# program.py
from wrap_logger import wrap
...
```
### Logging to a file
`wrap-logger` will write to any file you give it.
```py
import sys
from wrap_logger import wrap
some_object = object()
wrapped = wrap(some_object, output=sys.stderr)
# All logs will go to stderr
```
## Implementation details
`wrap-logger` wraps objects in a `WrapLogger` class. Although the class does
override the `__class__` property so as to fool `isinstance` checks, fooling
the `type` function does not appear to work, so those checks may fail leading
to potentially erroneous behaviour.
## TODOs
`wrap-logger` was thrown together so I could quickly debug another project, so
it is incomplete. If there is demand (hint: create an issue), I will be happy
to try my hand at implementing the following features:
* [ ] Recursive wrapping, so that attributes of attributes are also logged
* [ ] Configuration on what is/isn't logged (currently it just prints
everything)
* [ ] Figure out what happens if you use `wrap-logger` on itself. Does it
crash? Does it delete System 32? Does the space-time continuum collapse?
Who knows!
## MIT License
Copyright (c) 2023 Maddy Guthridge
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.
Raw data
{
"_id": null,
"home_page": "https://github.com/MaddyGuthridge/python-wrap-logger",
"name": "wrap-logger",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "log, logger, wrapper, wrap",
"author": "Maddy Guthridge",
"author_email": "hdsq@outlook.com.au",
"download_url": "https://files.pythonhosted.org/packages/84/bf/ef6e2ede4cc48974e91611afea4bfbc52e57d706e63a3d381138b203378e/wrap_logger-0.2.1.tar.gz",
"platform": null,
"description": "# Wrap Logger\n\nA library to wrap around objects and modules in Python and log property\naccesses and calls.\n\n`pip install wrap-logger`\n\n## Rationale\n\nIn some cases when programming, errors can break things to the point where\nyou have no idea where things went wrong, for example, crashing the runtime\nenvironment before a backtrace can be printed. In these cases, it can be\nextremely useful to log changes to data that are potentially related to the\nissue, but doing so can be tedious and slow. I needed a simple solution to\neasily inject logging into objects, and so I created `wrap-logger`.\n\n## Usage\n\nUsing `wrap-logger` is simple. Simply call the `wrap` function, which will\nreturn a wrapped version.\n\n### With a module\n\n```py\nimport foo\nfrom wrap_logger import wrap\n\n# Now all function calls and global reads/writes will be logged\nfoo = wrap(foo)\n\n# Getting a property causes things to be logged\nfoo.bar\n# [WRAP LOG] > Get foo.bar\n# [WRAP LOG] < Get foo.bar: gave 42\n\n# Same for setting properties\nobj.bar = 43\n# [WRAP LOG] > Set foo.bar: 42 -> 43\n# [WRAP LOG] < Set foo.bar\n\n# And calling functions\nobj.echo('hello world')\n# [WRAP LOG] > Call foo.echo('hello world')\n# [WRAP LOG] < Call foo.echo('hello world'): returned 'hello world'\n```\n\n### With a class\n\n```py\nfrom wrap_logger import wrap\n\nclass Simple:\n def __init__(self) -> None:\n self.value = 42\n\n\n# Wrap an instance of the object\nobj = wrap(Simple())\n```\n\n### Without Pip\n\n`wrap-logger` requires no dependencies, and can even function with some parts\nof the standard library missing. Simply head over to the releases tab where the\n`wrap-logger.zip` file is attached, then extract it into a new folder within\nyour project, where you can import it easily.\n\nHere is an example file structure:\n\n```txt\n+ program.py\n+ wrap_logger/ (you create this folder and place the files into it)\n + __init__.py\n + __wrap_logger.py\n + etc\n```\n\nYou should then be able to use it normally:\n\n```py\n# program.py\nfrom wrap_logger import wrap\n\n...\n```\n\n### Logging to a file\n\n`wrap-logger` will write to any file you give it.\n\n```py\nimport sys\nfrom wrap_logger import wrap\n\nsome_object = object()\nwrapped = wrap(some_object, output=sys.stderr)\n# All logs will go to stderr\n```\n\n## Implementation details\n\n`wrap-logger` wraps objects in a `WrapLogger` class. Although the class does\noverride the `__class__` property so as to fool `isinstance` checks, fooling\nthe `type` function does not appear to work, so those checks may fail leading\nto potentially erroneous behaviour.\n\n## TODOs\n\n`wrap-logger` was thrown together so I could quickly debug another project, so\nit is incomplete. If there is demand (hint: create an issue), I will be happy\nto try my hand at implementing the following features:\n\n* [ ] Recursive wrapping, so that attributes of attributes are also logged\n* [ ] Configuration on what is/isn't logged (currently it just prints\n everything)\n* [ ] Figure out what happens if you use `wrap-logger` on itself. Does it\n crash? Does it delete System 32? Does the space-time continuum collapse?\n Who knows!\n\n## MIT License\n\nCopyright (c) 2023 Maddy Guthridge\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A library to wrap around objects and modules in Python and log property accesses and calls",
"version": "0.2.1",
"project_urls": {
"Bug Tracker": "https://github.com/MaddyGuthridge/python-wrap-logger/issues",
"Documentation": "https://github.com/MaddyGuthridge/python-wrap-logger",
"Homepage": "https://github.com/MaddyGuthridge/python-wrap-logger",
"Online Documentation": "https://github.com/MaddyGuthridge/python-wrap-logger",
"Repository": "https://github.com/MaddyGuthridge/python-wrap-logger"
},
"split_keywords": [
"log",
" logger",
" wrapper",
" wrap"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6aa31869e0cb8bfa01330afb023b5938064859951f779a92a183c1e180d0967e",
"md5": "f2a2bbdf8321303961fdf489921d9d9e",
"sha256": "2575797b733b90fd3548382bfe081c2574940c6836bfb2ad0ea9a28ecc4d9ccf"
},
"downloads": -1,
"filename": "wrap_logger-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2a2bbdf8321303961fdf489921d9d9e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 9070,
"upload_time": "2024-06-10T13:35:40",
"upload_time_iso_8601": "2024-06-10T13:35:40.696991Z",
"url": "https://files.pythonhosted.org/packages/6a/a3/1869e0cb8bfa01330afb023b5938064859951f779a92a183c1e180d0967e/wrap_logger-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "84bfef6e2ede4cc48974e91611afea4bfbc52e57d706e63a3d381138b203378e",
"md5": "ffa34629a827ab30068a063ce96a82f1",
"sha256": "3d6f375154a8a3bf5841b2fc60d22cdb481c7eedb995d3de72d3d17bc3eb655f"
},
"downloads": -1,
"filename": "wrap_logger-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "ffa34629a827ab30068a063ce96a82f1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 5135,
"upload_time": "2024-06-10T13:35:41",
"upload_time_iso_8601": "2024-06-10T13:35:41.865847Z",
"url": "https://files.pythonhosted.org/packages/84/bf/ef6e2ede4cc48974e91611afea4bfbc52e57d706e63a3d381138b203378e/wrap_logger-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-10 13:35:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MaddyGuthridge",
"github_project": "python-wrap-logger",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "wrap-logger"
}
JSON
