Code Quality & Safety¶

This category covers BetterPy features for catching problems earlier, tightening feedback loops, and making Python code easier to inspect and fix.

Code Inspections¶

Constant should be Final inspection¶

Report module-level constants that look immutable but are missing a Final[...] annotation. The quick-fix adds the annotation and inserts the required import so the declaration becomes explicit to readers and type checkers.

How to invoke¶

Enable the inspection and place the caret on a reported constant, then use ⌥⏎ / Alt+Enter → "Wrap constant type in Final".

Example¶

API_VERSION = "v1"

becomes:

from typing import Final

API_VERSION: Final[str] = "v1"

What it supports¶

• Module-level constants with a single simple target such as NAME = value.
• Literal values, inferred class types, unions, and collection types when building the Final[...] annotation.
• Existing typing_extensions.Final imports.
• None initializers, which become Final[None].
• Imported module qualification when an inferred type would otherwise be ambiguous.

What it deliberately avoids¶

• Multi-target assignments such as A = B = 1.
• Qualified targets such as obj.NAME = value.
• Constants inside enum classes.
• Assignments already annotated with Final.
• Typing special forms such as TypeVar, ParamSpec, TypeVarTuple, and NewType.

Notes¶

• The inspection only runs on your own project files, not library or stub sources.
• The feature is gated by the Constant should be Final inspection setting under Settings | BetterPy | Code Quality & Safety | Code Inspections and is enabled by default.
• The quick-fix preserves the original assigned expression and reformats the final statement through the IDE code style manager.

Suppress missing docstrings on overloads¶

Suppresses PyCharm's missing docstring inspection for @overload signatures while keeping the implementation subject to the normal docstring rule.

from typing import overload

@overload
def parse(value: str) -> int: ...

@overload
def parse(value: bytes) -> int: ...

def parse(value: str | bytes) -> int:
    """Parse a numeric value."""
    return int(value)

# The overload signatures are not flagged for missing docstrings.
# The implementation still needs its own docstring.

Notes¶

• Only missing-docstring inspection results on overload signatures are suppressed.
• Ordinary functions and undocumented implementations continue to be reported.
• The feature is gated by the Suppress missing docstrings on overloads setting under Settings | BetterPy | Code Quality & Safety | Code Inspections.

Shadowing stdlib module inspection¶

Reports project modules that shadow Python standard library modules, such as random.py, logging.py, or json.py.

Python searches the script or current directory before the standard library. A project file with the same name as a standard library module can make ordinary application code, dependencies, tests, and debugging sessions import the project file instead of the intended stdlib module.

How to invoke¶

Enable the inspection, place the caret on the highlighted module name, then use ⌥⏎ / Alt+Enter -> "Rename file".

Example¶

# random.py
def pick(items):
    return items[0]

Rename the file to a non-stdlib name:

# project_random.py
def pick(items):
    return items[0]

What it supports¶

• Project Python files whose base name matches a Python standard library module.
• The standard __main__.py entrypoint, which is ignored.
• Rename confirmation when a file is renamed to a standard library module name.

Notes¶

• The inspection only runs on your own project files, not library or stub sources.
• The feature is gated by the File name shadows a Python standard library module setting under Settings | BetterPy | Code Quality & Safety | Code Inspections and is enabled by default.

Import Inspections¶

Private module import inspection¶

This inspection reports imports from private implementation modules when the imported symbol is already available from the public package API.

Example¶

from package._internal import User

If package.__all__ exports User, BetterPy suggests importing from package instead:

from package import User

When the symbol is not exported yet, the inspection can also make the symbol public by updating the package __all__, adding the re-export import, and rewriting matching private imports outside that package.

Notes¶

• The inspection helps keep callers on public package APIs.
• Imports inside the exporting package are left alone, so implementation modules can still use private package internals.
• It is gated by the Private module import inspection setting under Settings | BetterPy | Code Quality & Safety | Import Inspections.

Filtering¶

Usage filtering¶

Find Usages often mixes runtime references with references that are useful only in specific review modes. This feature adds usage-view filters that let you hide type-only references and test-source references without changing the underlying search result set.

Options¶

• Hide type annotation usages removes references that occur inside type hints, including function parameters, return types, variable annotations, and common generic type expressions.
• Hide test-source usages removes references from files marked as test sources and from pytest-style test files detected by BetterPy's pytest naming rules.

How to invoke¶

Run Find Usages (⌥F7 / Alt+F7) on a Python symbol, then use the BetterPy filter icons in the usage view toolbar:

• BetterPy: Show Type Annotations
• BetterPy: Show Test Usages

Example¶

# src/orders.py
class Order:
    ...


def submit(order: Order) -> None:
    ...


current = Order()
submit(current)


# tests/test_orders.py
from orders import Order

Order()

When type annotation usages are hidden, the order: Order annotation is removed from the usage view while the constructor call remains visible. When test-source usages are hidden, the reference in tests/test_orders.py is removed while production references remain visible.

What it deliberately avoids¶

• Rewriting or deleting annotations.
• Reclassifying source roots or changing project settings.
• Treating imports as type-only or test-only without usage context.
• Hiding production usages that happen to call test helper functions.

Notes¶

• The master feature is gated by the Usage filtering setting under Settings | BetterPy | Code Quality & Safety | Find Usages.
• The two filter options are shown under the master setting and can be toggled independently.