Skip to main content

Microformats parser

Project description

mf2py banner

version downloads license python-version

Welcome 👋

mf2py is a Python microformats parser with full support for microformats2, backwards-compatible support for microformats1 and experimental support for metaformats.

Installation 💻

To install mf2py run the following command:

$ pip install mf2py

Quickstart 🚀

Import the library:

>>> import mf2py

Parse an HTML Document from a file or string

>>> with open("test/examples/eras.html") as fp:
...     mf2json = mf2py.parse(doc=fp)
>>> mf2json
{'items': [{'type': ['h-entry'],
            'properties': {'name': ['Excited for the Taylor Swift Eras Tour'],
                           'author': [{'type': ['h-card'],
                                       'properties': {'name': ['James'],
                                                      'url': ['']},
                                       'value': 'James',
                                       'lang': 'en-us'}],
                           'published': ['2023-11-30T19:08:09'],
                           'featured': [{'value': '',
                                         'alt': 'Eras tour poster'}],
                           'content': [{'value': "I can't decide which era is my favorite.",
                                        'lang': 'en-us',
                                        'html': "<p>I can't decide which era is my favorite.</p>"}],
                           'category': ['music', 'Taylor Swift']},
            'lang': 'en-us'}],
 'rels': {'webmention': ['']},
 'rel-urls': {'': {'text': '',
                                               'rels': ['webmention']}},
 'debug': {'description': 'mf2py - microformats2 parser for python',
           'source': '',
           'version': '2.0.0',
           'markup parser': 'html5lib'}}
>>> mf2json = mf2py.parse(doc="<a class=h-card href=>James</a>")
>>> mf2json["items"]
[{'type': ['h-card'],
  'properties': {'name': ['James'],
                 'url': ['']}}]

Parse an HTML Document from a URL

>>> mf2json = mf2py.parse(url="")
>>> mf2json["items"][0]["type"]
>>> mf2json["items"][0]["children"][0]["type"]

Experimental Options

The following options can be invoked via keyword arguments to parse() and Parser().


Use expose_dom=True to expose the DOM of embedded properties.


Use metaformats=True to include any metaformats found.


Use filter_roots=True to filter known conflicting user names (e.g. Tailwind). Otherwise provide a custom list to filter instead.

Advanced Usage

parse is a convenience function for Parser. More sophisticated behaviors are available by invoking the parser object directly.

>>> with open("test/examples/festivus.html") as fp:
...     mf2parser = mf2py.Parser(doc=fp)

Filter by Microformat Type

>>> mf2json = mf2parser.to_dict()
>>> len(mf2json["items"])
>>> len(mf2parser.to_dict(filter_by_type="h-card"))
>>> len(mf2parser.to_dict(filter_by_type="h-entry"))

JSON Output

>>> json = mf2parser.to_json()
>>> json_cards = mf2parser.to_json(filter_by_type="h-card")

Breaking Changes in mf2py 2.0

  • Image alt support is now on by default.

Notes 📝

  • If you pass a BeautifulSoup document it may be modified.
  • A hosted version of mf2py is available at

Contributing 🛠️

We welcome contributions and bug reports via GitHub.

This project follows the IndieWeb code of conduct. Please be respectful of other contributors and forge a spirit of positive co-operation without discrimination or disrespect.

License 🧑‍⚖️

mf2py is licensed under an MIT License.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mf2py-2.0.1.tar.gz (21.8 kB view hashes)

Uploaded Source

Built Distribution

mf2py-2.0.1-py3-none-any.whl (25.8 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page