| Name | flake8-error-link JSON |
| Version |
1.2.4
JSON |
| download |
| home_page | |
| Summary | A linter that ensures all raised Exceptions include an error with a link to more information |
| upload_time | 2023-01-04 08:07:35 |
| maintainer | |
| docs_url | None |
| author | David Andersson |
| requires_python | >=3.8.1,<4.0.0 |
| license | Apache 2.0 |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# flake8-error-link
Have you ever encountered an error when using a package and then gone to Google
to find out how to solve the error? Wouldn't your users prefer to go directly
to your documentation that tells them exactly what went wrong and how to
resolve that error? `flake8-error-link` checks the way exceptions are raised in
your code base to ensure that a link with more information is provided.
## Getting Started
```shell
python -m venv venv
source ./venv/bin/activate
pip install flake8 flake8-error-link
flake8 source.py
```
On the following code:
```Python
# source.py
raise Exception
```
This will produce warnings such as:
```shell
source.py:1:0: ELI001 builtin exceptions should be raised with a link to more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001
```
This can be resolved by changing the code to:
```Python
# source.py
raise Exception("more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001")
```
## Configuration
The plugin adds the following configurations to `flake8`:
* `--error-link-regex`: The regular expression to use to verify the way
exceptions are reased, defaults to
`more information: (mailto\:|(news|(ht|f)tp(s?))\:\/\/){1}\S+`
## Rules
A few rules have been defined to allow for selective suppression:
* `ELI001`: checks that any builtin exceptions that are raised with constant
arguments include a link to more information.
* `ELI002`: checks that any custom exceptions that are raised with constant
arguments include a link to more information.
* `ELI003`: checks that any exceptions that are raised with variable arguments
include a constant argument with a link to more information.
* `ELI004`: checks that any exceptions that are re-raised include a constant
argument with a link to more information.
### Fix ELI001
This linting rule is trigger by raising an inbuilt exception without providing
a constant that includes a link to more information as one of the arguments to
the constructor. For example:
```Python
raise Exception
raise ValueError
raise Exception()
raise Exception("oh no! :(")
```
These examples can be fixed by using something like:
```Python
raise Exception(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001"
)
raise ValueError(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001"
)
raise Exception(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001"
)
raise Exception(
"oh no! :(",
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001",
)
```
### Fix ELI002
This linting rule is trigger by raising a custom exception without providing
a constant that include a link to more information as one of the arguments to
the constructor. For example:
```Python
class CustomError(Exception):
pass
raise CustomError
raise CustomError()
raise CustomError("bummer...")
```
These examples can be fixed by using something like:
```Python
class CustomError(Exception):
pass
raise CustomError(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002"
)
raise CustomError(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002"
)
raise CustomError(
"bummer...",
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002",
)
```
### Fix ELI003
This linting rule is trigger by raising an exception and passing at least one
argument without providing a constant that include a link to more information
as one of the arguments to the constructor. For example:
```Python
message = "gotcha"
def get_message():
return message
raise Exception(get_message())
raise Exception(f"{message} quite badly")
```
These examples can be fixed by using something like:
```Python
message = "gotcha"
def get_message():
return message
raise Exception(
get_message(),
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli003",
)
raise Exception(
f"{message} quite badly, more information: https://github.com/jdkandersson/flake8-error-link#fix-eli003"
)
```
### Fix ELI004
This linting rule is trigger by re-raising an exception. For example:
```Python
try:
raise Exception(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004"
)
except Exception:
raise
```
This example can be fixed by using something like:
```Python
try:
raise Exception(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004"
)
except Exception as exc:
raise Exception(
"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004"
) from exc
```
This rule can be spurious at times if an exception is re-raisesd that already
has a more information link. Regardless, it is usually a good idea to include a
specific link for a problem. The context is usually different when an exception
is re-raised so it could be useful to include documentation for that context
rather then relying on any link provided by the original exception.
Raw data
{
"_id": null,
"home_page": "",
"name": "flake8-error-link",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8.1,<4.0.0",
"maintainer_email": "",
"keywords": "",
"author": "David Andersson",
"author_email": "david@jdkandersson.com",
"download_url": "https://files.pythonhosted.org/packages/89/05/85840184d8448af12e163b1c10350f8bcb12c3a12c18e3a51da152b0c79e/flake8_error_link-1.2.4.tar.gz",
"platform": null,
"description": "# flake8-error-link\n\nHave you ever encountered an error when using a package and then gone to Google\nto find out how to solve the error? Wouldn't your users prefer to go directly\nto your documentation that tells them exactly what went wrong and how to\nresolve that error? `flake8-error-link` checks the way exceptions are raised in\nyour code base to ensure that a link with more information is provided.\n\n## Getting Started\n\n```shell\npython -m venv venv\nsource ./venv/bin/activate\npip install flake8 flake8-error-link\nflake8 source.py\n```\n\nOn the following code:\n\n```Python\n# source.py\nraise Exception\n```\n\nThis will produce warnings such as:\n\n```shell\nsource.py:1:0: ELI001 builtin exceptions should be raised with a link to more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\n```\n\nThis can be resolved by changing the code to:\n\n```Python\n# source.py\nraise Exception(\"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\")\n```\n\n## Configuration\n\nThe plugin adds the following configurations to `flake8`:\n\n* `--error-link-regex`: The regular expression to use to verify the way\n exceptions are reased, defaults to\n `more information: (mailto\\:|(news|(ht|f)tp(s?))\\:\\/\\/){1}\\S+`\n\n\n## Rules\n\nA few rules have been defined to allow for selective suppression:\n\n* `ELI001`: checks that any builtin exceptions that are raised with constant\n arguments include a link to more information.\n* `ELI002`: checks that any custom exceptions that are raised with constant\n arguments include a link to more information.\n* `ELI003`: checks that any exceptions that are raised with variable arguments\n include a constant argument with a link to more information.\n* `ELI004`: checks that any exceptions that are re-raised include a constant\n argument with a link to more information.\n\n### Fix ELI001\n\nThis linting rule is trigger by raising an inbuilt exception without providing\na constant that includes a link to more information as one of the arguments to\nthe constructor. For example:\n\n```Python\nraise Exception\n\nraise ValueError\n\nraise Exception()\n\nraise Exception(\"oh no! :(\")\n```\n\nThese examples can be fixed by using something like:\n\n```Python\nraise Exception(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\"\n)\n\nraise ValueError(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\"\n)\n\nraise Exception(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\"\n)\n\nraise Exception(\n \"oh no! :(\",\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli001\",\n)\n```\n\n### Fix ELI002\n\nThis linting rule is trigger by raising a custom exception without providing\na constant that include a link to more information as one of the arguments to\nthe constructor. For example:\n\n```Python\nclass CustomError(Exception):\n pass\n\nraise CustomError\n\nraise CustomError()\n\nraise CustomError(\"bummer...\")\n```\n\nThese examples can be fixed by using something like:\n\n```Python\nclass CustomError(Exception):\n pass\n\nraise CustomError(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002\"\n)\n\nraise CustomError(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002\"\n)\n\nraise CustomError(\n \"bummer...\",\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli002\",\n)\n```\n\n### Fix ELI003\n\nThis linting rule is trigger by raising an exception and passing at least one\nargument without providing a constant that include a link to more information\nas one of the arguments to the constructor. For example:\n\n```Python\nmessage = \"gotcha\"\n\ndef get_message():\n return message\n\nraise Exception(get_message())\n\nraise Exception(f\"{message} quite badly\")\n```\n\nThese examples can be fixed by using something like:\n\n```Python\nmessage = \"gotcha\"\n\ndef get_message():\n return message\n\nraise Exception(\n get_message(),\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli003\",\n)\n\nraise Exception(\n f\"{message} quite badly, more information: https://github.com/jdkandersson/flake8-error-link#fix-eli003\"\n)\n```\n\n### Fix ELI004\n\nThis linting rule is trigger by re-raising an exception. For example:\n\n```Python\ntry:\n raise Exception(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004\"\n )\nexcept Exception:\n raise\n```\n\nThis example can be fixed by using something like:\n\n```Python\ntry:\n raise Exception(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004\"\n )\nexcept Exception as exc:\n raise Exception(\n \"more information: https://github.com/jdkandersson/flake8-error-link#fix-eli004\"\n ) from exc\n```\n\nThis rule can be spurious at times if an exception is re-raisesd that already\nhas a more information link. Regardless, it is usually a good idea to include a\nspecific link for a problem. The context is usually different when an exception\nis re-raised so it could be useful to include documentation for that context\nrather then relying on any link provided by the original exception.\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "A linter that ensures all raised Exceptions include an error with a link to more information",
"version": "1.2.4",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "18c3a18638de8c5b1812058c40914927b11e1a0d43cd7264cbfa982a1839400b",
"md5": "b44316c0a2c2b2c7e70ab20fefd2d55e",
"sha256": "930702b5b000b6c7b6d6a250854297e303fd500c772fdf1e3e7070346dff526d"
},
"downloads": -1,
"filename": "flake8_error_link-1.2.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b44316c0a2c2b2c7e70ab20fefd2d55e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1,<4.0.0",
"size": 10149,
"upload_time": "2023-01-04T08:07:34",
"upload_time_iso_8601": "2023-01-04T08:07:34.189233Z",
"url": "https://files.pythonhosted.org/packages/18/c3/a18638de8c5b1812058c40914927b11e1a0d43cd7264cbfa982a1839400b/flake8_error_link-1.2.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "890585840184d8448af12e163b1c10350f8bcb12c3a12c18e3a51da152b0c79e",
"md5": "5f5fd8ae2033b47a29a8a6092604d1af",
"sha256": "b29d61e7e6ad1545df479ceb71a2d5140b0c73f2a6f0f4f0ebaee2f34df9e25c"
},
"downloads": -1,
"filename": "flake8_error_link-1.2.4.tar.gz",
"has_sig": false,
"md5_digest": "5f5fd8ae2033b47a29a8a6092604d1af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1,<4.0.0",
"size": 10022,
"upload_time": "2023-01-04T08:07:35",
"upload_time_iso_8601": "2023-01-04T08:07:35.514976Z",
"url": "https://files.pythonhosted.org/packages/89/05/85840184d8448af12e163b1c10350f8bcb12c3a12c18e3a51da152b0c79e/flake8_error_link-1.2.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-04 08:07:35",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "flake8-error-link"
}
