0
# Python-Creole
1

2
A pure Python markup converter that enables seamless conversion between different markup formats. python-creole provides bidirectional conversion capabilities for Creole markup, HTML, ReStructuredText, and Textile, making it essential for documentation systems, content management, and markup processing workflows.
3

4
## Package Information
5

6
- **Package Name**: python-creole
7
- **Language**: Python
8
- **Installation**: `pip install python-creole`
9
- **License**: GPL-3.0-or-later
10
- **Python Support**: 3.6+, PyPy3
11

12
## Core Imports
13

14
```python
15
import creole
16
```
17

18
Common conversion functions:
19

20
```python
21
from creole import creole2html, html2creole, html2rest, html2textile
22
```
23

24
ReStructuredText to HTML conversion:
25

26
```python
27
from creole.rest_tools.clean_writer import rest2html
28
```
29

30
## Basic Usage
31

32
```python
33
from creole import creole2html, html2creole, html2rest, html2textile
34

35
# Convert Creole markup to HTML
36
creole_markup = "This is **bold** and //italic// text"
37
html_output = creole2html(creole_markup)
38
print(html_output)  # <p>This is <strong>bold</strong> and <i>italic</i> text</p>
39

40
# Convert HTML back to Creole
41
html_input = '<p>This is <strong>bold</strong> and <i>italic</i> text</p>'
42
creole_output = html2creole(html_input)
43
print(creole_output)  # This is **bold** and //italic// text
44

45
# Convert HTML to ReStructuredText
46
rest_output = html2rest(html_input)
47
print(rest_output)  # This is **bold** and *italic* text
48

49
# Convert HTML to Textile
50
textile_output = html2textile(html_input)
51
print(textile_output)  # This is *bold* and __italic__ text
52
```
53

54
## Architecture
55

56
python-creole uses a document tree-based conversion architecture:
57

58
- **Parsers**: Convert input markup into intermediate document tree representation
59
- **Document Tree**: Node-based structure representing markup elements and hierarchy
60
- **Emitters**: Generate output markup from document tree
61
- **Handlers**: Process special cases like unknown tags, macros, and formatting rules
62

63
This design enables clean separation between parsing and output generation, allowing flexible conversion between any supported markup formats while maintaining structural integrity.
64

65
## Capabilities
66

67
### Core Conversion Functions
68

69
Primary markup conversion functions for transforming between Creole, HTML, ReStructuredText, and Textile formats. These functions handle the most common conversion scenarios with sensible defaults.
70

71
```python { .api }
72
def creole2html(markup_string: str, debug: bool = False, 
73
                parser_kwargs: dict = None, emitter_kwargs: dict = None,
74
                block_rules: tuple = None, blog_line_breaks: bool = True,
75
                macros: dict = None, verbose: int = None, stderr = None,
76
                strict: bool = False) -> str: ...
77

78
def html2creole(html_string: str, debug: bool = False,
79
                parser_kwargs: dict = None, emitter_kwargs: dict = None,
80
                unknown_emit = None, strict: bool = False) -> str: ...
81

82
def html2rest(html_string: str, debug: bool = False,
83
              parser_kwargs: dict = None, emitter_kwargs: dict = None,
84
              unknown_emit = None) -> str: ...
85

86
def html2textile(html_string: str, debug: bool = False,
87
                 parser_kwargs: dict = None, emitter_kwargs: dict = None,
88
                 unknown_emit = None) -> str: ...
89

90
def parse_html(html_string: str, debug: bool = False) -> DocNode: ...
91
```
92

93
[Core Conversions](./core-conversions.md)
94

95
### ReStructuredText Tools
96

97
Clean HTML generation from ReStructuredText markup with minimal output formatting, designed for use in documentation systems and web publishing workflows.
98

99
```python { .api }
100
def rest2html(content: str, enable_exit_status: bool = None, **kwargs) -> str: ...
101
```
102

103
[ReStructuredText Tools](./rest-tools.md)
104

105
### Parsers and Emitters
106

107
Low-level classes for advanced parsing and emission control, enabling custom conversion workflows and specialized markup processing.
108

109
```python { .api }
110
class CreoleParser:
111
    def __init__(self, markup_string: str, **kwargs): ...
112
    def parse(self) -> DocNode: ...
113

114
class HtmlParser:
115
    def __init__(self, debug: bool = False): ...
116
    def feed(self, html_string: str) -> DocNode: ...
117

118
class HtmlEmitter:
119
    def __init__(self, document: DocNode, **kwargs): ...
120
    def emit(self) -> str: ...
121

122
class CreoleEmitter:
123
    def __init__(self, document: DocNode, debug: bool = False, **kwargs): ...
124
    def emit(self) -> str: ...
125
```
126

127
[Parsers and Emitters](./parsers-emitters.md) - includes HTML utilities and unknown tag handlers
128

129
### Macros and Extensions
130

131
Built-in macros for extended functionality including syntax highlighting and raw HTML inclusion, plus utilities for creating custom macros.
132

133
```python { .api }
134
def html(text: str) -> str: ...
135
def pre(text: str) -> str: ...
136
def code(ext: str, text: str) -> str: ...
137
```
138

139
[Macros and Extensions](./macros-extensions.md)
140

141
### Setup and Utilities
142

143
Helper functions for project setup, README generation, and development workflows, including conversion from Creole to ReStructuredText for PyPI compatibility.
144

145
```python { .api }
146
def get_long_description(package_root: str, filename: str = 'README.creole', 
147
                        raise_errors: bool = None) -> str: ...
148
def update_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
149
def assert_rst_readme(package_root: str, filename: str = 'README.creole') -> None: ...
150
```
151

152
[Setup and Utilities](./setup-utilities.md)
153

154
### Command Line Interface
155

156
Command-line tools for file-based markup conversion with support for different text encodings and batch processing.
157

158
```python { .api }
159
class CreoleCLI:
160
    def __init__(self, convert_func): ...
161
    def convert(self, sourcefile: str, destination: str, encoding: str): ...
162
```
163

164
CLI Commands:
165
- `creole2html` - Convert creole files to HTML
166
- `html2creole` - Convert HTML files to creole  
167
- `html2rest` - Convert HTML files to ReStructuredText
168
- `html2textile` - Convert HTML files to textile
169

170
[Command Line Interface](./cli.md)
171

172
## Types
173

174
```python { .api }
175
class DocNode:
176
    def __init__(self, kind: str = None, parent=None): ...
177
    def debug(self): ...
178
    def append(self, child): ...
179
    def get_text(self) -> str: ...
180
    def get_attrs_as_string(self) -> str: ...
181

182
class DocutilsImportError(ImportError):
183
    pass
184

185
class Html2restException(Exception):
186
    pass
187

188
# HTML entity decoder class
189
class Deentity:
190
    def __init__(self): ...
191
    def replace_all(self, content: str) -> str: ...
192

193
# Handler function type for unknown HTML tags
194
UnknownTagHandler = Callable[[BaseEmitter, DocNode], str]
195

196
# Macro function types
197
MacroFunction = Callable[[str], str]
198
MacroWithArgs = Callable[[str, str], str]
199
```
200

201
## Constants
202

203
```python { .api }
204
__version__: str = "1.4.10"
205
__api__: str = "1.0"  # Creole 1.0 specification compatibility
206
VERSION_STRING: str  # Deprecated alias for __version__
207
API_STRING: str      # Deprecated alias for __api__
208
```