# Module Level Lint
A Flake8 plugin to enforce code quality by checking module level docstrings, future-imports, and module level dunders as specified in [PEP 8](https://peps.python.org/pep-0008/#module-level-dunder-names)
## Installation
You can install this plugin via pip:
```bash
pip install module-level-lint
```
## Usage
After installation, you can use this plugin with the `flake8` command. Here's how to run it:
```bash
flake8 [path]
```
To show only module level lint errors, run:
```bash
flake8 --select MLL [path]
```
To show only specific errors
```bash
flake8 --select MLL001,MLL002 [path]
```
To apply formatting
```bash
flake8 --select MLL [path] --fix
```
## Features
### Lint
#### Module Docstring Check: Ensure that your docstrings are always at the top of the file
- Linting Error: **MLL001**
Example:
```python
import random
# Bad: Module docstring is not at the top of the file
"""This is a docstring"""
def foo():
pass
```
```python
# Good: Docstring present at the top of the file
""" This is a docstring. """
def foo():
pass
```
#### Future-Imports Check: Ensure that future-imports are always at the top after module docstrings
- Linting Error: **MLL002**
Example:
```python
import random
# Bad: Future-imports is not at the top of the file
from __future__ import print_function
```
```python
# Good: Future-imports is at the top of the file
from __future__ import division
import random
```
- Linting Error: **MLL003**
Example:
```python
from __future__ import print_function
# Bad: Docstring is not at the top of the file
"""This is a docstring."""
```
```python
"""This is a docstring."""
# Good: Future-imports is at the top of the file after docstring
from __future__ import division
```
#### Module-Level Dunders: Ensure that module level dunders are always at the top after future-imports or docstrings
- Linting Error: **MLL004**
Example:
```python
import random
# Bad: Module level dunder after imports
__all__ = ["foo"]
def foo():
pass
```
```python
# Bad: Module level dunder before docstring
__all__ = ["foo"]
"""This is a docstring"""
def foo():
pass
```
```python
def foo():
pass
# Bad: Module level dunder after code
__all__ = ["foo"]
```
```python
# Good: Module level dunder at the top of the file
__all__ = ["foo"]
def foo():
pass
```
### Format
With the `--fix` flag, this plugin will try to format the files that have no rule violations. It will fix the newlines in the following format:
```python
"""Docstring goes here""" # An empty line after docstrings
from __future__ import annotations # An empty line after future imports
__all__ = ["foo"] # An empty line after module dunders
import random # Rest of the code
def foo():
return random.randint(1, 10)
```
## Configuration
This plugin doesn't require any specific configuration, but you can include its error codes in your Flake8 configuration file to disable or enable specific checks:
```ini
[flake8]
extend-ignore = MLL001, MLL002, MLL003, MLL004
```
## Contributing
Contributions, issues, and feature requests are welcome! Please feel free to submit a pull request or open an issue.
## License
This plugin is licensed under the MIT License.
Raw data
{
"_id": null,
"home_page": "https://github.com/hanhwanglim/module-level-lint",
"name": "module-level-lint",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9,<4.0",
"maintainer_email": "",
"keywords": "flake8,lint",
"author": "Han Hwang Lim",
"author_email": "hanhwanglim@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b9/2d/f8f81f025ff228cb0f98ea7a52ffa75b95b825718519b81ca0b615ff1068/module_level_lint-0.2.1.tar.gz",
"platform": null,
"description": "# Module Level Lint\n\nA Flake8 plugin to enforce code quality by checking module level docstrings, future-imports, and module level dunders as specified in [PEP 8](https://peps.python.org/pep-0008/#module-level-dunder-names)\n\n## Installation\n\nYou can install this plugin via pip:\n\n```bash\npip install module-level-lint\n```\n\n## Usage\n\nAfter installation, you can use this plugin with the `flake8` command. Here's how to run it:\n\n```bash\nflake8 [path]\n```\n\nTo show only module level lint errors, run:\n\n```bash\nflake8 --select MLL [path]\n```\n\nTo show only specific errors\n\n```bash\nflake8 --select MLL001,MLL002 [path]\n```\n\nTo apply formatting\n\n```bash\nflake8 --select MLL [path] --fix\n```\n\n## Features\n\n### Lint\n\n#### Module Docstring Check: Ensure that your docstrings are always at the top of the file\n\n- Linting Error: **MLL001**\n\nExample:\n\n```python\nimport random\n\n# Bad: Module docstring is not at the top of the file\n\"\"\"This is a docstring\"\"\"\n\ndef foo():\n pass\n```\n\n```python\n# Good: Docstring present at the top of the file\n\"\"\" This is a docstring. \"\"\"\n\ndef foo():\n pass\n```\n\n#### Future-Imports Check: Ensure that future-imports are always at the top after module docstrings\n\n- Linting Error: **MLL002**\n\nExample:\n\n```python\nimport random\n\n# Bad: Future-imports is not at the top of the file\nfrom __future__ import print_function\n```\n\n```python\n# Good: Future-imports is at the top of the file\nfrom __future__ import division\n\nimport random\n```\n\n- Linting Error: **MLL003**\n\nExample:\n\n```python\nfrom __future__ import print_function\n\n# Bad: Docstring is not at the top of the file\n\"\"\"This is a docstring.\"\"\"\n```\n\n```python\n\"\"\"This is a docstring.\"\"\"\n\n# Good: Future-imports is at the top of the file after docstring\nfrom __future__ import division\n```\n\n#### Module-Level Dunders: Ensure that module level dunders are always at the top after future-imports or docstrings\n\n- Linting Error: **MLL004**\n\nExample:\n\n```python\nimport random\n\n# Bad: Module level dunder after imports\n__all__ = [\"foo\"]\n\ndef foo():\n pass\n```\n\n```python\n# Bad: Module level dunder before docstring\n__all__ = [\"foo\"]\n\n\"\"\"This is a docstring\"\"\"\n\ndef foo():\n pass\n```\n\n```python\ndef foo():\n pass\n\n# Bad: Module level dunder after code\n__all__ = [\"foo\"]\n```\n\n```python\n# Good: Module level dunder at the top of the file\n__all__ = [\"foo\"]\n\ndef foo():\n pass\n```\n\n### Format\n\nWith the `--fix` flag, this plugin will try to format the files that have no rule violations. It will fix the newlines in the following format:\n\n```python\n\"\"\"Docstring goes here\"\"\" # An empty line after docstrings\n\nfrom __future__ import annotations # An empty line after future imports\n\n__all__ = [\"foo\"] # An empty line after module dunders\n\nimport random # Rest of the code\n\n\ndef foo():\n return random.randint(1, 10)\n```\n\n## Configuration\n\nThis plugin doesn't require any specific configuration, but you can include its error codes in your Flake8 configuration file to disable or enable specific checks:\n\n```ini\n[flake8]\nextend-ignore = MLL001, MLL002, MLL003, MLL004\n```\n\n## Contributing\n\nContributions, issues, and feature requests are welcome! Please feel free to submit a pull request or open an issue.\n\n## License\n\nThis plugin is licensed under the MIT License.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Flake8 plugin to checking module level docstrings, future-imports, and dunders as specified in PEP 8",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/hanhwanglim/module-level-lint",
"Repository": "https://github.com/hanhwanglim/module-level-lint"
},
"split_keywords": [
"flake8",
"lint"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "da37689161c098616823a559c7ee0cc01f1582424db48042475fca172d07e451",
"md5": "a8836d2fd50ccbe0aebf01dc768d373b",
"sha256": "db1e1568ab19c088e3fb4acd69089c0c69adf573ecfa2cf0f763420795e10e3b"
},
"downloads": -1,
"filename": "module_level_lint-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8836d2fd50ccbe0aebf01dc768d373b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9,<4.0",
"size": 6612,
"upload_time": "2024-01-03T12:14:29",
"upload_time_iso_8601": "2024-01-03T12:14:29.997093Z",
"url": "https://files.pythonhosted.org/packages/da/37/689161c098616823a559c7ee0cc01f1582424db48042475fca172d07e451/module_level_lint-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b92df8f81f025ff228cb0f98ea7a52ffa75b95b825718519b81ca0b615ff1068",
"md5": "7a04f94fcedfc1e37cc4cee02578d201",
"sha256": "e7cf0adddf38a6154e426fe9f69cf7647a5b443766250791ca580a2950066708"
},
"downloads": -1,
"filename": "module_level_lint-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "7a04f94fcedfc1e37cc4cee02578d201",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9,<4.0",
"size": 4878,
"upload_time": "2024-01-03T12:14:31",
"upload_time_iso_8601": "2024-01-03T12:14:31.798367Z",
"url": "https://files.pythonhosted.org/packages/b9/2d/f8f81f025ff228cb0f98ea7a52ffa75b95b825718519b81ca0b615ff1068/module_level_lint-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-03 12:14:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hanhwanglim",
"github_project": "module-level-lint",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "module-level-lint"
}
JSON
