[prev in list] [next in list] [prev in thread] [next in thread]
List: kwrite-devel
Subject: Re: About recent changes in kate/pate
From: "Philipp A." <flying-sheep () web ! de>
Date: 2013-11-16 22:49:03
Message-ID: CAN8d9gkMZQPQGDeW74U+kgjuAHp=px_X4ep4C0fkZ60CgHhBbQ () mail ! gmail ! com
[Download RAW message or body]
[Attachment #2 (multipart/alternative)]
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, …): everything else (classes, datastructures, functions)
is put in submodules, and in __init__.py, we just define a bunch of
decorated wrapper functions 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 about (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 described by
> a corresponding .desktop file w/ 'Kate/PythonPlugin' service type
>
> 1) default Python supposed to be version 3, so if your plugin is binilgual
> a property 'X-Python-2-Compatible=true' must be added to a .desktop file
>
> 2) if your plugin is Python2 only you have add also a
> 'X-Python-2-Only=true'
>
> 3) to make some simple dependency checks (from other python modules you
> plugin may use) add 'X-Python-Dependencies=<dep>', where the <dep> is a
> string in format:
> "python-module-2-import [ | version-info ]".
> 'version-info' is quite informal text to be displayed as a tooltip over
> "broken" plugin in the manager's view.
> To add Python2 only dependencies (i.e. will not be checked if embedded
> Python is version 3), add the 'X-Python-2-Dependencies' property w/ the
> same format.
> Examples could be found at
> pate/src/plugins/python_console_ipython/katepate_python_console_ipython.desktop
> (and some other files)
> It is why 'need_packages' from libkatepate.error module was removed.
>
> 4) to avoid .desktop file names clash, all of them have a prefix
> 'katepate_'
>
> 5) pate engine has refactored to be able to load individual plugins (not
> all at once as it was before). so checking/unchecking a plugin name in the
> manager will load/unload it immediately (just like C++ plugins manager do).
> It is why 'Reload plugins' button is 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 (maybe w/
> submenus), context menu, or a toolbar. You can even control an approximate
> place to merge your action w/ kate menu using groups (see cmake_utils_ui.rc
> for example). Every <Action> entry of the *_ui.rc may contain attributes to
> specify action's text, tooltip, whatsthis, icon, shortcut, & 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
> should be disabled/enabled depending on various circumstances. See
> `commentar.py` plugin for example.
> This feature can be used instead of some libkatepate.decorators.
>
> 7) pate defines an its own menu (named Pate) w/ 3 groups (top, mid,
> bottom) to merge your actions into (see block_ui.rc, format_ui.rc or
> 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 know 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 to avoid potential namespace (module names) clash.
> (Philipp can give more details about other benefits of this :)
>
> and finally
>
> 11) Shaheed, I'm really sorry, but documentation tab was completely
> removed. The reasons to do that:
> * code to make a GUI from C++ (where the part of data laid in a Python
> namespace) is far from clean, obvious and maintainable
> * it would be much more simple to implement the same, using pure python
> plugin and add some action to the Help menu
> * especially taking in account that documentation needed only to python
> plugin devs and not for end users
> * honestly, that generated docs are far from being usable (anyway).
> Partly cuz plugins itself do not provide a good enough docs.
> Partly cuz read it in a configuration dialog is far from convenient
> (I'd prefer read docs in a browser... or at least in a slightly bigger
> window than it was)
> * and finally it is quite strange (unexpected) to read some API docs in
> a configuration dialog :) Just assume if someone going to write a brand new
> Python plugin...
> and in the middle of typing he wants to recall some details... He must
> to choose configure kate (!) which will open a modal (!!!) dialog, so he
> will unable to type while reading and vise versa :)))
>
>
> Some further ideas:
> * make some more decorators to turn a python function into a signal
> handler for some popular events of the view/document class. Particularly,
> to be able to enable/disable actions 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
>
>
[Attachment #5 (text/html)]
<div dir="ltr"><div><div>awesome, this is a good explanation!<br><br></div>and you \
already removed needs_package and so on!<br><br></div>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, …): everything else (classes, \
datastructures, functions) is put in submodules, and in __init__.py, we just define a \
bunch of decorated wrapper functions around the datastructures which live in \
submodules.<br> </div><div class="gmail_extra"><br><br><div \
class="gmail_quote">2013/11/16 Alex Turbov <span dir="ltr"><<a \
href="mailto:i.zaufi@gmail.com" \
target="_blank">i.zaufi@gmail.com</a>></span><br><blockquote class="gmail_quote" \
style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"> <div \
dir="ltr"><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div><div>Hi \
all, and especially Python plugin developers<br><br></div>I'd like to share a \
brief info about (even more) recent changes in Python plugins, so others get know \
thats going on and be able to fix if smth wrong (still unfixed).<br>
<br></div>0) as you may know plugins now searched via trader client and described by \
a corresponding .desktop file w/ 'Kate/PythonPlugin' service \
type<br><br></div>1) default Python supposed to be version 3, so if your plugin is \
binilgual a property 'X-Python-2-Compatible=true' must be added to a .desktop \
file<br>
</div><br>2) if your plugin is Python2 only you have add also a \
'X-Python-2-Only=true'<br></div><br>3) to make some simple dependency checks \
(from other python modules you plugin may use) add \
'X-Python-Dependencies=<dep>', where the <dep> is a string in \
format:<br>
</div> "python-module-2-import [ | version-info ]".<br></div> \
'version-info' is quite informal text to be displayed as a tooltip over \
"broken" plugin in the manager's view.<br></div> To add Python2 only \
dependencies (i.e. will not be checked if embedded Python is version 3), add the \
'X-Python-2-Dependencies' property w/ the same format.<br>
</div> Examples could be found at \
pate/src/plugins/python_console_ipython/katepate_python_console_ipython.desktop (and \
some other files)<br></div><div> It is why 'need_packages' from \
libkatepate.error module was removed.<br>
</div><br>4) to avoid .desktop file names clash, all of them have a prefix \
'katepate_'<br></div><br>5) pate engine has refactored to be able to load \
individual plugins (not all at once as it was before). so checking/unchecking a \
plugin name in the manager will load/unload it immediately (just like C++ plugins \
manager do). It is why 'Reload plugins' button is not needed anymore and \
removed.<br>
<br></div>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 (maybe w/ submenus), \
context menu, or a toolbar. You can even control an approximate place to merge your \
action w/ kate menu using groups (see cmake_utils_ui.rc for example). Every \
<Action> entry of the *_ui.rc may contain attributes to specify action's \
text, tooltip, whatsthis, icon, shortcut, & etc. It is why @kate.action decorator \
do not need any parameters :)<br>
For advanced usage: also via *_ui.rc file you may control what actions should be \
disabled/enabled depending on various circumstances. See `commentar.py` plugin for \
example.<br></div>This feature can be used instead of some \
libkatepate.decorators.<br>
<br></div><div>7) pate defines an its own menu (named Pate) w/ 3 groups (top, mid, \
bottom) to merge your actions into (see block_ui.rc, format_ui.rc or commentar_ui.rc \
for usage examples)<br><br></div><div>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.<br>
<br></div>9) kate.gui removed completely<br><br></div>10) as you probably know 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 to avoid potential namespace \
(module names) clash. (Philipp can give more details about other benefits of this \
:)<br>
<br></div>and finally<br><br></div>11) Shaheed, I'm really sorry, but \
documentation tab was completely removed. The reasons to do that:<br></div> * code \
to make a GUI from C++ (where the part of data laid in a Python namespace) is far \
from clean, obvious and maintainable<br>
</div> * it would be much more simple to implement the same, using pure python \
plugin and add some action to the Help menu<br></div> * especially taking in \
account that documentation needed only to python plugin devs and not for end \
users<br>
</div> * honestly, that generated docs are far from being usable (anyway). Partly \
cuz plugins itself do not provide a good enough docs. <br> Partly cuz read it \
in a configuration dialog is far from convenient (I'd prefer read docs in a \
browser... or at least in a slightly bigger window than it was)<br>
</div><div> * and finally it is quite strange (unexpected) to read some API docs in \
a configuration dialog :) Just assume if someone going to write a brand new Python \
plugin...<br></div><div> and in the middle of typing he wants to recall some \
details... He must to choose configure kate (!) which will open a modal (!!!) dialog, \
so he will unable to type while reading and vise versa :)))<br>
<br><br></div><div>Some further ideas:<br></div><div>* make some more decorators to \
turn a python function into a signal handler for some popular events of the \
view/document class. Particularly, to be able to enable/disable actions depending on \
a selection in a current document, I need to track 'selectionChanged'... \
& etc.<br>
</div><div><br></div><div>comments? ideas?<br></div><div><br></div></div>
<br>_______________________________________________<br>
KWrite-Devel mailing list<br>
<a href="mailto:KWrite-Devel@kde.org">KWrite-Devel@kde.org</a><br>
<a href="https://mail.kde.org/mailman/listinfo/kwrite-devel" \
target="_blank">https://mail.kde.org/mailman/listinfo/kwrite-devel</a><br> \
<br></blockquote></div><br></div>
_______________________________________________
KWrite-Devel mailing list
KWrite-Devel@kde.org
https://mail.kde.org/mailman/listinfo/kwrite-devel
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic