Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
# **Upcoming release**

- #122 Document Introduce Parameter with an executable API example and default-value caveats.

- #859 Fix `find_definition`/Rename not resolving `async def` methods called via `self` (@gadievron)
- #895 patchedast Starred and keyword now consumes their syntactically expected and ** (@lieryan)
- #896 patchedast cleanup and refactoring (@lieryan)
Expand Down
61 changes: 60 additions & 1 deletion docs/library.rst
Original file line number Diff line number Diff line change
Expand Up @@ -584,7 +584,7 @@ folder.
it.

* ``rope.refactor.introduce_parameter``:
Introduce a parameter in a function.
Introduce a parameter in a function. See `Introduce Parameter`_ below.

* ``rope.refactor.encapsulate_field``:
Generate a getter/setter for a field and changes its occurrences to
Expand Down Expand Up @@ -662,6 +662,65 @@ Using rename refactoring:
>>> project.close()


Introduce Parameter
-------------------

``IntroduceParameter(project, resource, offset)`` replaces references to a
selected name or attribute inside a function with a new parameter. Its
default value is the original expression, so existing calls need not change.
``offset`` is a character offset inside the reference in the function body,
not the variable's definition. ``get_changes(new_parameter)`` prepares a
change set; apply it with ``project.do()`` after reviewing its description.

This complete example uses an isolated temporary project:

.. code-block:: python

from tempfile import TemporaryDirectory
from textwrap import dedent

from rope.base.project import Project
from rope.refactor.introduce_parameter import IntroduceParameter

with TemporaryDirectory() as directory:
project = Project(directory, ropefolder=None)
try:
module = project.root.create_file("example.py")
source = dedent("""\
greeting = "hello"
def greet():
return greeting
""")
module.write(source)
offset = source.rindex("greeting")
refactoring = IntroduceParameter(project, module, offset)
changes = refactoring.get_changes("message")
assert module.read() == source # No files have changed yet.
project.do(changes)
assert module.read() == dedent("""\
greeting = "hello"
def greet(message=greeting):
return message
""")
project.history.undo()
assert module.read() == source
finally:
project.close()

Occurrences are found by the object they reference, rather than by textual
equality alone. The selection must resolve to a name or attribute inside a
function; this is not a general operation on an arbitrary selected range of
text. An unresolved name or a selection outside a function raises
``rope.base.exceptions.RefactoringError``.

Review the generated default carefully. Python evaluates defaults when the
function is defined, and mutable default objects are shared between calls.
An expression that depends on a local variable or another parameter may not
be available there. Rope does not prove that these changes preserve runtime
behavior. Choose a fresh, valid parameter name and check the resulting
signature before applying the change.


Restructuring
-------------

Expand Down
31 changes: 31 additions & 0 deletions docs/overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,37 @@ This section shows some random refactorings that you can perform using
rope.


Introducing A Parameter
-----------------------

Use Introduce Parameter to replace a name or attribute used inside a function
with a new optional parameter. For example, select ``greeting`` in the body
of this function:

.. code-block:: python

greeting = "hello"
def greet():
return greeting

Introducing a parameter named ``message`` produces:

.. code-block:: python

greeting = "hello"
def greet(message=greeting):
return message

Existing calls such as ``greet()`` remain valid, and callers can now pass
``greet("goodbye")``. The default is evaluated at function definition time,
so later changes to the global ``greeting`` no longer affect ``greet()``.
Mutable defaults are also shared between calls. Review these consequences
before applying the refactoring.

Availability in an editor depends on its Rope integration. See
:ref:`library:Introduce Parameter` for the library API and a runnable example.


Renaming Attributes
-------------------

Expand Down
Loading