Convenience facilities for managing exceptions.
*Latest release 20230212.1*:
Fix imports.
## Function `exc_fold(*da, **dkw)`
Decorator to catch specific exception types and return a defined default value.
## Function `logexc(func)`
Decorator to log exceptions and reraise.
## Function `logexc_gen(genfunc)`
Decorator to log exceptions and reraise for generators.
## Function `LogExceptions(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 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": "https://bitbucket.org/cameron_simpson/css/commits/all",
"name": "cs.excutils",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "python2,python3",
"author": "Cameron Simpson",
"author_email": "Cameron Simpson <cs@cskk.id.au>",
"download_url": "https://files.pythonhosted.org/packages/15/5c/0168fe60f276966c0b4fa4594b4a2bb4ce28035300047b72ae7cec307df3/cs.excutils-20230212.1.tar.gz",
"platform": null,
"description": "Convenience facilities for managing exceptions.\n\n*Latest release 20230212.1*:\nFix imports.\n\n## Function `exc_fold(*da, **dkw)`\n\nDecorator to catch specific exception types and return a defined default value.\n\n## Function `logexc(func)`\n\nDecorator to log exceptions and reraise.\n\n## Function `logexc_gen(genfunc)`\n\nDecorator to log exceptions and reraise for generators.\n\n## Function `LogExceptions(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 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": "20230212.1",
"split_keywords": [
"python2",
"python3"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3efcf1fdf34482fd175fbb5ac2ec621d6662066bd6de6a9f6fc0d52efc6f014",
"md5": "c8785c0215216a97497f903c3f9ea571",
"sha256": "eb5bf1ca718dc5741b70141825e4f44fc258e25250b521173482489ff7b47b1a"
},
"downloads": -1,
"filename": "cs.excutils-20230212.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c8785c0215216a97497f903c3f9ea571",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 5986,
"upload_time": "2023-02-11T23:52:16",
"upload_time_iso_8601": "2023-02-11T23:52:16.675943Z",
"url": "https://files.pythonhosted.org/packages/c3/ef/cf1fdf34482fd175fbb5ac2ec621d6662066bd6de6a9f6fc0d52efc6f014/cs.excutils-20230212.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "155c0168fe60f276966c0b4fa4594b4a2bb4ce28035300047b72ae7cec307df3",
"md5": "a61224d50b3f276e139ea892d587ea72",
"sha256": "6bd0f489bc25508acece2253fd05712ebb5fe802a77ebb3a17c8839324524bd1"
},
"downloads": -1,
"filename": "cs.excutils-20230212.1.tar.gz",
"has_sig": false,
"md5_digest": "a61224d50b3f276e139ea892d587ea72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 5549,
"upload_time": "2023-02-11T23:52:18",
"upload_time_iso_8601": "2023-02-11T23:52:18.631804Z",
"url": "https://files.pythonhosted.org/packages/15/5c/0168fe60f276966c0b4fa4594b4a2bb4ce28035300047b72ae7cec307df3/cs.excutils-20230212.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-11 23:52:18",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "cs.excutils"
}
JSON