Style, Lint, and Format Python Code: All in One View

Last updated on 2025-09-18 | Edit this page

Grammar and spelling are important in writing academic and technical articles because they ensure clarity, precision, and professionalism in communication. Good grammar and correct spelling eliminate ambiguities and prevent misunderstandings, enabling readers to clearly grasp the intended message without distraction or confusion. This is essential for the credibility and readability of scholarly work, impacting how the article is perceived by peers and reviewers.

Specifically:

Correct spelling supports effective communication by eliminating semantic ambiguities and lexical/syntactic errors, which helps readers understand the content easily and accurately.
Grammar ensures that sentence structure and language conventions are properly followed, making the argument logically coherent and the writing flow smoothly. This enhances the reader’s ability to follow complex ideas and scientific reasoning.
Poor grammar and spelling can undermine the perceived quality of the research, reduce the article’s impact, and may lead to rejection from journals or negative reviewer assessments.
Mastery of grammar and spelling demonstrates attention to detail and academic rigor, which are vital in scholarly publishing.

Just as grammar and spelling are essential for clear communication in journal and technical articles, proper spelling, consistent naming, and correct syntax in code are vital for clarity, functionality, maintainability, and teamwork in software development. Developers can accomplish well written Python code by adhering to Python’s style guide while using linter and formatter tools.

Content from Python Style Guide

Last updated on 2025-09-26 | Edit this page

The PEP 8 Style Guide for Python Code gives coding conventions for code layout, comments, naming, and other programming recommendations. The pep8.org website is another presentation of the style guide. By adhering to the Python style guide, developers can write consistent code that is readable and maintainable on small and large projects. Some of the major conventions suggested by the guide are demonstrated below but readers should review the PEP 8 guide for more information.

Indentation

Spaces (not tabs) are the preferred indentation method. Use 4 spaces per indentation level.

PYTHON

# Correct

for x in range(10):
    print("x is", i)

def sayhello():
    x = "Hello there"
    return x

# Wrong

for x in range(10):
  print("x is", x)

def sayhello():
  x = "Hello there"
  return x

Imports

Imports should be on separate lines except when using the from syntax. Imports are always put at the top of the file, just after any module comments and docstrings, and before module globals and constants.

PYTHON

# Correct

import numpy
import polars

from subprocess import Popen, PIPE

# Wrong

import numpy, polars

Imports should be grouped in the order shown below. An empty line should be placed between each group of imports.

Standard library imports
Third party imports
Local application/library specific imports

PYTHON

# Standard library

import os
import math

# Third party

import numpy as np
import matplotlib.pyplot as plt

# Local package

from mypackage.utils import sayhello

Wildcard imports such as from package import * should be avoided because it is unclear what is actually imported from the package. This confuses both human readers of the code as well as automated tools.

Documentation strings

Documentation strings, or docstrings, should be written for modules, functions, classes, and methods to describe the associated code. Several docstring styles exist such as the NumPy style and the Google style. The example below uses the Google docstring style.

PYTHON

def sayhello(x: str) -> str:
    """Create a greeting to say hello to someone.

    Args:
        x: Name of a person for the greeting.

    Returns:
        A greeting for the given name.
    """
    greeting = f"Hello {x}, how are you today?"
    return greeting

Naming conventions

Modules should have short lowercase names where underscores can be used to improve readability. Packages should also have short lowercase names but use of underscores is discouraged.

BASH

# Module names

downloader.py

file_downloader.py

PYTHON

# Package names

import mypackage

Class names should use the capitalized words (or CapWords, CamelCase) convention.

PYTHON

class Downloader:
    ...

dl = Downloader()

class FileDownloader:
    ...

file = FileDownloader()

Function and variable names should be lowercase with underscores to separate words for readability. This naming convention applies to methods on a class object too.

PYTHON

def hello(x):
    return f"Hello {x}"

def say_hello(x):
    y = f"Hello {x}"
    print(y)

Constants are usually defined at the module level and written in all capital letters.

PYTHON

# A module named example.py

import numpy as np
import pandas as pd

# Constants for this module
TOTAL = 89
API_URL = "https://mywebsite/api:8090"

Content from Linting Python Code

Last updated on 2025-09-26 | Edit this page

A code linter tool is a static code analysis program that automatically checks source code for errors, bugs, stylistic issues, and deviations from coding standards, all without executing the code. Linters help developers catch problems early by flagging questionable constructs, possible vulnerabilities, or code that doesn’t follow best practices.

Ruff is a highly performant linter specifically for Python code. It checks for errors, style issues, and deviations from best practices, and can automatically fix some issues. It is a direct replacement for tools like Flake8, isort, pydocstyle, pyupgrade, and autoflake. Ruff is rapidly becoming the standard Python linting choice due to its speed, breadth of features, and ease of integration. Consequently, Ruff is used in this episode to demonstrate various linting features for Python code.

Linting examples

Here is some poorly written Python code:

PYTHON

# bad_code.py

import os, sys   # multiple imports on one line

def add(x,y):    # missing whitespace after comma
    return x+ y  # inconsistent spacing

def unused_function():
    pass         # unused function

value = 42
print("The answer is: {}". format(value)) # space before format call

Next, run Ruff to check the code:

BASH

$ ruff check bad_code.py

Ruff will output the following errors and warnings about the code in the file:

OUTPUT

E401 [*] Multiple imports on one line
 --> bad_code.py:3:1
  |
1 | # bad_code.py
2 |
3 | import os, sys   # multiple imports on one line
  | ^^^^^^^^^^^^^^
4 |
5 | def add(x,y):    # missing whitespace after comma
  |
help: Split imports

F401 [*] `os` imported but unused
 --> bad_code.py:3:8
  |
1 | # bad_code.py
2 |
3 | import os, sys   # multiple imports on one line
  |        ^^
4 |
5 | def add(x,y):    # missing whitespace after comma
  |
help: Remove unused import

F401 [*] `sys` imported but unused
 --> bad_code.py:3:12
  |
1 | # bad_code.py
2 |
3 | import os, sys   # multiple imports on one line
  |            ^^^
4 |
5 | def add(x,y):    # missing whitespace after comma
  |
help: Remove unused import

Found 3 errors.
[*] 3 fixable with the `--fix` option.

Content from Formatting Python Code

Last updated on 2025-09-26 | Edit this page

A code formatter is a tool that automatically reformats source code according to a set of predefined style guidelines, ensuring consistency in indentation, line breaks, spacing, and other structural aspects of code. The primary goal is to enhance readability, maintain uniform code style across a project, and reduce the need for manual formatting by developers.

Ruff, originally known as a Python linter, also includes code formatting capabilities, allowing it to apply automatic style adjustments to Python source code. This means Ruff can handle both code linting (error and code quality checks) and code formatting (enforcing a consistent style), much like specialized Python formatters such as Black. Ruff’s formatter is designed to work very quickly due to its Rust implementation, making it efficient for large projects and continuous integration (CI) workflows.

Formatting examples

here

Content from Language Server Protocol

Last updated on 2025-09-26 | Edit this page

Stuff about language server protocol and how it relates to linting and formatting Python code.

Content from Continuous Integration

Last updated on 2025-09-26 | Edit this page

Stuff about using ruff for lint and format checks in CI.