MWParserFromHell

Warnings

• breaking Frequent dropping of support for end-of-life Python versions. For example, v0.7.0 dropped Python 3.8, v0.6.6 dropped 3.7, and v0.6.5 dropped 3.6. Ensure your Python environment is kept up-to-date with supported versions (currently Python 3.9+).
  Fix: Upgrade your Python interpreter to a version officially supported by mwparserfromhell (currently Python 3.9+). Refer to the changelog for specific version requirements.
• breaking In v0.6.0, `Wikicode.matches()` was updated to recognize underscores as equivalent to spaces, and `Template.get()` gained a `default` parameter. Also, `Wikicode`'s `filter()` methods changed their default `recursive` parameter from `False` to `True`.
  Fix: Review usage of `Wikicode.matches()`, `Template.get()`, and `filter()` methods. Explicitly set `recursive=False` if non-recursive filtering is desired.
• gotcha When installing from source, mwparserfromhell attempts to build a fast C tokenizer extension. If this fails (e.g., due to missing C compilers), it falls back to a slower pure-Python implementation. You can explicitly control this by setting the environment variable `WITH_EXTENSION=0` during installation to force the pure-Python version.
  Fix: If experiencing installation issues related to C extensions, try `WITH_EXTENSION=0 pip install mwparserfromhell` or ensure a C compiler is available on your system.
• gotcha mwparserfromhell operates on the raw wikicode. It cannot detect syntax elements produced by template transclusion (i.e., it doesn't expand templates) or resolve complex, cross-over syntax (e.g., `{{echo|''Hello}}, world!''`). For such cases, the parser may treat portions as plain text. The `skip_style_tags=True` parameter in `parse()` can sometimes help with formatting-related issues.
  Fix: Be aware of these limitations when parsing complex or transcluded wikicode. For rendered content, consider using MediaWiki's API or a different tool. For formatting issues, try `mwparserfromhell.parse(text, skip_style_tags=True)`.
• gotcha While `template['param_name']` (dict-style access) works for `Template` objects, it will raise a `ValueError` if the parameter does not exist. Using `template.get('param_name', default_value)` is generally safer and clearer for handling potentially missing parameters, similar to Python's dictionary `get` method.
  Fix: Prefer `template.get('param_name', default_value)` over `template['param_name']` when a parameter might be absent, to avoid unexpected `ValueError` exceptions.
• gotcha The nested node depth limit was raised from 40 to 100 in v0.6.6 to better match MediaWiki's parsing behavior. Extremely deeply nested wikicode structures might still hit this limit, potentially leading to incomplete parsing or errors.
  Fix: Be mindful of very deep nesting in wikicode. If encountering issues with deeply nested structures, consider simplifying the wikicode where possible or manually traversing the parsed tree to identify the problematic section.

Install

• pip install mwparserfromhell Latest stable version

Imports

• parse

  import mwparserfromhell
  wikicode = mwparserfromhell.parse(text)

  While `from mwparserfromhell import parse` technically works, the official quickstart and examples consistently use `import mwparserfromhell` and then `mwparserfromhell.parse(text)` for clarity and access to other library components.

Quickstart

This quickstart demonstrates basic parsing of MediaWiki wikicode, extracting templates, their parameters, and headings using the `mwparserfromhell.parse()` function and `Wikicode` object's filter methods.

import mwparserfromhell

text = """I has a template! {{foo|bar|baz|eggs=spam}} \n== Heading ==\n[[File:Example.jpg|thumb|A caption.]] See it?"""
wikicode = mwparserfromhell.parse(text)

print(wikicode) # Outputs the original wikicode

# Filter for templates
templates = wikicode.filter_templates()
if templates:
    template = templates[0]
    print(f"Template name: {template.name}")
    print(f"Template parameter '1': {template.get(1).value}")
    print(f"Template parameter 'eggs': {template.get('eggs').value}")

# Filter for wikilinks (e.g., file captions are wikilinks)
wikilinks = wikicode.filter_wikilinks()
if wikilinks:
    print(f"First wikilink: {wikilinks[0].title}")

# Get all headings
headings = wikicode.filter_headings()
if headings:
    print(f"First heading: {headings[0].title}")