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

[Richard Duivenvoorde]

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
>