# [flake8-keyword-params](https://github.com/plinss/flake8-keyword-params)
flake8 plugin to require that optional parameters are keyword-only.
This is a highly opinionated plugin asserting that optional parameters should be keyword-only (see [PEP-3102](https://peps.python.org/pep-3102/)).
Requiring keywords for optional parameters generally improves readability at point of use,
especially for parameters that are seldomly used
or would otherwise fall into the [bool trap](https://adamj.eu/tech/2021/07/10/python-type-hints-how-to-avoid-the-boolean-trap/).
Note that when addressing issues found by this plugin,
sometimes a better answer than making the parameter keyword-only is to make it non-optional
or position-only (see [PEP-570](https://peps.python.org/pep-0570/)).
Accepting that there are common use cases where a keyword-only parameter offers little value,
this plugin allows a safelist of function names and parameters that are allowed to be optional.
A small predefined set is included by default,
but may be extended or replaced via config options.
Feel free to file issues to request more default safe entries,
especially any in the Python standard library.
## Installation
Standard python package installation:
pip install flake8-keyword-params
## Options
`keyword-params-safelist`
: Add a function to the safelist, may be specified more than once
`keyword-params-exclude-safelist`
: Remove a function from the safelist, may be specified more than once
`keyword-params-include-name`
: Include plugin name in messages
`keyword-params-no-include-name`
: Do not include plugin name in messages (default setting)
All options may be specified on the command line with a `--` prefix,
or can be placed in your flake8 config file.
Safelist options may specify a bare function name,
so that all parameters are allowed to be optional without keywords,
or a function name, followed by a colon, followed by a parameter name.
In the latter case, only the specified parameters may be optional without keywords.
Both function names and parameter names may be regular expressions.
For example:
```
flake8 --keyword-params-safelist=get:default --keyword-params-safelist="from_.*:default"
```
in .flake8 or setup.cfg
```
[flake8]
keyword-params-safelist = get:default from_.*:default
```
or in pyproject.toml:
```
[tool.flake8]
keyword-params-safelist = ['get:default', 'from_.*:default']
```
## Error Codes
| Code | Message |
|--------|---------|
| KWP001 | Optional parameter 'param' should be keyword only
## Examples
```
def foo(x=None): <-- KWP001
def get(key, default=None): <-- No error, common use case
```
Raw data
{
"_id": null,
"home_page": "",
"name": "flake8-keyword-params",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "flake8",
"author": "",
"author_email": "Peter Linss <pypi@linss.com>",
"download_url": "https://files.pythonhosted.org/packages/48/91/b78c498a6dd263887b0b8c3ea43c652880b01307b583e1bd7cc52f6e37ce/flake8-keyword-params-1.2.0.tar.gz",
"platform": null,
"description": "# [flake8-keyword-params](https://github.com/plinss/flake8-keyword-params)\n\nflake8 plugin to require that optional parameters are keyword-only.\n\nThis is a highly opinionated plugin asserting that optional parameters should be keyword-only (see [PEP-3102](https://peps.python.org/pep-3102/)).\nRequiring keywords for optional parameters generally improves readability at point of use,\nespecially for parameters that are seldomly used \nor would otherwise fall into the [bool trap](https://adamj.eu/tech/2021/07/10/python-type-hints-how-to-avoid-the-boolean-trap/).\n\nNote that when addressing issues found by this plugin,\nsometimes a better answer than making the parameter keyword-only is to make it non-optional\nor position-only (see [PEP-570](https://peps.python.org/pep-0570/)).\n\nAccepting that there are common use cases where a keyword-only parameter offers little value,\nthis plugin allows a safelist of function names and parameters that are allowed to be optional.\nA small predefined set is included by default,\nbut may be extended or replaced via config options.\nFeel free to file issues to request more default safe entries,\nespecially any in the Python standard library. \n\n## Installation\n\nStandard python package installation:\n\n pip install flake8-keyword-params\n\n\n## Options\n\n`keyword-params-safelist`\n: Add a function to the safelist, may be specified more than once \n\n`keyword-params-exclude-safelist`\n: Remove a function from the safelist, may be specified more than once \n\n`keyword-params-include-name`\n: Include plugin name in messages\n\n`keyword-params-no-include-name`\n: Do not include plugin name in messages (default setting)\n\nAll options may be specified on the command line with a `--` prefix,\nor can be placed in your flake8 config file.\n\nSafelist options may specify a bare function name, \nso that all parameters are allowed to be optional without keywords, \nor a function name, followed by a colon, followed by a parameter name.\nIn the latter case, only the specified parameters may be optional without keywords.\nBoth function names and parameter names may be regular expressions.\n\nFor example:\n```\nflake8 --keyword-params-safelist=get:default --keyword-params-safelist=\"from_.*:default\"\n```\nin .flake8 or setup.cfg\n```\n[flake8]\nkeyword-params-safelist = get:default from_.*:default\n```\nor in pyproject.toml:\n```\n[tool.flake8]\nkeyword-params-safelist = ['get:default', 'from_.*:default']\n```\n\n\n## Error Codes\n\n| Code | Message |\n|--------|---------|\n| KWP001 | Optional parameter 'param' should be keyword only\n\n\n## Examples\n\n```\ndef foo(x=None): <-- KWP001\n\ndef get(key, default=None): <-- No error, common use case\n```\n",
"bugtrack_url": null,
"license": "GNU Lesser General Public License v3",
"summary": "Flake8 keyword parameter validation",
"version": "1.2.0",
"project_urls": {
"homepage": "https://github.com/plinss/flake8-keyword-params"
},
"split_keywords": [
"flake8"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "01717b8f68921c3999081f19c37f8a1a057d00ec5ef7d0a8272e7af8335ae057",
"md5": "bb90ddaade70c0f2dcf64118f16ed349",
"sha256": "44544a2d067a853ca44035701873fa02909a74e21ec72a1b9aded5851a10041e"
},
"downloads": -1,
"filename": "flake8_keyword_params-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bb90ddaade70c0f2dcf64118f16ed349",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 5649,
"upload_time": "2024-01-06T03:58:20",
"upload_time_iso_8601": "2024-01-06T03:58:20.491217Z",
"url": "https://files.pythonhosted.org/packages/01/71/7b8f68921c3999081f19c37f8a1a057d00ec5ef7d0a8272e7af8335ae057/flake8_keyword_params-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4891b78c498a6dd263887b0b8c3ea43c652880b01307b583e1bd7cc52f6e37ce",
"md5": "c4409550b5ea8ba0c9635005d8a0be96",
"sha256": "96a1dad03c0b752761d35f0c98d33aba74bb247d89b9a5bc6f91868d9c8ca026"
},
"downloads": -1,
"filename": "flake8-keyword-params-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "c4409550b5ea8ba0c9635005d8a0be96",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 6491,
"upload_time": "2024-01-06T03:58:21",
"upload_time_iso_8601": "2024-01-06T03:58:21.866944Z",
"url": "https://files.pythonhosted.org/packages/48/91/b78c498a6dd263887b0b8c3ea43c652880b01307b583e1bd7cc52f6e37ce/flake8-keyword-params-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-06 03:58:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "plinss",
"github_project": "flake8-keyword-params",
"github_not_found": true,
"lcname": "flake8-keyword-params"
}
JSON
