Merge branch 'master' into support-2.19

.github/workflows/run_tests.yml

@@ -31,18 +31,14 @@ jobs:
         # make sure the versions are monotonic increasing w.r.t. each other
         # other wise e.g. an older version of a dependency may not work well with a newer version of Python
         include:
-          - python-version: "pypy-3.6"
-            pandoc-version: "2.12"
-            click-version: "click>=6,<7"
-            pyyaml-version: "pyyaml>=3,<4"
-          - python-version: "3.7"
-            pandoc-version: "2.13"
-            click-version: "click>=7,<8"
-            pyyaml-version: "pyyaml>=5,<6"
-          - python-version: "pypy-3.7"
-            pandoc-version: "2.14.2"
-            click-version: "click>=7,<8"
-            pyyaml-version: "pyyaml>=5,<6"
+          - python-version: "pypy-3.8"
+            pandoc-version: "3.0.1"
+            click-version: "click>=8,<9"
+            pyyaml-version: "pyyaml>=6,<7"
+          - python-version: "pypy-3.9"
+            pandoc-version: "latest"
+            click-version: "click>=8,<9"
+            pyyaml-version: "pyyaml>=6,<7"
           - python-version: "3.8"
             pandoc-version: "2.15"
             click-version: "click>=8,<9"
@@ -52,19 +48,24 @@ jobs:
             click-version: "click>=8,<9"
             pyyaml-version: "pyyaml>=6,<7"
           - python-version: "3.10"
+            pandoc-version: "2.19.2"
+            click-version: "click>=8,<9"
+            pyyaml-version: "pyyaml>=6,<7"
+            yamlloader-version: "yamlloader>=1,<2"
+          - python-version: "3.11"
             pandoc-version: "latest"
             click-version: "click>=8,<9"
             pyyaml-version: "pyyaml>=6,<7"
             yamlloader-version: "yamlloader>=1,<2"
-          - python-version: "3.11-dev"
+          - python-version: "3.12-dev"
             pandoc-version: "latest"
             click-version: "click>=8,<9"
             pyyaml-version: "pyyaml>=6,<7"
             yamlloader-version: "yamlloader>=1,<2"
     steps:
-    - uses: actions/checkout@v2
+    - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v2
+      uses: actions/setup-python@v4
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016, Sergio Correia
+Copyright (c) 2016-2023, Sergio Correia
 
 All rights reserved.
 

README.md

@@ -15,7 +15,7 @@
 
 For a detailed user guide, documentation, and installation instructions, see
 <http://scorreia.com/software/panflute/>.
