[Qgis-community-team] Developing Python Plugins Documentat​ion confusion

[Andrei Mirt]

Hello,

Thank you for your response and for the provided help, especially for
clearing up the classFactory confusion.

I would have helped if I would have had the means to do it.

Since this is my first contact with QGis plugin development and one of
the few contacts I have with python(my background is Object Pascal and
.NET mainly) I don't see the point in guessing what is the correct
version to correct it. Just because something doesn't work for me, it
doesn't mean it is generally incorrect, the same way as if something
worked for me it doesn't mean it is the correct way to do it.
For example I really didn't know if __init__.py should really have
something in it or not. Hence the back and forth moving of
classFactory in plugin.py and __init__.py, which I'm sure looks silly
to any experienced developer. These trial and error steps, I took to
check how it works, not how it should work. Of course I could have
dived into the actual code of QGis and I would have had a clear
answer, at least for the current version... unless there's a bug,
which makes QGis act against the intention of the programmer.
Actually, I would have done this if no one would have responded. After
I would have gained enough knowledge from the actual code maybe I
would have also proposed some documentation changes, but for the time
being I think it would be a waste of time for me to propose wrong
documentation (until I get lucky) as it would be for you or someone
else to reject it., even though you say you'd be happy to review it.

My point is that I don't understand how could I have helped others in
matters I couldn't help myself. Actually, I think I already helped the
community by specifically indicating parts which generates confusion
to a newbie and you confirmed me that the problem it's not on me, but
on the actual documentation. Because I know what's confusing, it
doesn't mean I know how it should be to not be confusing, but it is
rather an indication that I don't know. I also told you that I will
write a documentation page about setting up VS with PTVS when I'll
gain enough knowledge, because I don't want to post anything before
I'm sure about what I'm talking.

I knew that python doesn't require filenames/directories to be in line
with class definitions, but QGis might have asked this and this was my
confusion. The documentation doesn't say anything about this, but it
gives some examples, which might suggest this is how it should be.
Also the recommended way to start developing (PluginBuilder) creates a
skeleton with the same name for directory-filename-class. If we
consider these 2 reasons it is easy to see why questions like this may
rise.

I didn't know that asking for help is not a good practice on this
mailing list. I would have asked somewhere else, but this seemed to me
the best option to get in touch with people who are actually
developing QGis and can say what are their intention for the code
they're writing. I still think this is my best option and I will
continue to ask for help whenever I think it is reasonable, against
your recommendation, but according to your actual practice of asking
for help. Also, if no one is asking for help, then who should anyone
help and about what? I think this kind of policy reduces the quantity
of discussion. One might think that this gives more time to the
developers and increases the quality of the discussion, and I agree,
but, in my opinion this is also promoting stakeholders estrangement,
which, again, in my opinion, is disastrous for a community-based
project.

