API

Reading

frontmatter.parse(text, encoding='utf-8', handler=None, **defaults)

Parse text with frontmatter, return metadata and content. Pass in optional metadata defaults as keyword args.

If frontmatter is not found, returns an empty metadata dictionary (or defaults) and original text content.

>>> with open('tests/yaml/hello-world.txt') as f:
...     metadata, content = frontmatter.parse(f.read())
>>> print(metadata['title'])
Hello, world!

frontmatter.check(fd, encoding='utf-8')

Check if a file-like object or filename has a frontmatter, return True if exists, False otherwise.

If it contains a frontmatter but it is empty, return True as well.

>>> frontmatter.check('tests/yaml/hello-world.txt')
True

frontmatter.checks(text, encoding='utf-8')

Check if a text (binary or unicode) has a frontmatter, return True if exists, False otherwise.

If it contains a frontmatter but it is empty, return True as well.

>>> with open('tests/yaml/hello-world.txt') as f:
...     frontmatter.checks(f.read())
True

frontmatter.load(fd, encoding='utf-8', handler=None, **defaults)

Load and parse a file-like object or filename, return a post.

>>> post = frontmatter.load('tests/yaml/hello-world.txt')
>>> with open('tests/yaml/hello-world.txt') as f:
...     post = frontmatter.load(f)

frontmatter.loads(text, encoding='utf-8', handler=None, **defaults)

Parse text (binary or unicode) and return a post.

>>> with open('tests/yaml/hello-world.txt') as f:
...     post = frontmatter.loads(f.read())

Writing

frontmatter.dump(post, fd, encoding='utf-8', handler=None, **kwargs)

Serialize post to a string and write to a file-like object. Text will be encoded on the way out (utf-8 by default).

>>> from io import BytesIO
>>> post = frontmatter.load('tests/yaml/hello-world.txt')
>>> f = BytesIO()
>>> frontmatter.dump(post, f)
>>> print(f.getvalue().decode('utf-8'))
---
layout: post
title: Hello, world!
---

Well, hello there, world.

from io import BytesIO
post = frontmatter.load('tests/yaml/hello-world.txt')
f = BytesIO()
frontmatter.dump(post, f)
print(f.getvalue().decode('utf-8'))

---
layout: post
title: Hello, world!
---
<BLANKLINE>
Well, hello there, world.

frontmatter.dumps(post, handler=None, **kwargs)

Serialize a post to a string and return text. This always returns unicode text, which can then be encoded.

Passing handler will change how metadata is turned into text. A handler passed as an argument will override post.handler, with YAMLHandler used as a default.

>>> post = frontmatter.load('tests/yaml/hello-world.txt')
>>> print(frontmatter.dumps(post)) 
---
layout: post
title: Hello, world!
---

Well, hello there, world.

post = frontmatter.load('tests/yaml/hello-world.txt')
print(frontmatter.dumps(post))

---
layout: post
title: Hello, world!
---

Well, hello there, world.

Post objects

class frontmatter.Post(content, handler=None, **metadata)

A post contains content and metadata from Front Matter. This is what gets returned by load and loads. Passing this to dump or dumps will turn it back into text.

For convenience, metadata values are available as proxied item lookups.

__delitem__(name)

Delete a metadata key

__getitem__(name)

Get metadata key

__setitem__(name, value)

Set a metadata key

get(key, default=None)

Get a key, fallback to default

keys()

Return metadata keys

to_dict()

Post as a dict, for serializing

values()

Return metadata values

Handlers

class frontmatter.default_handlers.BaseHandler(fm_boundary=None, start_delimiter=None, end_delimiter=None)

BaseHandler lays out all the steps to detecting, splitting, parsing and exporting front matter metadata.

All default handlers are subclassed from BaseHandler.

detect(text)

Decide whether this handler can parse the given text, and return True or False.

Note that this is not called when passing a handler instance to frontmatter.load or loads.

export(metadata, **kwargs)

Turn metadata back into text

format(post, **kwargs)

Turn a post into a string, used in frontmatter.dumps

load(fm)

Parse frontmatter and return a dict

split(text)

Split text into frontmatter and content

class frontmatter.default_handlers.YAMLHandler(fm_boundary=None, start_delimiter=None, end_delimiter=None)

Load and export YAML metadata. By default, this handler uses YAML’s “safe” mode, though it’s possible to override that.

class frontmatter.default_handlers.JSONHandler(fm_boundary=None, start_delimiter=None, end_delimiter=None)

Load and export JSON metadata.

Note that changing START_DELIMITER or END_DELIMITER may break JSON parsing.

class frontmatter.default_handlers.TOMLHandler(fm_boundary=None, start_delimiter=None, end_delimiter=None)

Load and export TOML metadata.

By default, split based on +++.