API: better use of Python properties

David Baumgold 10 years ago 0

The Python API should use the "property" function (http://docs.python.org/library/functions.html#property) wherever possible to make accessing and setting information about ST2's current state more seamless and Pythonic. This will make it even easier to write more and better plugins, and since it's a backwards-incompatible change, the time to make it is *now*, while ST2 is still in alpha/beta state.

All methods that take no arguments and exist only to return information should be decorated with "@property" so that other functions don't need to use parentheses to call the method. Some examples of methods that could use this treatment: sublime.windows(), sublime.version(), view.id(), view.file_name(), view.is_dirty(), view.settings(), region.size(), region.empty(), window.id(), window.views(), window.active_group(), etc. This allows for easier chaining: in the context of a plugin, it would be nice to refer to self.view.window.folders[i], instead of self.view.window().folders()[i].

Some objects have a pair of getter/setter methods: for example, view.name() and view.set_name(name). The "property" function allows you to combine these into one property, so that plugin writers can find out the name of the view by accessing view.name and set the name of the view by assigning a string to view.name (like so: view.name = "my view"). This is much more readable and Pythonic than having a separate method just to do assignment.