-For examples that you can use as starting points, check the [examples repo](https://github.com/sergiocorreia/panflute-filters/tree/master/filters), the [sample template](https://raw.githubusercontent.com/sergiocorreia/panflute/master/docs/source/_static/template.py), or [this github search](https://github.com/search?o=desc&q=%22import+panflute%22+OR+%22from+panflute%22+created%3A%3E2016-01-01+language%3APython+extension%3Apy&s=indexed&type=Code&utf8=%E2%9C%93).
+For examples that you can use as starting points, check the [examples repo](https://github.com/sergiocorreia/panflute-filters/tree/master/filters), the [sample template](https://raw.githubusercontent.com/sergiocorreia/panflute/master/docs/source/_static/template.py), or [this github search](https://github.com/search?q=import+panflute+extension%3Apy&type=Code).
 If you want to contribute, head [here](/CONTRIBUTING.md).
 
 You might also find useful [this presentation](https://github.com/BPLIM/Workshops/raw/master/BPLIM2019/D2_S1_Sergio_Correia_Markdown.pdf) on how I use markdown+pandoc+panflute to write research papers (at the Banco de Portugal 2019 Workshop on Reproductible Research).
@@ -61,9 +61,9 @@ pandoc versioning semantics is [MAJOR.MAJOR.MINOR.PATCH](https://pvp.haskell.org
 
 | panflute version | supported pandoc versions | supported pandoc API versions |
 | ---------------- | ------------------------- | ----------------------------- |
-| 2.2              | 2.11.0.4-2.19.x           | 1.22                          |
-| 2.1.3            | 2.11.0.4–2.19.x           | 1.22                          |
-| 2.1              | 2.11.0.4—2.14.x           | 1.22                          |
+| 2.3.0            | 2.11.0.4–3.0.x            | 1.22–1.23                     |
+| 2.2.4            | 2.11.0.4–2.17.x           | 1.22–1.22.1                   |
+| 2.1.x            | 2.11.0.4—2.14.x           | 1.22                          |
 | 2.0              | 2.11.0.4—2.11.x           | 1.22                          |
 | not supported    | 2.10                      | 1.21                          |
 | 1.12             | 2.7-2.9                   | 1.17.5–1.20                   |
@@ -84,3 +84,10 @@ Feel free to submit push requests. For consistency, code should comply with [pep
 ## License
 
 BSD3 license (following [`pandocfilters`](https://github.com/jgm/pandocfilters) by @jgm).
+
+
+## Changelog
+
+- `2.3.0` Update [Pandoc API](https://github.com/jgm/pandoc-types/blob/master/changelog) from 1.22 to 1.23 ([Pandoc 3.0](https://pandoc.org/releases.html#pandoc-3.0-2023-01-18)):
+    - Add `Figure` block object
+    - Remove `Null` block object (scheduled for removed)

panflute/__init__.py

@@ -22,7 +22,7 @@
     Code, BlockQuote, Note, Div, Plain, Para, Emph, Strong, Underline,
     Strikeout, Superscript, Subscript, SmallCaps, Span, RawBlock, RawInline,
     Math, CodeBlock, Link, Image, BulletList, OrderedList, DefinitionList,
-    LineBlock, Header, Quoted, Cite)
+    LineBlock, Figure, Header, Quoted, Cite)
 
 from .table_elements import (
     Table, TableHead, TableFoot, TableBody,

panflute/elements.py

@@ -9,7 +9,7 @@
 # Imports
 # ---------------------------
 
-from .utils import check_type, check_group, encode_dict, decode_ica, debug
+from .utils import check_type, check_group, encode_dict, decode_ica, debug, check_type_or_value
 from .utils import load_pandoc_version, load_pandoc_reader_options
 from .containers import ListContainer, DictContainer
 from .base import Element, Block, Inline, MetaValue
@@ -53,7 +53,7 @@ class Doc(Element):
 
     _children = ['metadata', 'content']
 
-    def __init__(self, *args, metadata={}, format='html', api_version=(1, 22)):
+    def __init__(self, *args, metadata={}, format='html', api_version=(1, 23)):
         self._set_content(args, Block)
         self.metadata = metadata
         self.format = format  # Output format
@@ -101,6 +101,7 @@ def to_json(self):
 # Classes - Empty
 # ---------------------------
 
+# TODO: Remove
 class Null(Block):
     """Nothing
 
@@ -1006,6 +1007,55 @@ def _slots_to_json(self):
         return self.content.to_json()
 
 
+
+# ---------------------------
+# Classes - Figures
+# ---------------------------
+
+class Figure(Block):
+    """Standalone figure, with attributes, caption, and arbitrary block content
+
+    :param args: contents of the figure block
+    :type args: :class:`Block`
+    :param identifier: element identifier (usually unique)
+    :type identifier: :class:`str`
+    :param classes: class names of the element
+    :type classes: :class:`list` of :class:`str`
+    :param attributes: additional attributes
+    :type attributes: :class:`dict`
+    :Base: :class:`Block`
+
+    :Example:
+
+        >>> image = Image(Str("Description"), title='The Title',
+                    url='example.png', attributes={'height':'256px'})
+        >>> caption = Caption(Plain(Str('The'), Space, Str('Caption')))
+        >>> figure = Figure(Plain(image), caption=caption, identifier='figure1')
+     """
+
+    __slots__ = ['_content', '_caption', 'identifier', 'classes', 'attributes']
+    _children = ['content', 'caption']
+
+    def __init__(self, *args, caption=None, identifier='', classes=[], attributes={}):
+        self._set_ica(identifier, classes, attributes)
+        self._set_content(args, Block)
+        self.caption = caption
+
+    @property
+    def caption(self):
+        return self._caption
+
+    @caption.setter
+    def caption(self, value):
+        self._caption = check_type_or_value(value, Caption, None)
+        if self._caption is not None:
+            self._caption.parent = self
+            self._caption.location = 'caption'
+
+    def _slots_to_json(self):
+        return [self._ica_to_json(), self.caption.to_json(), self.content.to_json()]
+
+
 # ---------------------------
 # Classes - Metadata
 # ---------------------------
@@ -1342,6 +1392,7 @@ def _decode_definition_item(item):
     'DefinitionList': lambda c: DefinitionList(*[_decode_definition_item(item) for item in c]),
     'LineBlock': lambda c: LineBlock(*[LineItem(*item) for item in c]),
     'ColWidth': lambda c: c,
+    'Figure': lambda c: Figure(*c[2], caption=Caption(*c[1][1], short_caption=c[1][0]), **decode_ica(c[0])),
     'Table': table_from_json,
     'MetaMap': lambda c: MetaMap(*c.items()),
 }

panflute/version.py

@@ -2,4 +2,4 @@
 Panflute version
 """
 
-__version__ = '2.2.4'
+__version__ = '2.3.0'

setup.py

@@ -75,6 +75,7 @@
         'Programming Language :: Python :: 3.8',
         'Programming Language :: Python :: 3.9',
         'Programming Language :: Python :: 3.10',
+        'Programming Language :: Python :: 3.11',
         'Programming Language :: Python :: Implementation :: CPython',
         'Programming Language :: Python :: Implementation :: PyPy'
     ],

tests/test_walk.py

@@ -17,6 +17,17 @@ def compare_docs(doc_a, doc_b):
     return doc_a_json == doc_b_json
 
 
+"""
+Find out the current Pandoc API version (else test fails)
+"""
+
+from panflute.tools import pandoc_version
+api_version = (1, 23)
+if pandoc_version.version < (3, 0, 0):
+    api_version = (1, 22)
+
+
+
 """
 Action functions to use in testing
 """
@@ -63,39 +74,39 @@ def block_replace_list(elem, doc):
 
 
 def test_none():
-    in_doc = expected_doc = pf.Doc(pf.Para(pf.Str("a")))
+    in_doc = expected_doc = pf.Doc(pf.Para(pf.Str("a")), api_version=api_version)
     in_doc.walk(do_nothing)
     assert compare_docs(in_doc, expected_doc)
 
 
 def test_empty_list():
-    in_doc = pf.Doc(pf.Para(pf.Str("a"), pf.Space))
+    in_doc = pf.Doc(pf.Para(pf.Str("a"), pf.Space), api_version=api_version)
     in_doc.walk(remove_elem)
-    expected_doc = pf.Doc(pf.Para(pf.Space))
+    expected_doc = pf.Doc(pf.Para(pf.Space), api_version=api_version)
     assert compare_docs(in_doc, expected_doc)
 
 def test_inline_elem():
-    in_doc = pf.Doc(pf.Para(pf.Str("a")))
+    in_doc = pf.Doc(pf.Para(pf.Str("a")), api_version=api_version)
     in_doc.walk(inline_replace_elem)
-    expected_doc = pf.Doc(pf.Para(pf.Str("b")))
+    expected_doc = pf.Doc(pf.Para(pf.Str("b")), api_version=api_version)
     assert compare_docs(in_doc, expected_doc)
 
 def test_inline_list():
-    in_doc = pf.Doc(pf.Para(pf.Str("a")))
+    in_doc = pf.Doc(pf.Para(pf.Str("a")), api_version=api_version)
     in_doc.walk(inline_replace_list)
-    expected_doc = pf.Doc(pf.Para(pf.Str("a"), pf.Space, pf.Str("b")))
+    expected_doc = pf.Doc(pf.Para(pf.Str("a"), pf.Space, pf.Str("b")), api_version=api_version)
     assert compare_docs(in_doc, expected_doc)
 
 
 def test_block_elem():
-    in_doc = pf.Doc(pf.Para(pf.Str("a")))
+    in_doc = pf.Doc(pf.Para(pf.Str("a")), api_version=api_version)
     in_doc.walk(block_replace_elem)
-    expected_doc = pf.Doc(pf.CodeBlock("b"))
+    expected_doc = pf.Doc(pf.CodeBlock("b"), api_version=api_version)
     assert compare_docs(in_doc, expected_doc)
 
 
 def test_block_list():
-    in_doc = pf.Doc(pf.Para(pf.Str("c")))
+    in_doc = pf.Doc(pf.Para(pf.Str("c")), api_version=api_version)
     in_doc.walk(block_replace_list)
-    expected_doc = pf.Doc(pf.Para(pf.Str("a")), pf.Para(pf.Str("b")))
+    expected_doc = pf.Doc(pf.Para(pf.Str("a")), pf.Para(pf.Str("b")), api_version=api_version)
     assert compare_docs(in_doc, expected_doc)