Document breaking changes in Pelican 4.5

[shniubobo]

• I have read the Filing Issues and subsequent “How to Get Help” sections of the documentation.
• I have searched the issues (including closed ones) and believe that this is not a duplicate.

• OS version and name: Ubuntu 18.04 (WSL)
• Python version: 3.8.6

Issues

The first one

As of 58edad6, import pelican.signals is no longer valid.

$ git reset 58edad^ --hard
$ python -c "import pelican.signals"  # exits 0

$ git reset 58edad --hard
$ python -c "import pelican.signals"
Traceback (most recent call last):
  File "<string>", line 1, in <module>
ModuleNotFoundError: No module named 'pelican.signals'

The second one

As of ed1eca1, legacy plugins with . in their names stop working.

To reproduce

Create these files:

├── content
│   └── 1.rst
├── pelicanconf.py
├── plugins
│   └── m
│       └── test.py

.. content/1.rst
###
123
###

# pelicanconf.py
PLUGINS = [
    'm.test',
]
PLUGIN_PATHS = [
    'plugins'
]

# plugins/m/test.py
from pelican import signals


def takes_nothing():
    pass


def register():
    signals.initialized.connect(takes_nothing)

And then:

$ git reset ed1eca^ --hard
$ python -m pelican content
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: No timezone information specified in the settings. Assuming your timezone is UTC for feed generation. Check http://docs.getpelican.com/en/latest/settings.html#timezone for more information
CRITICAL: takes_nothing() takes 0 positional arguments but 1 was given
# plugin correctly loaded

$ git reset ed1eca --hard
$ python -m pelican content
WARNING: Feeds generated without SITEURL set properly may not be valid
WARNING: No timezone information specified in the settings. Assuming your timezone is UTC for feed generation. Check http://docs.getpelican.com/en/latest/settings.html#timezone for more information
ERROR: Cannot load plugin `m.test`
  | No module named 'm'
ERROR: Skipping /[path redacted]/content/1.rst: could not find information about 'date'
Done: Processed 0 articles, 0 drafts, 0 pages, 0 hidden pages and 0 draft pages in 0.08 seconds.
# plugin not loaded

Projects affected by these changes

An example: https://github.com/mosra/m.css

And a related issue: mosra/m.css#178

[avaris]

First one was known, I tried to keep it backwards compatible at first by adding a dummy file but then opted to remove that since no plugin was using that style. from pelican import signals will still work.

I'll check second one. Does it still error if you include an empty __init__.py in the m folder~ Edit: Yes, it does. It think I found the issue. It was an oversight or misunderstanding on my part, about how the import machinery works. It doesn't seem to automatically resolve package submodules. I'll try to work on it soon.

[shniubobo]

First one was known, I tried to keep it backwards compatible at first by adding a dummy file but then opted to remove that since no plugin was using that style. from pelican import signals will still work.

I'll check second one. Does it still error if you include an empty __init__.py in the m folder?

Yes it still errors.

In the affected project mentioned above, there is an empty __init__.py.

[avaris]

This should be enough to fix the second issue, if you want to test it out:

diff --git a/pelican/plugins/_utils.py b/pelican/plugins/_utils.py
index 78c19e54..a2930551 100644
--- a/pelican/plugins/_utils.py
+++ b/pelican/plugins/_utils.py
@@ -40,6 +40,11 @@ def list_plugins(ns_pkg=None):


 def load_legacy_plugin(plugin, plugin_paths):
+    if '.' in plugin:
+        # it is in a package, so resolve packages first
+        package, _, _ = plugin.rpartition('.')
+        load_legacy_plugin(package, plugin_paths)
+
     # Try to find plugin in PLUGIN_PATHS
     spec = importlib.machinery.PathFinder.find_spec(plugin, plugin_paths)
     if spec is None:

I'll make a PR when I have time to add tests for it.

[shniubobo]

Thanks for the quick fix! The plugins work fine with this patch.

But what about the first issue? Maybe one extra line in the changelog could save lots of plugin developers' time. You know, a lot of plugins are not included in the pelican-plugins repo (like the affected project I mentioned). These plugins' developers, if they were using import pelican.signals, a BREAKING CHANGES section in the changelog could help them fix their broken plugins easily. As is in the related issue I mentioned, sometimes this simple import error can be difficult to debug.

[avaris]

We can add the changelog entry for the next version about the change.

I could also restore pelican.signals but only with an ImportError stating that it is deprecated, and tell plugins to switch. That would look like this:

ERROR: Cannot load plugin `m.test`
  | Importing from `pelican.signals` is deprecated. Use `from pelican import signals` or `import pelican.plugins.signals` instead.

[justinmayer]

I took the liberty of updating the Pelican 4.5 release post, adding a fourth caveat to the “Upgrading from previous releases” section and including the above deprecation details.

[mosra]

This should be enough to fix the second issue

@avaris this is great, thank you ❤️ Would significantly simplify everything for all m.css users :)

[egberts]

I'm running Pelican 4.5.0 and am still experiencing load_legacy() not found issue.

$ python3.8 -c "import pelican;print(pelican.__version__)"
4.5.0

At 7a6686f (origin/master, origin/HEAD) Fix SUMMARY_END_SUFFIX variable name in changelog

I've done a git submodule checkout of m.css into the working area of a website such that this directory layout is:

+ egbert.net
|-- content
|-- output
|-- plugins
|-- m.css
   |
   +-- plugins
      +-- ansilexer.py
      +-- dot2svg.py
      +-- latex2svg.py
      +-- latex2svgextra.py
      +-- m
         +-- htmlsanity.py
         +-- metadata.py 
...

I used the following plugin settings:

PLUGIN_PATHS = [ './plugins', 'm.css/plugins' ]
PLUGINS = [
#          'i18n_subsites',
          'collate_content',
          'sitemap',
          'dateish',
          'tag_cloud',
          'm.alias',
          'm.htmlsanity',
          'm.images',
          'm.math',
          'just_table',
          'code_include',
]

And my console output for Pelican was:

ERROR: Cannot load plugin `m.alias`
  | No module named 'm'
ERROR: Cannot load plugin `m.htmlsanity`
  | No module named 'm'
ERROR: Cannot load plugin `m.images`
  | No module named 'm'
ERROR: Cannot load plugin `m.math`
  | No module named 'm'

Surely, I must be misreading the documentation or something, am I?

[avaris]

I'm running Pelican 4.5.0 and am still experiencing load_legacy() not found issue.

Still? It's not fixed yet.

[egberts]

Yeah, latest master. Will troubleshoot this.

A different error occurred when I used the following:

PLUGIN_PATHS = [ './plugins', 'm.css/plugins', 'm.css/plugins/m' ]

whose output gives:

(Pdb) c
ERROR: Cannot load plugin `m.math`
  | No module named 'latex2svg'
ERROR: Cannot register plugin `m.alias`
  | No module named 'pelican.signals'
ERROR: Cannot register plugin `m.htmlsanity`
  | name 'pelican' is not defined
ERROR: Cannot register plugin `m.images`
  | No module named 'pelican.signals'

Ordering of PLUGIN_PATHS don't matter... Discontinuing this specific approach. Back to debugging 4.5.0 and legacy plugins.