# 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.
Raw data
{
"_id": null,
"home_page": "https://github.com/eyeseast/python-frontmatter",
"name": "python-frontmatter",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "frontmatter",
"author": "Chris Amico",
"author_email": "eyeseast@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/96/de/910fa208120314a12f9a88ea63e03707261692af782c99283f1a2c8a5e6f/python-frontmatter-1.1.0.tar.gz",
"platform": null,
"description": "# Python Frontmatter\n\n[Jekyll](http://jekyllrb.com/)-style YAML front matter offers a useful way to add arbitrary, structured metadata to text documents, regardless of type.\n\nThis is a small package to load and parse files (or just text) with YAML (or JSON, TOML or other) front matter.\n\n[](https://github.com/eyeseast/python-frontmatter/actions?query=workflow%3ATest)\n[](https://pypi.org/project/python-frontmatter/)\n\n**[Documentation](https://python-frontmatter.readthedocs.io/en/latest/)**\n\n## Install:\n\n pip install python-frontmatter\n\n## Usage:\n\n```python\n>>> import frontmatter\n\n```\n\nLoad a post from a filename:\n\n```python\n>>> post = frontmatter.load('tests/yaml/hello-world.txt')\n\n```\n\nOr a file (or file-like object):\n\n```python\n>>> with open('tests/yaml/hello-world.txt') as f:\n... post = frontmatter.load(f)\n\n```\n\nOr load from text:\n\n```python\n>>> with open('tests/yaml/hello-world.txt') as f:\n... post = frontmatter.loads(f.read())\n\n```\n\nIf 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:\n\n```python\n>>> with open('tests/yaml/hello-world.txt', encoding=\"utf-8-sig\") as f:\n... post = frontmatter.load(f)\n\n```\n\nAccess content:\n\n```python\n>>> print(post.content)\nWell, hello there, world.\n\n# this works, too\n>>> print(post)\nWell, hello there, world.\n\n```\n\nUse metadata (metadata gets proxied as post keys):\n\n```python\n>>> print(post['title'])\nHello, world!\n\n```\n\nMetadata is a dictionary, with some handy proxies:\n\n```python\n>>> sorted(post.keys())\n['layout', 'title']\n\n>>> from pprint import pprint\n>>> post['excerpt'] = 'tl;dr'\n>>> pprint(post.metadata)\n{'excerpt': 'tl;dr', 'layout': 'post', 'title': 'Hello, world!'}\n\n```\n\nIf you don't need the whole post object, just parse:\n\n```python\n>>> with open('tests/yaml/hello-world.txt') as f:\n... metadata, content = frontmatter.parse(f.read())\n>>> print(metadata['title'])\nHello, world!\n\n```\n\nWrite back to plain text, too:\n\n```python\n>>> print(frontmatter.dumps(post)) # doctest: +NORMALIZE_WHITESPACE\n---\nexcerpt: tl;dr\nlayout: post\ntitle: Hello, world!\n---\nWell, hello there, world.\n\n```\n\nOr write to a file (or file-like object):\n\n```python\n>>> from io import BytesIO\n>>> f = BytesIO()\n>>> frontmatter.dump(post, f)\n>>> print(f.getvalue().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE\n---\nexcerpt: tl;dr\nlayout: post\ntitle: Hello, world!\n---\nWell, hello there, world.\n\n```\n\nFor 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.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parse and manage posts with YAML (or other) frontmatter",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/eyeseast/python-frontmatter"
},
"split_keywords": [
"frontmatter"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "49873c8da047b3ec5f99511d1b4d7a5bc72d4b98751c7e78492d14dc736319c5",
"md5": "d96feb205fa163c7eacf5cf5ccb40c36",
"sha256": "335465556358d9d0e6c98bbeb69b1c969f2a4a21360587b9873bfc3b213407c1"
},
"downloads": -1,
"filename": "python_frontmatter-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d96feb205fa163c7eacf5cf5ccb40c36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 9834,
"upload_time": "2024-01-16T18:50:00",
"upload_time_iso_8601": "2024-01-16T18:50:00.911860Z",
"url": "https://files.pythonhosted.org/packages/49/87/3c8da047b3ec5f99511d1b4d7a5bc72d4b98751c7e78492d14dc736319c5/python_frontmatter-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "96de910fa208120314a12f9a88ea63e03707261692af782c99283f1a2c8a5e6f",
"md5": "f0d26bc7456a2ad868a6b5e5df2d6ee4",
"sha256": "7118d2bd56af9149625745c58c9b51fb67e8d1294a0c76796dafdc72c36e5f6d"
},
"downloads": -1,
"filename": "python-frontmatter-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f0d26bc7456a2ad868a6b5e5df2d6ee4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16256,
"upload_time": "2024-01-16T18:50:04",
"upload_time_iso_8601": "2024-01-16T18:50:04.052369Z",
"url": "https://files.pythonhosted.org/packages/96/de/910fa208120314a12f9a88ea63e03707261692af782c99283f1a2c8a5e6f/python-frontmatter-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-16 18:50:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eyeseast",
"github_project": "python-frontmatter",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "python-frontmatter"
}
JSON
