awesome, this is a good explanation!

and you already removed needs_package and so on!

and it fits= really nice to use __init__.py in directory-based plugins for the already = used and your proposed new decorators (@kate.action, @kate.configPage, =E2= =80=A6): everything else (classes, datastructures, functions) is put in sub= modules, and in __init__.py, we just define a bunch of decorated wrapper fu= nctions around the datastructures which live in submodules.

2013/11= /16 Alex Turbov <i.zaufi@gmail.com>

Hi all, and especially = Python plugin developers

I'd like to share a brief info ab= out (even more) recent changes in Python plugins, so others get know thats = going on and be able to fix if smth wrong (still unfixed).

0) as you may know plugins now searched via trader client and des= cribed by a corresponding .desktop file w/ 'Kate/PythonPlugin' serv= ice type

1) default Python supposed to be version 3, so if you= r plugin is binilgual a property 'X-Python-2-Compatible=3Dtrue' mus= t be added to a .desktop file

2) if your plugin is Python2 only you have add also a 'X-Pyth= on-2-Only=3Dtrue'

3) to make some simple dependency checks= (from other python modules you plugin may use) add 'X-Python-Dependenc= ies=3D<dep>', where the <dep> is a string in format:

=C2=A0 "python-module-2-import [ | version-info ]".
=C2=A0 'version-info' is quite informal text to be displayed as a= tooltip over "broken" plugin in the manager's view.
=C2=A0 To add Python2 only dependencies (i.e. will not be checked if embed= ded Python is version 3), add the 'X-Python-2-Dependencies' propert= y w/ the same format.

=C2=A0 Examples could be found at pate/src/plugins/python_console_ipy= thon/katepate_python_console_ipython.desktop (and some other files)
=C2=A0 It is why 'need_packages' from libkatepate.error modu= le was removed.

4) to avoid .desktop file names clash, all of them have a prefix = 'katepate_'

5) pate engine has refactored to be able t= o load individual plugins (not all at once as it was before). so checking/u= nchecking a plugin name in the manager will load/unload it immediately (jus= t like C++ plugins manager do). It is why 'Reload plugins' button i= s not needed anymore and removed.

6) plugins w/ actions now use KXMLGUIClient and "inject"= ; their actions into UI smoothly. Particular place where an action will be = injected in UI completely defined by *_ui.rc file. It can be a main menu (m= aybe w/ submenus), context menu, or a toolbar. You can even control an appr= oximate place to merge your action w/ kate menu using groups (see cmake_uti= ls_ui.rc for example). Every <Action> entry of the *_ui.rc may contai= n attributes to specify action's text, tooltip, whatsthis, icon, shortc= ut, & etc. It is why @kate.action decorator do not need any parameters = :)
For advanced usage: also via *_ui.rc file you may control what actions shou= ld be disabled/enabled depending on various circumstances. See `commentar.p= y` plugin for example.
This feature can be used instead of some li= bkatepate.decorators.

7) pate defines an its own menu (named Pate) w/ 3 groups (to= p, mid, bottom) to merge your actions into (see block_ui.rc, format_ui.rc o= r commentar_ui.rc for usage examples)

8) the plugin also = adds a simple about dialog (About Pate). the main reason I've added it = is to show some Python info... authors/credits and other stuff still needs = (?) to be added.

9) kate.gui removed completely

10) as you probably k= now the engine do not add a plugin's directory to the python paths. so = the only path is the root of plugins! now plugin may use relative imports t= o avoid potential namespace (module names) clash. (Philipp can give more de= tails about other benefits of this :)

and finally

11) Shaheed, I'm really sorry, but d= ocumentation tab was completely removed. The reasons to do that:
= =C2=A0 * code to make a GUI from C++ (where the part of data laid in a Pyth= on namespace) is far from clean, obvious and maintainable

=C2=A0 * it would be much more simple to implement the same, using pu= re python plugin and add some action to the Help menu
=C2=A0 * esp= ecially taking in account that documentation needed only to python plugin d= evs and not for end users

=C2=A0 * honestly, that generated docs are far from being usable (any= way). Partly cuz plugins itself do not provide a good enough docs.
=C2= =A0=C2=A0=C2=A0 Partly cuz read it in a configuration dialog is far from co= nvenient (I'd prefer read docs in a browser... or at least in a slightl= y bigger window than it was)

=C2=A0 * and finally it is quite strange (unexpected) to read so= me API docs in a configuration dialog :) Just assume if someone going to wr= ite a brand new Python plugin...
=C2=A0=C2=A0=C2=A0 and in th= e middle of typing he wants to recall some details... He must to choose con= figure kate (!) which will open a modal (!!!) dialog, so he will unable to = type while reading and vise versa :)))

Some further ideas:
* make some more decor= ators to turn a python function into a signal handler for some popular even= ts of the view/document class. Particularly, to be able to enable/disable a= ctions depending on a selection in a current document, I need to track '= ;selectionChanged'... & etc.

comments? ideas?

_______________________________________________
KWrite-Devel mailing list
KWrite-Devel@kde.org
https://mail.kde.org/mailman/listinfo/kwrite-devel

--089e01536b142218e704eb531f27-- --===============4713043550144531019== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ KWrite-Devel mailing list KWrite-Devel@kde.org https://mail.kde.org/mailman/listinfo/kwrite-devel --===============4713043550144531019==--