If actually modifying the documentation is problematic, I am available
anytime to change it (I am available to write such lengthy mails, one
can tell I'm not a busy man), but I don't have the knowledge to change
it. Long story, short, some points I made in the first email are still
confusing.

Could someone please explain
-if and why is the __init__ constructor method mandatory? I understand
what a constructor is and how python works and why there is a
constructor in all the plugins I checked, but is there any reason one
wouldn't/shouldn't want/need it or should it be included on the list
of mandatory methods of the main class?
-how is a plugin hooked and the intended life-cycle of a bare plugin?

I promise I will take the time to update the documentation once I'll
have the info.

Best Regards,
Andrei

On 24 February 2014 16:41, Richard Duivenvoorde <richard at duif.net> wrote:
>
> Hi Andrei,
>
> I think you raised some valid points.
>
> One thing drawback with a fast moving project like QGIS, is dat idea's
> and functionality are in flux all the time.
>
> Some remarks of you are just plain valid (aka wrong in docs: indeed the
> __init__.py should have at least classFactory attribute/method), others
> seem to come from the fact that python has some concepts that are
> different/strange when you from a (come for example java) language.
> Eg: have a look into this
> http://docs.python.org/2/tutorial/modules.html
> and see that a file name does not necessarily have to be in line with
> any class definition in it ...
>
> Another pointer: besides your three starting point, there is even a
> fourth: there is the 'Hello World' Plugin of Alessandro which, I think,
> would have been a better starting point for you...
>
> Anyway: as you are now pretty into theory and practice I would ask you
> to not 'ask for help', but just 'help' :-)
>
> Source of the page you are referring to is here:
>
> https://github.com/qgis/QGIS-Documentation/edit/master/source/docs/pyqgis_developer_cookbook/plugins.rst
>
> Feel free to fix the errors and or rewrite it so if matches current reality.
>
> We could also split up in two ways:
> - one page about a really bare 'hello world' plugin (bare minimum)
> - one page about a more advanced one (with translations and help (from
> the plugin builder plugin).
>
>
> And if you are into it:
> - plz write a page about your experience with debugging plugins on
> windows. I think a lot/most of our users or on that OS
> (personally I prefer that over 'blogging' because then some users
> complain about scattered info :-) )
>
> - here is an example on debugging but then with pycharm:
> http://linfiniti.com/2012/09/remote-debugging-qgis-plugins-using-pycharm/
>
> - here is one about seeing debug info on windows:
> http://lists.osgeo.org/pipermail/qgis-developer/2008-May/003724.html
>
> - here is another one about seeing debug info on windows:
>
> - here is one with pydev
> http://blog.vitu.ch/01082013-1452/develop-qgis-python-plugins-using-eclipse-pydev
>
> - debugging with pdb http://www.qgisworkshop.org/html/workshop/debug.html
>
> Some of the info above is already written into our docs:
> http://www.qgis.org/en/docs/pyqgis_developer_cookbook/ide_debugging.html
>
> To make a long story short: please take some time to update the docs.
> I'm happy to review it.
>
> Regards,
>
> Richard Duivenvoorde
>
>
> On 24-02-14 09:38, Andrei Mirt wrote:
>>  Hello,
>>
>> I recently started to write a plugin for QGis. I started by reading
>> the documentation and online examples. Since I want to understand
>> everything I decided not to use the recommended Plugin Builder to get
>> started with the plugin.
>> In the documentation, on this page
>> http://www.qgis.org/en/docs/pyqgis_developer_cookbook/plugins.html it
>> says what a typical plugin looks like, but not what is absolutely
>> required.
>>
>> PYTHON_PLUGINS_PATH/
>> testplug/
>> __init__.py
>> plugin.py
>> metadata.txt
>> resources.qrc
>> resources.py
>> form.ui
>> form.py
>>
>> __init__.py is, first of all, required for python related reasons.
>> Python doesn't require __init__.py to have anything in it, it can be
>> an empty file. According to the previously mentioned documentation
>> page, for QGis, __init__.py = The starting point of the plugin. It is
>> normally empty.
>>
>> But if you have an empty __init__.py QGis will invariably throw an
>> error [AttributeError: 'module' object has no attribute
>> 'classFactory'], which means that the documentation is wrong. After I
>> looked through multiple plugins I noticed that __init__.py must have a
>> classFactory method, as suggested by the error. Also, the
>> overly-highly-recommended PluginBuilder generates the classFactory
>> function in __init__.py. On the same page on the documentation, after
>> it finishes all the instructions about __init__.py and starts with the
>> instructions for the next file, plugin.py, it is stated that
>>
>> "One thing worth mentioning is classFactory() function which is called
>> when the plugin gets loaded to QGIS. It receives reference to instance
>> of QgisInterface and must return instance of your plugin - in our case
>> it’s called TestPlugin. This is how should this class look like (e.g.
>> testplugin.py):"
>>
>> and then a testplugin.py example is given, even though this is under
>> plugin.py instructions. The mismatch in the name (testplugin.py vs
>> plugin.py), is not as much as a problem as the fact that the example
>> doesn't include a classFactory method, which was worth mentioning, but
>> not worth including. Against my own logic, but according to the
>> documentation, I tried to move the classFactory method from
>> __init__.py to plugin.py, but qgis throws the same error
>> [AttributeError: 'module' object has no attribute 'classFactory'].
>> After the testplugin.py example is given it is stated that: "The only
>> plugin functions that must exist are initGui() and unload(). These
>> functions are called when the plugin is loaded and unloaded.", but I
>> don't really understand how and why would one create a plugin without
>> a __init__(self, iface) method, therefore I think it should either be
>> enforced that this class is mandatory or at least it should be
>> mentioned that it is strongly recommended, since there aren't many
>> applications that can live without it. Classes without a
>> __init__(self) constructor are perfectly valid in pyton and sometimes
>> a constructor is useless, but for the main .py file of a QGis I think
>> it should be mandatory.
>>
>> There are also some mismatches between strings that should (or
>> shouldn't?) be the same like:
>> - testplugin.py =? plugin.py
>> - __init__.py =? __init.py__
>> - testplug =? TestPlugin
>> Also things that do not necessarily have to have the same name, should
>> be clearly different. For example, should the plugin folder match a
>> .py file in the same folder and/or the name of the plugin in the
>> metadata.txt ? Are there QGis restrictions about naming structure,
>> beside those imposed by python itself?
>>
>> I am no guru, I am just getting into plugin developing for QGis and I
>> recently got into Python, so all of this is new to me. Maybe for some
>> it is so obvious what are the minimum requirements for a plugin to
>> exist, or what a __init__.py must minimally include, or what plugin.py
>> must include, that just overlook these inaccuracies, but this part of
>> the documentation is definetely addressed to newbies like me and it is
>> very confusing.
>>
>> I would like to kindly ask some QGis-Python-plugins guru to revise
>> this page to reflect reality (and also current version of QGis). I
>> would do it myself, but I am such a newbie that I may do even worse
>> than it is now.
>> In my opinion, this page should:
>> -include what are the minimum requirements for a plugin to be valid,
>> even though it does nothing and the reasons behind these requirements
>> -follow a clear standard, therefore no more mismatches like
>> testplugin.py vs plugin.py or __init__.py vs __init.py__ or testplug
>> vs testplugin.
>> -shortly explain how the plugin is actually hooked to qgis and maybe
>> plugin's lifecycle.
>>
>> The next page on the documentation is about IDE settings for writing
>> and debugging plugins. I managed to set up a really nice and comfy
>> environment in Visual Studio with PTVS for QGis python plugin
>> development. I can even start QT designer from Visual Studio, modify
>> something on the interface and then compile the .ui without leaving
>> the Visual Studio window. Also debugging and Intellisense work quite
>> well. It might be the best environment for python plugin development
>> on Windows, but it goes completely undocumented. As soon as I have a
>> thorough understanding of how qgis python plugins work, I will publish
>> an article about my experience with setting up Visual Studio with PTVS
>> for QGis Python plugins development, which I may later adapt for QGis
>> documentation. I think it would worth to be included in the
>> documentation. I know Microsoft doesn't integrate very well with
>> open-source philosophy, but it does nice things, like giving free full
>> VS licenses to students like me and I thing students are an important
>> market for QGis plugin development and QGis development in general.
>>
>> I hope I didn't bore you that much that you didn't get to this part,
>> Best Regards,
>> Andrei
>> _______________________________________________
>> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
>> Qgis-community-team at lists.osgeo.org
>> http://lists.osgeo.org/mailman/listinfo/qgis-community-team
>>
>
> _______________________________________________
> Qgis-community-team mailing list for organizing community resources such as documentation, translation etc..
> Qgis-community-team at lists.osgeo.org
> http://lists.osgeo.org/mailman/listinfo/qgis-community-team

-- 
Alfa IM Cadastru
800021, Str. Brailei,
nr. 1 bl. I, sc. 6, ap. 5
Mobil: 0751 03 44 32
Tel :    0236 41 70 52
Fax:    0236 31 77 00