Convenience facilities for managing exceptions.
*Latest release 20240630*:
* LogExceptions: new optinal `log` param for the lgging call.
* @logexc: use @decorator like other civilised decorators, pass decorator params to LogExceptions.
## Function `exc_fold(*da, **dkw)`
Decorator to catch specific exception types and return a defined default value.
## Function `logexc(*da, **dkw)`
Decorator to log exceptions and reraise.
## Function `logexc_gen(*da, **dkw)`
Decorator to log exceptions and reraise for generators.
## Function `LogExceptions(log=None, conceal=False)`
Wrapper for `NoExceptions` which reports exceptions and optionally
suppresses them.
## Function `noexc(func)`
Decorator to wrap a function which should never raise an exception.
Instead, any raised exception is attempted to be logged.
A significant side effect is of course that if the function raises an
exception it now returns `None`.
My primary use case is actually to wrap logging functions,
which I have had abort otherwise sensible code.
## Function `noexc_gen(func)`
Decorator to wrap a generator which should never raise an exception.
Instead, any raised exception is attempted to be logged and iteration ends.
My primary use case is wrapping generators chained in a pipeline,
as in cs.later.Later.pipeline.
## Class `NoExceptions`
A context manager to catch _all_ exceptions and log them.
Arguably this should be a bare try...except but that's syntacticly
noisy and separates the catch from the top.
For simple function calls `return_exc_info()` is probably better.
*Method `NoExceptions.__init__(self, handler)`*:
Initialise the `NoExceptions` context manager.
The `handler` is a callable which
expects `(exc_type,exc_value,traceback)`
and returns `True` or `False`
for the `__exit__` method of the manager.
If `handler` is `None`, the `__exit__` method
always returns `True`, suppressing any exception.
## Function `return_exc_info(func, *args, **kwargs)`
Run the supplied function and arguments.
Return `(func_return, None)`
in the case of successful operation
and `(None, exc_info)` in the case of an exception.
`exc_info` is a 3-tuple of `(exc_type, exc_value, exc_traceback)`
as returned by `sys.exc_info()`.
If you need to protect a whole suite and would rather not move it
into its own function, consider the NoExceptions context manager.
## Function `returns_exc_info(func)`
Decorator function to wrap functions whose exceptions should be caught,
such as inside event loops or worker threads.
It causes a function to return `(func_return, None)`
in the case of successful operation
and `(None, exc_info)` in the case of an exception.
`exc_info` is a 3-tuple of `(exc_type, exc_value, exc_traceback)`
as returned by `sys.exc_info()`.
## Function `safe_property(func)`
Substitute for @property which lets AttributeErrors escape as RuntimeErrors.
## Function `transmute(*da, **dkw)`
Decorator to transmute an inner exception to another exception type.
The motivating use case is properties in a class with a
`__getattr__` method;
if some inner operation of the property function raises `AttributeError`
then the property is bypassed in favour of `__getattr__`.
Confusion ensues.
In principle this can be an issue with any exception raised
from "deeper" in the call chain, which can be mistaken for a
"shallow" exception raised by the function itself.
## Function `unattributable(func)`
Decorator to transmute `AttributeError` into a `RuntimeError`.
## Function `unimplemented(func)`
Decorator for stub methods that must be implemented by a stub class.
# Release Log
*Release 20240630*:
* LogExceptions: new optinal `log` param for the lgging call.
* @logexc: use @decorator like other civilised decorators, pass decorator params to LogExceptions.
*Release 20230212.1*:
Fix imports.
*Release 20230212*:
Import cs.gimmicks instead of cs.logutils, reduces dependencies.
*Release 20221228*:
Get warning etc from cs.gimmicks, breaks circular import with cs.logutils.
*Release 20221207*:
@unattributable: bugfix decorator construction to accomodate callable() @decorator precheck.
*Release 20210123*:
@transmute: refactor to raise chained exceptions in Python 3+.
*Release 20190812*:
LogExceptions: drop stack trace noise.
*Release 20190220*:
New decorator @exc_fold to catch particular exceptions, log an error and return a defined value.
*Release 20190101*:
@logexc: handle missing func.__name__.
*Release 20170904*:
Minor updates, improved docstring.
*Release 20160828*:
* @unattributable and @safe_property decorators, used to protect properties from inner AttributeErrors.
* Improved exception practices.
*Release 20150118*:
metadata updates
*Release 20150110*:
Initial distinfo for pypi release.
Raw data
{
"_id": null,
"home_page": null,
"name": "cs.excutils",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "python2, python3",
"author": null,
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/90/77/4a5379d748bcd349bfa2d37382b80f98e1e629ef6a03e6ac16944188134d/cs.excutils-20240630.tar.gz",
"platform": null,
"description": "Convenience facilities for managing exceptions.\n\n*Latest release 20240630*:\n* LogExceptions: new optinal `log` param for the lgging call.\n* @logexc: use @decorator like other civilised decorators, pass decorator params to LogExceptions.\n\n## Function `exc_fold(*da, **dkw)`\n\nDecorator to catch specific exception types and return a defined default value.\n\n## Function `logexc(*da, **dkw)`\n\nDecorator to log exceptions and reraise.\n\n## Function `logexc_gen(*da, **dkw)`\n\nDecorator to log exceptions and reraise for generators.\n\n## Function `LogExceptions(log=None, conceal=False)`\n\nWrapper for `NoExceptions` which reports exceptions and optionally\nsuppresses them.\n\n## Function `noexc(func)`\n\nDecorator to wrap a function which should never raise an exception.\nInstead, any raised exception is attempted to be logged.\n\nA significant side effect is of course that if the function raises an\nexception it now returns `None`.\nMy primary use case is actually to wrap logging functions,\nwhich I have had abort otherwise sensible code.\n\n## Function `noexc_gen(func)`\n\nDecorator to wrap a generator which should never raise an exception.\nInstead, any raised exception is attempted to be logged and iteration ends.\n\nMy primary use case is wrapping generators chained in a pipeline,\nas in cs.later.Later.pipeline.\n\n## Class `NoExceptions`\n\nA context manager to catch _all_ exceptions and log them.\n\nArguably this should be a bare try...except but that's syntacticly\nnoisy and separates the catch from the top.\nFor simple function calls `return_exc_info()` is probably better.\n\n*Method `NoExceptions.__init__(self, handler)`*:\nInitialise the `NoExceptions` context manager.\n\nThe `handler` is a callable which\nexpects `(exc_type,exc_value,traceback)`\nand returns `True` or `False`\nfor the `__exit__` method of the manager.\nIf `handler` is `None`, the `__exit__` method\nalways returns `True`, suppressing any exception.\n\n## Function `return_exc_info(func, *args, **kwargs)`\n\nRun the supplied function and arguments.\nReturn `(func_return, None)`\nin the case of successful operation\nand `(None, exc_info)` in the case of an exception.\n\n`exc_info` is a 3-tuple of `(exc_type, exc_value, exc_traceback)`\nas returned by `sys.exc_info()`.\nIf you need to protect a whole suite and would rather not move it\ninto its own function, consider the NoExceptions context manager.\n\n## Function `returns_exc_info(func)`\n\nDecorator function to wrap functions whose exceptions should be caught,\nsuch as inside event loops or worker threads.\n\nIt causes a function to return `(func_return, None)`\nin the case of successful operation\nand `(None, exc_info)` in the case of an exception.\n\n`exc_info` is a 3-tuple of `(exc_type, exc_value, exc_traceback)`\nas returned by `sys.exc_info()`.\n\n## Function `safe_property(func)`\n\nSubstitute for @property which lets AttributeErrors escape as RuntimeErrors.\n\n## Function `transmute(*da, **dkw)`\n\nDecorator to transmute an inner exception to another exception type.\n\nThe motivating use case is properties in a class with a\n`__getattr__` method;\nif some inner operation of the property function raises `AttributeError`\nthen the property is bypassed in favour of `__getattr__`.\nConfusion ensues.\n\nIn principle this can be an issue with any exception raised\nfrom \"deeper\" in the call chain, which can be mistaken for a\n\"shallow\" exception raised by the function itself.\n\n## Function `unattributable(func)`\n\nDecorator to transmute `AttributeError` into a `RuntimeError`.\n\n## Function `unimplemented(func)`\n\nDecorator for stub methods that must be implemented by a stub class.\n\n# Release Log\n\n\n\n*Release 20240630*:\n* LogExceptions: new optinal `log` param for the lgging call.\n* @logexc: use @decorator like other civilised decorators, pass decorator params to LogExceptions.\n\n*Release 20230212.1*:\nFix imports.\n\n*Release 20230212*:\nImport cs.gimmicks instead of cs.logutils, reduces dependencies.\n\n*Release 20221228*:\nGet warning etc from cs.gimmicks, breaks circular import with cs.logutils.\n\n*Release 20221207*:\n@unattributable: bugfix decorator construction to accomodate callable() @decorator precheck.\n\n*Release 20210123*:\n@transmute: refactor to raise chained exceptions in Python 3+.\n\n*Release 20190812*:\nLogExceptions: drop stack trace noise.\n\n*Release 20190220*:\nNew decorator @exc_fold to catch particular exceptions, log an error and return a defined value.\n\n*Release 20190101*:\n@logexc: handle missing func.__name__.\n\n*Release 20170904*:\nMinor updates, improved docstring.\n\n*Release 20160828*:\n* @unattributable and @safe_property decorators, used to protect properties from inner AttributeErrors.\n* Improved exception practices.\n\n*Release 20150118*:\nmetadata updates\n\n*Release 20150110*:\nInitial distinfo for pypi release.\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 or later (GPLv3+)",
"summary": "Convenience facilities for managing exceptions.",
"version": "20240630",
"project_urls": {
"MonoRepo Commits": "https://bitbucket.org/cameron_simpson/css/commits/branch/main",
"Monorepo Git Mirror": "https://github.com/cameron-simpson/css",
"Monorepo Hg/Mercurial Mirror": "https://hg.sr.ht/~cameron-simpson/css",
"Source": "https://github.com/cameron-simpson/css/blob/main/lib/python/cs/excutils.py"
},
"split_keywords": [
"python2",
" python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "61f30d1f365480971d148620c06cf44cd2ede0f321ad7867e5caddc4b2e9a54e",
"md5": "864c8a6aab997168795f8533de78658f",
"sha256": "b6a5dc66d83f0571d3222f8c495b84db9e51b92ff8001eb63552f4337e051bae"
},
"downloads": -1,
"filename": "cs.excutils-20240630-py3-none-any.whl",
"has_sig": false,
"md5_digest": "864c8a6aab997168795f8533de78658f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 6118,
"upload_time": "2024-06-30T01:16:30",
"upload_time_iso_8601": "2024-06-30T01:16:30.778907Z",
"url": "https://files.pythonhosted.org/packages/61/f3/0d1f365480971d148620c06cf44cd2ede0f321ad7867e5caddc4b2e9a54e/cs.excutils-20240630-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "90774a5379d748bcd349bfa2d37382b80f98e1e629ef6a03e6ac16944188134d",
"md5": "10148737abdfd6d14822295e40ec705c",
"sha256": "0cf090aab5e1203212b344e75871d70d1ec7db4bc3140e70a31521ca94a027ba"
},
"downloads": -1,
"filename": "cs.excutils-20240630.tar.gz",
"has_sig": false,
"md5_digest": "10148737abdfd6d14822295e40ec705c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5520,
"upload_time": "2024-06-30T01:16:32",
"upload_time_iso_8601": "2024-06-30T01:16:32.488271Z",
"url": "https://files.pythonhosted.org/packages/90/77/4a5379d748bcd349bfa2d37382b80f98e1e629ef6a03e6ac16944188134d/cs.excutils-20240630.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-30 01:16:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cameron-simpson",
"github_project": "css",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "cs.excutils"
}
JSON
