Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/eyeseast/python-frontmatter
Parse and manage posts with YAML (or other) frontmatter
https://github.com/eyeseast/python-frontmatter
frontmatter python yaml
Last synced: about 5 hours ago
JSON representation
Parse and manage posts with YAML (or other) frontmatter
- Host: GitHub
- URL: https://github.com/eyeseast/python-frontmatter
- Owner: eyeseast
- License: mit
- Created: 2014-09-15T01:51:06.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2024-01-16T18:49:16.000Z (about 1 year ago)
- Last Synced: 2024-04-14T13:11:03.328Z (10 months ago)
- Topics: frontmatter, python, yaml
- Language: Python
- Homepage: http://python-frontmatter.rtfd.io
- Size: 146 KB
- Stars: 316
- Watchers: 7
- Forks: 41
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# Python Frontmatter
[Jekyll](http://jekyllrb.com/)-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.
[](https://github.com/eyeseast/python-frontmatter/actions?query=workflow%3ATest)
[](https://pypi.org/project/python-frontmatter/)
**[Documentation](https://python-frontmatter.readthedocs.io/en/latest/)**
## Install:
pip install python-frontmatter
## Usage:
```python
>>> import frontmatter
```
Load a post from a filename:
```python
>>> post = frontmatter.load('tests/yaml/hello-world.txt')
```
Or a file (or file-like object):
```python
>>> with open('tests/yaml/hello-world.txt') as f:
... post = frontmatter.load(f)
```
Or load from text:
```python
>>> with open('tests/yaml/hello-world.txt') as f:
... post = frontmatter.loads(f.read())
```
If the file has a [Byte-Order Mark](https://en.wikipedia.org/wiki/Byte_order_mark) (BOM), strip it off first. An easy way to do this is by using the [`utf-8-sig`](https://docs.python.org/3/library/codecs.html?highlight=utf%208%20sig#module-encodings.utf_8_sig) encoding:
```python
>>> with open('tests/yaml/hello-world.txt', encoding="utf-8-sig") as f:
... post = frontmatter.load(f)
```
Access content:
```python
>>> print(post.content)
Well, hello there, world.
# this works, too
>>> print(post)
Well, hello there, world.
```
Use metadata (metadata gets proxied as post keys):
```python
>>> print(post['title'])
Hello, world!
```
Metadata is a dictionary, with some handy proxies:
```python
>>> 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:
```python
>>> 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:
```python
>>> 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):
```python
>>> 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.