diff --git a/CHANGELOG.md b/CHANGELOG.md index 88e4748e2..37d0aa082 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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) diff --git a/docs/library.rst b/docs/library.rst index 6a62c3e00..94d1e5d8e 100644 --- a/docs/library.rst +++ b/docs/library.rst @@ -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 @@ -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 ------------- diff --git a/docs/overview.rst b/docs/overview.rst index 01076ade5..a3aa012b4 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -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 -------------------