[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kwrite-devel
Subject:    Re: About recent changes in kate/pate
From:       Shaheed Haque <srhaque () theiet ! org>
Date:       2013-11-17 1:11:15
Message-ID: CAHAc2jfnW3mP4xw39oYAaHAafb36hKN=rszwSRCnynuK6rw-5A () mail ! gmail ! com
[Download RAW message or body]

[Attachment #2 (multipart/alternative)]


Honestly, the Documentation tab is not a huge loss. It was useful for me
when I was first learning Python and pulling in Pate. And removing it means
we can now be fully i18n, so the translators will be happy. So, it is all
good.

One question: when I was thinking about .desktop files, I did not think I
could use the KTrader setup because I could not find a way for a user to
make a hacked version of a plugin without needing system privs (i.e. a copy
in his local directory overrides one in the system directories). Is that
still possible? Again, I'm not sure it is a big loss, but I would e curious
if you came across an answer for this.

On 16 November 2013 22:49, Philipp A. <flying-sheep@web.de> wrote:

> 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
>>
>>
>
> _______________________________________________
> KWrite-Devel mailing list
> KWrite-Devel@kde.org
> https://mail.kde.org/mailman/listinfo/kwrite-devel
>
>

[Attachment #5 (text/html)]

<div dir="ltr"><div>Honestly, the Documentation tab is not a huge loss. It \
was useful for me when I was first learning Python and pulling in Pate. And \
removing it means we can now be fully i18n, so the translators will be \
happy. So, it is all good.<br> </div><div \
class="gmail_extra"><br></div><div class="gmail_extra">One question: when I \
was thinking about .desktop files, I did not think I could use the KTrader \
setup because I could not find a way for a user to make a hacked version of \
a plugin without needing system privs (i.e. a copy in his local directory \
overrides one in the system directories). Is that still possible? Again, \
I&#39;m not sure it is a big loss, but I would e curious if you came across \
an answer for this.<br> <br><div class="gmail_quote">On 16 November 2013 \
22:49, Philipp A. <span dir="ltr">&lt;<a href="mailto:flying-sheep@web.de" \
target="_blank">flying-sheep@web.de</a>&gt;</span> wrote:<br><blockquote \
class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> <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">&lt;<a href="mailto:i.zaufi@gmail.com" \
target="_blank">i.zaufi@gmail.com</a>&gt;</span><br><blockquote \
class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc \
solid;padding-left:1ex"> <div><div class="h5">
<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&#39;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/ &#39;Kate/PythonPlugin&#39; \
service type<br><br></div>1) default Python supposed to be version 3, so if \
your plugin is binilgual a property &#39;X-Python-2-Compatible=true&#39; \
must be added to a .desktop file<br>


</div><br>2) if your plugin is Python2 only you have add also a \
&#39;X-Python-2-Only=true&#39;<br></div><br>3) to make some simple \
dependency checks (from other python modules you plugin may use) add \
&#39;X-Python-Dependencies=&lt;dep&gt;&#39;, where the &lt;dep&gt; is a \
string in format:<br>


</div>   &quot;python-module-2-import [ | version-info ]&quot;.<br></div>   \
&#39;version-info&#39; is quite informal text to be displayed as a tooltip \
over &quot;broken&quot; plugin in the manager&#39;s view.<br></div>   To \
add Python2 only dependencies (i.e. will not be checked if embedded Python \
is version 3), add the &#39;X-Python-2-Dependencies&#39; 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 &#39;need_packages&#39; \
from libkatepate.error module was removed.<br>


</div><br>4) to avoid .desktop file names clash, all of them have a prefix \
&#39;katepate_&#39;<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 &#39;Reload \
plugins&#39; button is not needed anymore and removed.<br>


<br></div>6) plugins w/ actions now use KXMLGUIClient and \
&quot;inject&quot; 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 &lt;Action&gt; entry of \
the *_ui.rc may contain attributes to specify action&#39;s text, tooltip, \
whatsthis, icon, shortcut, &amp; 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&#39;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&#39;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&#39;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&#39;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 &#39;selectionChanged&#39;... &amp; etc.<br>


</div><div><br></div><div>comments? ideas?<br></div><div><br></div></div>
<br></div></div>_______________________________________________<br>
KWrite-Devel mailing list<br>
<a href="mailto:KWrite-Devel@kde.org" \
target="_blank">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> \
<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></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