module-level-lint

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

Installation

You can install this plugin via pip:

pip install module-level-lint

Usage

After installation, you can use this plugin with the flake8 command. Here's how to run it:

flake8 [path]

To show only module level lint errors, run:

flake8 --select MLL [path]

To show only specific errors

flake8 --select MLL001,MLL002 [path]

To apply formatting

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:

import random

# Bad: Module docstring is not at the top of the file
"""This is a docstring"""

def foo():
    pass

# 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:

import random

# Bad: Future-imports is not at the top of the file
from __future__ import print_function

# Good: Future-imports is at the top of the file
from __future__ import division

import random

• Linting Error: MLL003

Example:

from __future__ import print_function

# Bad: Docstring is not at the top of the file
"""This is a docstring."""

"""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:

import random

# Bad: Module level dunder after imports
__all__ = ["foo"]

def foo():
    pass

# Bad: Module level dunder before docstring
__all__ = ["foo"]

"""This is a docstring"""

def foo():
    pass

def foo():
    pass

# Bad: Module level dunder after code
__all__ = ["foo"]

# 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:

"""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:

[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.