Provide non editor-centric APIs

[niqodea]

Is your feature request related to a problem? Please describe. I would like to write a CLI wrapper for the rope library that is easy to use as a command line user. On the other hand, many Rope's APIs are tailored to be easy to use in the context of editors. In particular, the constructor of the Move objects identify symbols within a python file using the byte offset of the symbol within that file, which is an information that is easy to retrieve by inspecting the cursor of the editor, but awkward to provide as a CLI user. This editor-centric API makes it especially challenging to develop a CLI wrapper for Rope.

Describe the solution you'd like It would be great if MoveMethod and MoveGlobal offered an alternative way to identify the symbol to move with something easy to input from the CLI instead of offset (for example, they could use resource + name). This change should be feasible, as the offset is not stored as a field in the Move object, but instead only used to retrieve other object fields. Perhaps it could make sense to lift the logic handling the offset in a factory function outside of __init__ and allow the user to inject all object fields in the constructor for finer control if needed.

Describe alternatives you've considered I researched other attempts at wrapping rope in a CLI and stumbled upon ropecli. By looking at the code, it looks like the author encountered the same problem and had to implement several layer of reverse engineering to retrieve the offset starting from the name of the symbol to move. Moreover, it is not clear whether the implemented retrieval of the offset is precise or best-effort.

Additional context I am writing ropify, a CLI wrapper for Rope. It would be cool to make this CLI viable for command line users as well.

[lieryan]

Hi @niqodea, thanks for writing this issue. Having a non-editor-centric API is a fairly common request, so I'd be open to pull requests implementing this. Would you like to take a stab at implementing this? I think you probably have a better idea of how a non-editor centric API should work than I do anyway.

If I understand correctly, this should be possible by exposing create_move(..., name: PyName) in the API as well as the class constructors. Currently, create_move() uses eval_location() to get the pyname, but for a non-editor API, you'll need get a PyName by name, which can be done by using the module/scope interface like so:

In [22]: eval_location(mod, 6425 + 10) # offset of `class Project()` inside the file
Out[22]: <rope.base.pynamesdef.DefinedName at 0x7f730b1e3050>

In [26]: dn = proj.get_module("rope.base.project")["Project"]
Out[26]: <rope.base.pynamesdef.DefinedName at 0x7f730b1e3050>

So once the pyname parameter is exposed, you will be able to do something like so:

create_move(proj, proj.get_module("rope.base.project").resource, name=proj.get_module("rope.base.project")["Project"])

This will require changing the create_move(), MoveGlobal, and MoveMethod.

Aside, do you want to add ropify to the Wiki page?

[niqodea]

Thank you for the guidance! I will be happy to contribute when I have time.

Aside, do you want to add ropify to the Wiki page?

With pleasure!