0
# Panflute
1

2
A Python library that provides a pythonic alternative to pandocfilters for creating Pandoc document filters. Panflute enables programmatic manipulation and transformation of documents in various formats (Markdown, LaTeX, HTML, etc.) by providing an intuitive object-oriented API for working with Pandoc's abstract syntax tree (AST).
3

4
## Package Information
5

6
- **Package Name**: panflute
7
- **Language**: Python
8
- **Installation**: `pip install panflute`
9
- **Requirements**: Python 3.7+, Pandoc 2.11.0.4–3.1.x
10

11
## Core Imports
12

13
```python
14
import panflute as pf
15
```
16

17
For specific components:
18

19
```python
20
from panflute import Doc, Para, Str, run_filter, stringify
21
```
22

23
Check version:
24

25
```python
26
import panflute as pf
27
print(pf.__version__)  # '2.3.1'
28
```
29

30
## Basic Usage
31

32
```python
33
import panflute as pf
34

35
def capitalize_strings(elem, doc):
36
    """Filter function to capitalize all strings in a document."""
37
    if isinstance(elem, pf.Str):
38
        return pf.Str(elem.text.upper())
39

40
if __name__ == '__main__':
41
    pf.run_filter(capitalize_strings)
42
```
43

44
Creating documents programmatically:
45

46
```python
47
import panflute as pf
48

49
# Create a simple document
50
doc = pf.Doc(
51
    pf.Header(pf.Str('My Title'), level=1),
52
    pf.Para(pf.Str('Hello '), pf.Strong(pf.Str('world')), pf.Str('!')),
53
    pf.Para(pf.Link(pf.Str('Visit our site'), url='https://example.com'))
54
)
55

56
# Convert to JSON for Pandoc
57
pf.dump(doc)
58
```
59

60
## Architecture
61

62
Panflute's architecture is built around Pandoc's AST hierarchy:
63

64
- **Document (Doc)**: Root container with metadata and content blocks
65
- **Elements**: Base class for all AST nodes with parent-child relationships and navigation
66
- **Blocks**: Top-level document structures (paragraphs, headers, lists, tables)
67
- **Inlines**: Text-level elements within blocks (strings, emphasis, links, images)
68
- **MetaValues**: Metadata elements for document frontmatter
69
- **Containers**: List and dict wrappers that maintain parent-child relationships
70

71
The library provides comprehensive tree traversal through the `walk()` method, enabling powerful document transformations while preserving the AST structure and relationships.
72

73
## Capabilities
74

75
### Document I/O
76

77
Core functions for reading and writing Pandoc JSON documents, running filter functions, and managing document processing workflows.
78

79
```python { .api }
80
def load(input_stream=None) -> Doc: ...
81
def dump(doc: Doc, output_stream=None): ...
82
def run_filter(action: callable, **kwargs): ...
83
def run_filters(actions: list, **kwargs): ...
84
```
85

86
[Document I/O](./document-io.md)
87

88
### Document Elements
89

90
Complete set of Pandoc AST element classes for building and manipulating documents, including blocks, inlines, metadata, and table components.
91

92
```python { .api }
93
class Doc(Element): ...
94
class Para(Block): ...
95
class Header(Block): ...
96
class Str(Inline): ...
97
class Emph(Inline): ...
98
class Link(Inline): ...
99
class Table(Block): ...
100
class TableRow(Element): ...
101
class TableCell(Element): ...
102
```
103

104
[Document Elements](./document-elements.md)
105

106
### Text Processing Tools
107

108
Utility functions for text extraction, document conversion, YAML processing, and external tool integration.
109

110
```python { .api }
111
def stringify(element, newlines=True) -> str: ...
112
def convert_text(text, input_format='markdown', output_format='panflute', **kwargs): ...
113
def yaml_filter(element, doc, **kwargs): ...
114
def shell(args, wait=True, msg=None): ...
115
```
116

117
[Text Processing Tools](./text-processing.md)
118

119
### Command Line Interface
120

121
CLI tools for running panflute as a Pandoc filter with automatic filter discovery and execution capabilities.
122

123
```python { .api }
124
def main(): ...
125
def panfl(): ...
126
def stdio(filters=None, **kwargs): ...
127
```
128

129
[Command Line Interface](./cli.md)
130

131
## Types
132

133
### Core Types
134

135
```python { .api }
136
class Element:
137
    """
138
    Base class for all Pandoc elements.
139
    
140
    Provides core functionality for element tree traversal, JSON serialization,
141
    and parent-child relationship tracking.
142
    
143
    Properties:
144
    - parent: parent element (None for root)
145
    - location: attribute name in parent where this element is stored
146
    - index: position in parent container (for list elements)
147
    - tag: element type name (read-only)
148
    
149
    Methods:
150
    - walk(action, doc=None, stop_if=None): traverse element tree applying action
151
    - to_json(): serialize element to Pandoc JSON format
152
    """
153
    parent: Element | None
154
    location: str | None
155
    index: int | None
156
    
157
    @property
158
    def tag(self) -> str: ...
159
    
160
    def walk(self, action: callable, doc: Doc = None, stop_if: callable = None) -> Element: ...
161
    def to_json(self) -> dict: ...
162

163
class Block(Element):
164
    """Base class for block-level elements (paragraphs, headers, lists, etc.)."""
165

166
class Inline(Element):
167
    """Base class for inline elements (text, emphasis, links, etc.)."""
168

169
class MetaValue(Element):
170
    """Base class for metadata elements (strings, lists, maps, etc.)."""
171
```
172

173
### Container Types
174

175
```python { .api }
176
class ListContainer:
177
    """
178
    Wrapper around a list to track elements' parents.
179
    
180
    This class shouldn't be instantiated directly by users,
181
    but by the elements that contain it.
182
    
183
    Parameters:
184
    - *args: elements contained in the list
185
    - oktypes: type or tuple of types allowed as items (default: object)
186
    - parent: the parent element
187
    
188
    Methods:
189
    - walk(action, doc=None, stop_if=None): apply action to all contained elements
190
    - to_json(): convert to JSON representation
191
    """
192
    def __init__(self, *args, oktypes=object, parent=None): ...
193

194
class DictContainer:
195
    """
196
    Wrapper around a dict to track elements' parents.
197
    
198
    This class shouldn't be instantiated directly by users,
199
    but by the elements that contain it.
200
    
201
    Parameters:
202
    - *args: elements contained in the dict (sequence of tuples)
203
    - oktypes: type or tuple of types allowed as items (default: object)
204
    - parent: the parent element
205
    - **kwargs: additional key-value pairs
206
    
207
    Methods:
208
    - walk(action, doc=None, stop_if=None): apply action to all contained elements
209
    - to_json(): convert to JSON representation
210
    """
211
    def __init__(self, *args, oktypes=object, parent=None, **kwargs): ...
212

213
# Version information
214
__version__: str  # Library version string (e.g., '2.3.1')
215
```