initialize() documentation

[pdurrant]

The documentation for initialize() says:

Called once when calibre plugins are initialized. Plugins are re-initialized
every time a new plugin is added.

Perform any plugin specific initialization here, such as extracting
resources from the plugin zip file. The path to the zip file is
available as ``self.plugin_path``.

Note that ``self.site_customization`` is **not** available at this point.
'''
pass

On a plugin I'm running it seems that initialize() is being called every time the plugin runs, not just the plugins is added to calibre.

Is this expected behaviour? If so, when should a plugin run code that only needs to be run once when the plugin is added to calibre

[kovidgoyal]

In __init__ or at the module level. Or simply use a global variable to check that the initialization has been performed.

And note that, for file type plugins, the plugin is run in a worker process, which means initialization including __init__ will happen once per worker process (and note that there can be multiple worker processes, and new worker processes can be created at any time). So if you are doing some initialization that needs to occur only once, not once per processes, you will need to use some kind of IPC locking mechanism, like a sentinel directory or a lock file or a global mutex.

[pdurrant]

Many thanks.

Could you clarify the difference between the __init__() method and the initialize() method? I'm not clear on what to do in each one.

[Later]
Hmm... since initialize() is also being called every time the plugin is run, is there much point to it at all anymore? When it was only called when the plugin was installed, I can see what the point of it was, but not anymore. Or I have just not understood at all?

[kovidgoyal]

initialize() is not called every time the plugin is run, only every time it is initialized. You are probably confused because you are talking about a file type plugin run when adding books. If you add a single book at a time, a new worker processes is started for every add, which means the plugin is initialized for every add. However, if you do a recursive add, with more books than the number of CPU cores there will be a max number of worker processes equal to the number of cores on your system (say n) and initialize() will be caled only n times which is less than the number of books being added.

[pdurrant]

Ah. OK. I understand now. Perhaps the documentation of the initialize() should be updated.

[kovidgoyal]

How would the documentation be improved? I'll be happy to add something, but at least to me, the documentation seems pretty correct. It explicitly states that initialize can be called more than once.

[pdurrant]

It reads to me like it should only be called when plugins are added. That's certainly more than once, but a lot less than every time it's instantiated.

How about

"Called once when the plugin is initialized. Plugins are initialized
every time a new plugin is added, and every time the plugin is started in a new thread."

[kovidgoyal]

Added.