158 lines
4 KiB
Text
158 lines
4 KiB
Text
Metadata-Version: 2.1
|
|
Name: python-frontmatter
|
|
Version: 1.1.0
|
|
Summary: Parse and manage posts with YAML (or other) frontmatter
|
|
Home-page: https://github.com/eyeseast/python-frontmatter
|
|
Author: Chris Amico
|
|
Author-email: eyeseast@gmail.com
|
|
License: MIT
|
|
Keywords: frontmatter
|
|
Classifier: Development Status :: 5 - Production/Stable
|
|
Classifier: Intended Audience :: Developers
|
|
Classifier: License :: OSI Approved :: MIT License
|
|
Classifier: Natural Language :: English
|
|
Classifier: Programming Language :: Python :: 3
|
|
Classifier: Programming Language :: Python :: 3.8
|
|
Classifier: Programming Language :: Python :: 3.9
|
|
Classifier: Programming Language :: Python :: 3.10
|
|
Classifier: Programming Language :: Python :: 3.11
|
|
Classifier: Programming Language :: Python :: 3.12
|
|
Description-Content-Type: text/markdown
|
|
License-File: LICENSE
|
|
Requires-Dist: PyYAML
|
|
Provides-Extra: docs
|
|
Requires-Dist: sphinx ; extra == 'docs'
|
|
Provides-Extra: test
|
|
Requires-Dist: pytest ; extra == 'test'
|
|
Requires-Dist: toml ; extra == 'test'
|
|
Requires-Dist: pyaml ; extra == 'test'
|
|
Requires-Dist: mypy ; extra == 'test'
|
|
Requires-Dist: types-PyYAML ; extra == 'test'
|
|
Requires-Dist: types-toml ; extra == 'test'
|
|
|
|
# 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.
|