Refactoring & Code Transformations¶
BetterPy provides 10 refactoring intentions and actions — from populating function arguments to extracting protocols and converting between code patterns.
Arguments¶
Make parameter optional¶
Convert a required function parameter into an optional parameter without manually editing the signature. BetterPy adds | None to its type annotation and supplies a None default when no default exists. The function body stays unchanged.
How to invoke¶
Place the caret on a required parameter and use ⌥⏎ / Alt+Enter -> "BetterPy: Make optional".
Example¶
becomes:
What it supports¶
- Annotated function and method parameters, preserving an existing default value.
- Annotated attributes.
- Parameters in regular Python source files in your project.
- Existing annotations and surrounding formatting.
What it deliberately avoids¶
- Untyped parameters and annotations that already accept
None. - Parameters whose position cannot accept a default without changing Python's required-parameter ordering rules.
*args,**kwargs, and synthetic parameters.- Files outside your own project sources.
Notes¶
- Python 3.10 and later use
T | None; older Python versions usetyping.Optional[T], adding an import when needed. - Review how the function handles
None: the intention does not update its body. - The feature is gated by the Make parameter optional setting under Settings | BetterPy | Refactoring & code transformations | Arguments.
Make parameter mandatory¶
Convert an optional function parameter back into a required parameter. BetterPy removes the default value from the signature so callers must provide an argument explicitly.
How to invoke¶
Place the caret on an optional parameter and use ⌥⏎ / Alt+Enter -> "BetterPy: Make mandatory".
Example¶
becomes:
What it supports¶
- Function and method parameters with simple default values.
- Typed and untyped parameters.
- Regular project Python files.
- Keeping annotations, decorators, and the surrounding function body unchanged.
What it deliberately avoids¶
- Parameters without a default value.
*args,**kwargs, and generated parameters.- Changes to call sites. After applying the intention, inspect callers and update any that relied on the removed default.
- Files outside your own project sources.
Notes¶
- This is a signature-editing intention, not a full call-site migration.
- The feature is gated by the Make parameter mandatory setting under Settings | BetterPy | Refactoring & code transformations | Arguments.
Top-level extract function¶
Extracts selected module-level Python statements into a new function while keeping the code explicit about inputs and outputs.
Before¶
After¶
def calculate_discounted_total(subtotal, tax, discount):
raw_total = subtotal + tax
discounted_total = raw_total - discount
return discounted_total
discounted_total = calculate_discounted_total(subtotal, tax, discount)
print(discounted_total)
The action is available through PyCharm's extract method refactoring when the current selection is at module level and can be represented as a standalone function.
Extract function to scope¶
BetterPy's Extract Function to Scope refactoring moves selected Python code into a named helper and replaces the selection with a call. The helper and call are applied as one undoable change.
MCP tools¶
analyze_extract_function_to_scope accepts a project file path and one-based selection lines and columns. It reports whether extraction is supported, a conflict code when it is not, inferred inputs and outputs, available destination IDs, and a modification stamp. It does not edit the file.
extract_function_to_scope takes the same selection, a destination ID from analysis, and the new function name. It applies the refactoring without a dialog and returns the updated file text. Pass the analysis modification stamp as expectedModificationStamp to reject an edit if the file changed between calls. Both tools are available only when this feature is included in the build and enabled in BetterPy settings.
Supported destinations¶
- Current function inserts a local helper before the selected code.
- An enclosing function inserts the helper into a containing function that can access the values needed at the call site.
- Class inserts a
@staticmethodhelper into the class that directly contains the selected method. The option is available in instance, class, and static methods, including methods of nested or function-local classes. Calls use__class__to refer to the class where the method was defined;selforclsis passed as an ordinary input when the selected code uses it. Nested functions inside a method do not get a class destination. - Module creates a module-level helper.
Direct executable statements and expressions at module level can also be selected. Only the module destination is available; selections inside a module-level if, loop, or other compound suite are rejected. The helper is inserted after the module docstring and any from __future__ imports. When extracting code from a function, the module helper is placed before the file-level construct containing that function. Module globals stay live and are resolved when the helper runs. Every selected module binding that must remain visible after extraction is returned to the module.
For module selections, a read-only use of a global after a selected call keeps that live lookup. A read-modify-write of the same global is rejected when a statically resolved call in the selection can mutate it. In the original code, the read happens after the call; passing the global as a helper input would evaluate it before the helper starts and could use a stale value. Same-file wrapper calls and lambda aliases are followed when they can be resolved.
Inputs are passed as helper parameters. Values assigned by the selection and used afterward are returned and assigned at the call site. For example, extracting the assignment below to the module as make_result preserves result for the following return:
def make_result(value):
result = value + 1
return result
def calculate(value):
result = make_result(value)
return result
Safety boundaries¶
Unsupported selections and destination conflicts leave the file unchanged and do not record an applied refactoring. Extraction is rejected when a selection is partial, crosses executable scopes, or appears in a function header or decorator. Function and module docstrings cannot be selected. Module-level imports, function or class definitions, and annotated assignments cannot be moved into helpers. Import, global/nonlocal, and assignment-expression bindings are rejected when moving them would change which scope owns the name.
Selections with a return, break, or continue that would escape the new helper are rejected. Module outputs assigned only inside a branch or loop are rejected because the helper could not return a value on every path. Zero-argument super() is rejected for every destination. Async-generator delegation is unsupported; supported await and whole-statement synchronous generator selections preserve their async or generator behavior.
Extraction is rejected when selected writes are read by an existing closure or callback invoked within the selection, including callbacks reached through statically resolved same-file wrappers or lambda aliases. Moving those writes into a helper would hide them from the original binding until the helper returns. Augmented assignments count as writes for this check.
Moving code that contains a class-mangled private name outside its original class scope is rejected. A helper name beginning with __ is also rejected when Python would mangle its definition and call differently. Local helpers that stay in the same class scope remain available.
Class extraction is rejected when the containing method declares global or nonlocal __class__, when staticmethod is shadowed in a scope used by the class body, or when the class or a resolved base class explicitly declares a metaclass= argument. Class helper names conflict with direct or inherited runtime member names, including names Python creates through private-name mangling, and with known __slots__ entries. A dynamic __slots__ declaration that cannot be read as a literal also blocks the class destination. Class-name shadowing inside the method and same-named overrides in subclasses are safe because calls are qualified through __class__.
Python normalizes identifiers using NFKC. Helper-name validation and collision checks use that normalized spelling, so visually distinct spellings that Python treats as the same identifier conflict before editing.
Cross-file extraction is not supported. The existing Extract Function and Top-level Extract Function actions remain independent and are unchanged when this feature is disabled.
Parameter Object¶
Parameter object refactoring¶
Introduce Parameter Object turns a long parameter list into a single object parameter. Inline Parameter Object performs the reverse transformation when the object no longer carries enough value to stay separate.
How to invoke¶
- Place the caret inside a function and use Refactor | BetterPy: Introduce Parameter Object....
- Place the caret on a function that takes an inlineable parameter object and use Refactor | BetterPy: Inline Parameter Object....
- When the gutter feature is enabled, a parameter-object gutter icon can start the introduce flow on eligible functions.
Introduce example¶
can become:
from dataclasses import dataclass
@dataclass
class CreateOrderParams:
customer_id: int
product_id: str
quantity: int
urgent: bool
def create_order(params: CreateOrderParams):
...
Call sites are rewritten to construct the parameter object:
Inline example¶
@dataclass
class SearchParams:
query: str
limit: int
def search(params: SearchParams):
return client.search(params.query, params.limit)
can become:
What it supports¶
- Dataclass,
NamedTuple,TypedDict,pydantic.BaseModel, andattrsparameter objects. - Per-invocation class name, parameter name, and field selection.
frozen,slots, andkw_onlyoptions where the selected base type supports them.- Rewriting function bodies and known call sites, including cross-file and inheritance-aware call sites.
- Preserving type annotations, scalar defaults, and supported mutable defaults.
- Inline refactoring for recognized dataclass,
NamedTuple,TypedDict, Pydantic, andattrsshapes.
What it deliberately avoids¶
- Functions whose parameters or usages cannot be rewritten predictably.
- Highly dynamic call sites where argument mapping is ambiguous.
- Parameter objects that are not recognized as a supported shape.
- Blindly deleting object classes when usages remain outside the refactoring scope.
Calls that unpack extracted arguments with *args or **kwargs are rejected rather than partially rewritten. Review custom decorators and string-based parameter documentation after refactoring; BetterPy intentionally does not rewrite arbitrary strings or comments.
Notes¶
- The feature is incubating. Preview the refactoring and review the changed files before committing the result.
- The feature is gated by the Parameter object refactoring setting under Settings | BetterPy | Refactoring & code transformations | Parameter Object.
Parameter object MCP tool¶
The Parameter object MCP tool exposes BetterPy's parameter-object refactoring flow to MCP-capable assistants. It lets an assistant request the same IDE-backed transformation instead of trying to rewrite Python source text on its own.
How to use¶
Connect an MCP client to the IDE, then ask it to introduce or inline a parameter object for a specific function. The tool runs inside the IDE context, so it can use project PSI, inspections, and refactoring infrastructure.
Example request¶
Introduce a parameter object for create_order in orders/service.py.
Use a dataclass and update call sites.
The assistant can route that request to BetterPy's MCP tool. The IDE performs the refactoring and returns the result through the MCP session.
What it supports¶
- Assistant-triggered introduce parameter object operations.
- The same target validation used by the interactive refactoring.
- Project-aware source edits rather than standalone text replacement.
- Respecting the parameter-object feature settings configured in the IDE.
What it deliberately avoids¶
- Running when the Parameter object refactoring feature is disabled.
- Applying transformations to unsupported or ambiguous function signatures.
- Replacing human review. You should still inspect the produced diff.
Notes¶
- This feature is useful when you want an assistant to orchestrate refactoring while the IDE remains responsible for correctness-sensitive edits.
- The feature is gated by the Parameter object MCP tool setting under Settings | BetterPy | Refactoring & code transformations | Parameter Object.
Code Transformations¶
Change visibility¶
Toggle a Python symbol between public and private naming without manually renaming the declaration and every call site. BetterPy reuses the IntelliJ rename refactoring, so all references in the project are updated together with the declaration.
How to invoke¶
Place the caret on the name of a function, class, or top-level/class-level variable, then ⌥⏎ / Alt+Enter → "Change visibility: make private" or "Change visibility: make public". The intention text adapts to the current name: - A name without a leading underscore offers "make private" and renames name → _name. - A name starting with _ offers "make public" and strips leading underscores (_name → name, __name → name).
Example¶
What it supports¶
- Functions, classes, and assignment targets (module-level and class-level attributes).
- Updates every reference in the project via the standard rename refactoring, so imports and qualified usages stay in sync.
- Works on names with one or more leading underscores; making a name public removes all of them.
- When invoked on a method that is also defined in a super class or overridden in subclasses, BetterPy asks before changing the rest of the hierarchy. The dialog lists the affected super classes and subclasses and lets you choose between "Rename in Hierarchy", "Rename Only This Method", or "Cancel".
What it deliberately avoids¶
- Dunder names such as
__init__or__call__— these have language-defined semantics. - Pytest test functions (
test_*) and test classes (Test*), since renaming them would hide them from collection. - Symbols defined in
conftest.py, where the_prefix would change pytest fixture discovery. - Names whose target form would collide with a Python reserved keyword.
- Files outside your own project (library or stub sources).
Notes¶
- The intention is gated by the Change visibility setting under Settings | BetterPy | Refactoring & code transformations | Code Transformations and is enabled by default.
- Because the rename runs through
RenameProcessor, conflicts (for example an existing symbol with the target name) are surfaced through the standard refactoring conflict dialog rather than silently overwriting code.
Inline bare tuple return¶
Inline functions with one bare tuple return while preserving tuple grouping and avoiding a synthetic result variable.
How to invoke: Place the caret on the function or a call site and run the standard Inline refactoring (⌥⌘N / Ctrl+Alt+N).
Tip
Only module-level functions with one unconditional bare tuple return are eligible. PyCharm's regular argument handling, import updates, and declaration-removal options remain available.
Dict access conversion¶
This feature bundles three related intentions that help you switch between the most common dictionary lookup styles depending on whether you want terse code, explicit fallback handling, or exception-driven control flow.
All three intentions only activate for expressions BetterPy can verify as mappings. That keeps the feature from appearing on unrelated subscription syntax such as lists, tuples, or arbitrary objects that just happen to define a get() method.
Convert bracket access to .get()¶
How to invoke: ⌥⏎ / Alt+Enter on mapping[key] → "BetterPy: Replace 'dict[key]' with 'dict.get(key)'"
Use this when a missing key should quietly yield None instead of raising KeyError.
becomes:
What it supports¶
- Ordinary dictionary and mapping lookups such as
payload["id"]. - Variable keys like
payload[key_name]. - Tuple keys, including the comma form
mapping[a, b], which is rewritten tomapping.get((a, b)). - Complex mapping expressions such as
factory().cache["users"]. - Inline comments and spacing inside the brackets; BetterPy preserves the bracket contents instead of rebuilding them from scratch.
What it deliberately avoids¶
- Assignment targets like
mapping[key] = value. - Deletions such as
del mapping[key]. - Augmented assignments like
mapping[key] += 1. - Non-mapping operands such as lists.
Those cases are skipped because .get() changes the meaning: it reads a value, but it cannot stand in for write/delete syntax.
Convert .get() to bracket access¶
How to invoke: ⌥⏎ / Alt+Enter on mapping.get(key) → "BetterPy: Replace 'dict.get(key)' with 'dict[key]'"
Use this when a key is expected to exist and surfacing KeyError is preferable to silently returning None.
becomes:
What it supports¶
- One-argument
.get()calls. - Positional keys such as
mapping.get(key). - Keyword style calls like
mapping.get(key=name), which becomemapping[name].
What it deliberately avoids¶
.get()calls with a default, for examplemapping.get("timeout", 30).- Calls with zero arguments or more than one effective argument.
- Calls on non-mapping values.
- Shadowed or unrelated
getcall sites where BetterPy cannot prove the qualifier is a mapping lookup.
This restriction matters because mapping.get(key, default) is not equivalent to mapping[key]; replacing it would drop the fallback value.
Convert .get(..., default) to try / except KeyError¶
How to invoke: ⌥⏎ / Alt+Enter on mapping.get(key, default) used as a full assignment or return value → "BetterPy: Replace 'dict.get(key, default)' with try/except KeyError"
Use this when you want explicit exception-based control flow while keeping the same fallback result.
becomes:
It also works for direct returns:
becomes:
What it supports¶
- Full assignment statements with exactly one target.
- Full return statements.
- Positional and keyword forms for
keyanddefault. - Safe default expressions such as literals, constants, references, and simple constant-style subscriptions.
What it deliberately avoids¶
- Nested or partial expressions like
foo(payload.get("name", "unknown")). - Assignments with multiple targets.
- Calls without a default value.
- Defaults that may have side effects or are expensive to duplicate.
The generated try block repeats the lookup once and the fallback once, so BetterPy only offers the intention when that duplication is predictable and safe.
Convert try / except KeyError to .get()¶
How to invoke: ⌥⏎ / Alt+Enter inside a qualifying try block → "BetterPy: Replace try-except with dict.get"
Use this when explicit exception handling is unnecessary and a compact lookup reads better.
becomes:
It also supports the common initialization-plus-pass pattern:
becomes:
What it supports¶
- A single
except KeyErrorclause. - A
tryblock containing exactly one statement. - Assignment or return forms.
- Fallbacks expressed as a literal or simple reference.
- Tuple keys and parenthesized complex mapping expressions.
What it deliberately avoids¶
trystatements withelseorfinallyblocks.- Multiple
exceptclauses. - Nested subscriptions such as
mapping[a][b], where.get()would not preserve the same failure boundary. - Complex fallback expressions.
These constraints ensure the shorter .get() form stays semantically equivalent to the original exception-handling code.
When to prefer each form¶
- Use
mapping[key]when the key is required and a missing value should fail loudly. - Use
mapping.get(key)when absence is expected andNoneis a meaningful signal. - Use
mapping.get(key, default)when you want a compact fallback. - Use
try/except KeyErrorwhen the fallback path needs to be visually explicit or is about to grow into more than a single expression.
Because BetterPy supports moving in both directions, you can start with the clearest form for the current situation and change it later without rewriting the statement by hand.
Toggle enum member value¶
Toggle an enum member reference between the enum member object and its literal value. This is useful when a call site or assertion needs to switch between comparing enum members and comparing their serialized values.
How to invoke¶
Place the caret on an enum member reference or on a literal value with an expected enum type, then use ⌥⏎ / Alt+Enter -> "BetterPy: Toggle enum member / value".
Example¶
becomes:
Running the intention on "red" changes it back to Color.RED when the expression has an expected Color type, such as an annotated assignment or annotated function parameter.
What it supports¶
- Members of
Enum,IntEnum,StrEnum,Flag, andIntFlagclasses. - Qualified enum member references such as
Color.RED. - Literal values whose expected type resolves to an enum class.
- Enum references used inside expressions, assignments, and comparisons.
What it deliberately avoids¶
- Bare names such as
REDwhere the enum class is not part of the reference. - Literal values without an expected enum type annotation.
- Attributes on non-enum classes.
- Longer attribute chains such as
Color.RED.nameorColor.RED.custom. - Files outside your own project sources.
Notes¶
- The intention changes call-site references only. It does not rewrite enum member declarations.
- The feature is gated by the Toggle enum member value setting under Settings | BetterPy | Refactoring & code transformations | Type Editing.