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

[Andrei Mirt]

 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