# better-exceptions
Pretty and more helpful exceptions in Python, automatically.
## Usage
Install `better_exceptions` via pip:
```console
pip install better_exceptions
```
And set the `BETTER_EXCEPTIONS` environment variable to any value:
```bash
export BETTER_EXCEPTIONS=1 # Linux / OSX
setx BETTER_EXCEPTIONS 1 # Windows
```
That's it!
### Python REPL (Interactive Shell)
In order to use `better_exceptions` in the Python REPL, first install the package (as instructed above) and run:
```console
$ python -m better_exceptions
Type "help", "copyright", "credits" or "license" for more information.
(BetterExceptionsConsole)
>>>
```
in order to drop into a `better_exceptions`-enabled Python interactive shell.
### Advanced Usage
If you want to allow the entirety of values to be outputted instead of being truncated to a certain amount of characters:
```python
import better_exceptions
better_exceptions.MAX_LENGTH = None
```
While using `better_exceptions` in production, do not forget to unset the `BETTER_EXCEPTIONS` variable to avoid leaking sensitive data in your logs.
### Use with unittest
If you want to use `better_exceptions` to format `unittest`'s exception output, you can use the monkey patch below:
```python
import sys
import unittest
import better_exceptions
def patch(self, err, test):
lines = better_exceptions.format_exception(*err)
if sys.version_info[0] == 2:
return u"".join(lines).encode("utf-8")
return "".join(lines)
unittest.result.TestResult._exc_info_to_string = patch
```
Note that this uses an undocumented method override, so it is **not** guaranteed to work on all platforms or versions of Python.
### Django Usage
In `settings.py`, add your new class to the `MIDDLEWARE` setting and update your logging configuration:
```python
# ...
MIDDLEWARE = [
# ...
"better_exceptions.integrations.django.BetterExceptionsMiddleware",
]
# ...
from better_exceptions.integrations.django import skip_errors_filter
# if you don't want to override LOGGING because you want to change the default,
# you can vendor Django's default logging configuration and update it for
# better-exceptions. the default for Django 3.1.4 can be found here:
# https://github.com/django/django/blob/3.1.4/django/utils/log.py#L13-L63
LOGGING = {
'version': 1,
'disable_existing_loggers': False,
'filters': {
'skip_errors': {
'()': 'django.utils.log.CallbackFilter',
'callback': skip_errors_filter,
}
},
'handlers': {
'console': {
'level': 'INFO',
# without the 'filters' key, Django will log errors twice:
# one time from better-exceptions and one time from Django.
# with the 'skip_errors' filter, we remove the repeat log
# from Django, which is unformatted.
'filters': ['skip_errors'],
'class': 'logging.StreamHandler',
}
},
'loggers': {
'django': {
'handlers': [
'console',
],
}
}
}
```
example output:
## Troubleshooting
If you do not see beautiful exceptions, first make sure that the environment variable does exist. You can try `echo $BETTER_EXCEPTIONS` (Linux / OSX) or `echo %BETTER_EXCEPTIONS%` (Windows). On Linux and OSX, the `export` command does not add the variable permanently, you will probably need to edit the `~/.profile` file to make it persistent. On Windows, you need to open a new terminal after the `setx` command.
Check that there is no conflict with another library, and that the `sys.excepthook` function has been correctly replaced with the `better_exceptions`'s one. Sometimes other components can set up their own exception handlers, such as the `python3-apport` Ubuntu package that you may need to uninstall.
Make sure that you have not inadvertently deleted the `better_exceptions_hook.pth` file that should be in the same place as the `better_exceptions` folder where all of your Python packages are installed. Otherwise, try re-installing `better_exceptions`.
You can also try to manually activate the hook by adding `import better_exceptions; better_exceptions.hook()` at the beginning of your script.
Finally, if you still can not get this module to work, [open a new issue](https://github.com/Qix-/better-exceptions/issues/new) by describing your problem precisely and detailing your configuration (Python and `better_exceptions` versions, OS, code snippet, interpreter, etc.) so that we can reproduce the bug you are experiencing.
# License
Copyright © 2017, Josh Junon. Licensed under the [MIT license](LICENSE.txt).
Raw data
{
"_id": null,
"home_page": null,
"name": "better-exceptions-xl0",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "pretty, better, exceptions, exception, error, local, debug, debugging, locals",
"author": null,
"author_email": "Josh Junon <pypi@josh.junon.me>",
"download_url": "https://files.pythonhosted.org/packages/0f/da/b5818398f560258d5a4306bb93412d544e103febf490a984486a510d0be4/better_exceptions_xl0-0.4.3.tar.gz",
"platform": null,
"description": "# better-exceptions\n\nPretty and more helpful exceptions in Python, automatically.\n\n\n\n## Usage\n\nInstall `better_exceptions` via pip:\n\n```console\npip install better_exceptions\n```\n\nAnd set the `BETTER_EXCEPTIONS` environment variable to any value:\n\n```bash\nexport BETTER_EXCEPTIONS=1 # Linux / OSX\nsetx BETTER_EXCEPTIONS 1 # Windows\n```\n\nThat's it!\n\n### Python REPL (Interactive Shell)\n\nIn order to use `better_exceptions` in the Python REPL, first install the package (as instructed above) and run:\n\n```console\n$ python -m better_exceptions\nType \"help\", \"copyright\", \"credits\" or \"license\" for more information.\n(BetterExceptionsConsole)\n>>>\n```\n\nin order to drop into a `better_exceptions`-enabled Python interactive shell.\n\n### Advanced Usage\n\nIf you want to allow the entirety of values to be outputted instead of being truncated to a certain amount of characters:\n\n```python\nimport better_exceptions\nbetter_exceptions.MAX_LENGTH = None\n```\n\nWhile using `better_exceptions` in production, do not forget to unset the `BETTER_EXCEPTIONS` variable to avoid leaking sensitive data in your logs.\n\n### Use with unittest\n\nIf you want to use `better_exceptions` to format `unittest`'s exception output, you can use the monkey patch below:\n\n```python\nimport sys\nimport unittest\nimport better_exceptions\n\ndef patch(self, err, test):\n lines = better_exceptions.format_exception(*err)\n if sys.version_info[0] == 2:\n return u\"\".join(lines).encode(\"utf-8\")\n return \"\".join(lines)\n\nunittest.result.TestResult._exc_info_to_string = patch\n```\n\nNote that this uses an undocumented method override, so it is **not** guaranteed to work on all platforms or versions of Python.\n\n### Django Usage\n\nIn `settings.py`, add your new class to the `MIDDLEWARE` setting and update your logging configuration:\n\n```python\n# ...\n\nMIDDLEWARE = [\n # ...\n \"better_exceptions.integrations.django.BetterExceptionsMiddleware\",\n]\n\n# ...\n\nfrom better_exceptions.integrations.django import skip_errors_filter\n\n# if you don't want to override LOGGING because you want to change the default,\n# you can vendor Django's default logging configuration and update it for\n# better-exceptions. the default for Django 3.1.4 can be found here:\n# https://github.com/django/django/blob/3.1.4/django/utils/log.py#L13-L63\nLOGGING = {\n 'version': 1,\n 'disable_existing_loggers': False,\n 'filters': {\n 'skip_errors': {\n '()': 'django.utils.log.CallbackFilter',\n 'callback': skip_errors_filter,\n }\n },\n 'handlers': {\n 'console': {\n 'level': 'INFO',\n # without the 'filters' key, Django will log errors twice:\n # one time from better-exceptions and one time from Django.\n # with the 'skip_errors' filter, we remove the repeat log\n # from Django, which is unformatted.\n 'filters': ['skip_errors'],\n 'class': 'logging.StreamHandler',\n }\n },\n 'loggers': {\n 'django': {\n 'handlers': [\n 'console',\n ],\n }\n }\n}\n```\n\nexample output:\n\n\n\n## Troubleshooting\n\nIf you do not see beautiful exceptions, first make sure that the environment variable does exist. You can try `echo $BETTER_EXCEPTIONS` (Linux / OSX) or `echo %BETTER_EXCEPTIONS%` (Windows). On Linux and OSX, the `export` command does not add the variable permanently, you will probably need to edit the `~/.profile` file to make it persistent. On Windows, you need to open a new terminal after the `setx` command.\n\nCheck that there is no conflict with another library, and that the `sys.excepthook` function has been correctly replaced with the `better_exceptions`'s one. Sometimes other components can set up their own exception handlers, such as the `python3-apport` Ubuntu package that you may need to uninstall.\n\nMake sure that you have not inadvertently deleted the `better_exceptions_hook.pth` file that should be in the same place as the `better_exceptions` folder where all of your Python packages are installed. Otherwise, try re-installing `better_exceptions`.\n\nYou can also try to manually activate the hook by adding `import better_exceptions; better_exceptions.hook()` at the beginning of your script.\n\nFinally, if you still can not get this module to work, [open a new issue](https://github.com/Qix-/better-exceptions/issues/new) by describing your problem precisely and detailing your configuration (Python and `better_exceptions` versions, OS, code snippet, interpreter, etc.) so that we can reproduce the bug you are experiencing.\n\n# License\n\nCopyright © 2017, Josh Junon. Licensed under the [MIT license](LICENSE.txt).\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pretty and helpful exceptions, automatically",
"version": "0.4.3",
"project_urls": {
"Download": "https://github.com/qix-/better-exceptions/releases",
"Homepage": "https://github.com/qix-/better-exceptions",
"Repository": "https://github.com/qix-/better-exceptions"
},
"split_keywords": [
"pretty",
" better",
" exceptions",
" exception",
" error",
" local",
" debug",
" debugging",
" locals"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18de9a1f6d4ebf889eff1c572ea572bc71b7570b5d6837f7a4e2b8d20784b4a3",
"md5": "7b088e59e0e66a600b0af5918f4ac369",
"sha256": "00fbe4ccaa06911ac09213849582da44cfa99f999c35c99c1c15bd2e2e207e73"
},
"downloads": -1,
"filename": "better_exceptions_xl0-0.4.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b088e59e0e66a600b0af5918f4ac369",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 13285,
"upload_time": "2025-10-22T19:37:23",
"upload_time_iso_8601": "2025-10-22T19:37:23.764201Z",
"url": "https://files.pythonhosted.org/packages/18/de/9a1f6d4ebf889eff1c572ea572bc71b7570b5d6837f7a4e2b8d20784b4a3/better_exceptions_xl0-0.4.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0fdab5818398f560258d5a4306bb93412d544e103febf490a984486a510d0be4",
"md5": "1ec862759a785181591b40d6ac388a8e",
"sha256": "09a44606bbc9435e88ad5303d431b64415827963f8b050110345bba6ba335d46"
},
"downloads": -1,
"filename": "better_exceptions_xl0-0.4.3.tar.gz",
"has_sig": false,
"md5_digest": "1ec862759a785181591b40d6ac388a8e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 22191,
"upload_time": "2025-10-22T19:37:25",
"upload_time_iso_8601": "2025-10-22T19:37:25.277876Z",
"url": "https://files.pythonhosted.org/packages/0f/da/b5818398f560258d5a4306bb93412d544e103febf490a984486a510d0be4/better_exceptions_xl0-0.4.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 19:37:25",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qix-",
"github_project": "better-exceptions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "better-exceptions-xl0"
}
JSON
