Skip to main content

Parse and manage posts with YAML (or other) frontmatter

Project description

Python Frontmatter

Jekyll-style YAML front matter offers a useful way to add arbitrary, structured metadata to text documents, regardless of type.

This is a small package to load and parse files (or just text) with YAML (or JSON, TOML or other) front matter.

Tests PyPI

Documentation

Install:

pip install python-frontmatter

Usage:

>>> import frontmatter

Load a post from a filename:

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

Or a file (or file-like object):

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

Or load from text:

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

If the file has a Byte-Order Mark (BOM), strip it off first. An easy way to do this is by using the utf-8-sig encoding:

>>> with open('tests/yaml/hello-world.txt', encoding="utf-8-sig") as f:
...     post = frontmatter.load(f)

Access content:

>>> print(post.content)
Well, hello there, world.

# this works, too
>>> print(post)
Well, hello there, world.

Use metadata (metadata gets proxied as post keys):

>>> print(post['title'])
Hello, world!

Metadata is a dictionary, with some handy proxies:

>>> sorted(post.keys())
['layout', 'title']

>>> from pprint import pprint
>>> post['excerpt'] = 'tl;dr'
>>> pprint(post.metadata)
{'excerpt': 'tl;dr', 'layout': 'post', 'title': 'Hello, world!'}

If you don't need the whole post object, just parse:

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

Write back to plain text, too:

>>> print(frontmatter.dumps(post)) # doctest: +NORMALIZE_WHITESPACE
---
excerpt: tl;dr
layout: post
title: Hello, world!
---
Well, hello there, world.

Or write to a file (or file-like object):

>>> from io import BytesIO
>>> f = BytesIO()
>>> frontmatter.dump(post, f)
>>> print(f.getvalue().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE
---
excerpt: tl;dr
layout: post
title: Hello, world!
---
Well, hello there, world.

For more examples, see files in the tests/ directory. Each sample file has a corresponding .result.json file showing the expected parsed output. See also the examples/ directory, which covers more ways to customize input and output.

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

python-frontmatter-1.1.0.tar.gz (16.3 kB view hashes)

Uploaded Source

Built Distribution

python_frontmatter-1.1.0-py3-none-any.whl (9.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