{"id":1873,"library":"python-frontmatter","title":"Python Frontmatter","description":"Parse and manage posts with YAML (or other) frontmatter. This library simplifies reading and writing content files that include metadata blocks, typically used in static site generators or content management systems. Current version is 1.1.0. Releases are infrequent but stable, primarily focused on maintenance, Python version compatibility, and type hinting.","status":"active","version":"1.1.0","language":"en","source_language":"en","source_url":"https://github.com/eyeseast/python-frontmatter","tags":["frontmatter","yaml","markdown","parsing","blogging","static-site"],"install":[{"cmd":"pip install python-frontmatter","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Used for parsing and dumping YAML frontmatter, which is the default handler.","package":"PyYAML","optional":false}],"imports":[{"symbol":"load","correct":"from frontmatter import load"},{"symbol":"loads","correct":"from frontmatter import loads"},{"symbol":"dumps","correct":"from frontmatter import dumps"},{"symbol":"Post","correct":"from frontmatter import Post"},{"note":"The class is capitalized; direct `frontmatter` usually refers to the module, not an instance.","wrong":"from frontmatter import frontmatter","symbol":"Frontmatter","correct":"from frontmatter import Frontmatter"},{"note":"Required if explicitly specifying the YAML handler, otherwise it's the default for `load`/`loads`.","symbol":"YAMLHandler","correct":"from frontmatter.handlers import YAMLHandler"},{"note":"Required to parse JSON frontmatter explicitly.","symbol":"JSONHandler","correct":"from frontmatter.handlers import JSONHandler"},{"note":"Required to parse TOML frontmatter explicitly.","symbol":"TOMLHandler","correct":"from frontmatter.handlers import TOMLHandler"}],"quickstart":{"code":"import frontmatter\n\n# Example content with YAML frontmatter\ncontent_string = '''---\ntitle: My Awesome Post\nauthor: John Doe\ntags:\n  - python\n  - frontmatter\n---\n\nThis is the *body* of my post.\nIt can contain anything.\n'''\n\n# Load from a string\npost = frontmatter.loads(content_string)\n\nprint(f\"Title: {post['title']}\")\nprint(f\"Author: {post.metadata.get('author')}\")\nprint(f\"Content:\\n{post.content}\")\n\n# Modify the post\npost['status'] = 'published'\npost.metadata['tags'].append('documentation')\npost.content = \"New content! \" + post.content\n\n# Dump back to a string\nmodified_content = frontmatter.dumps(post)\nprint(\"\\n--- Modified Content ---\\n\")\nprint(modified_content)\n\n# Example using JSON handler\njson_content_string = '''---\n{\\\"title\\\": \\\"JSON Post\\\", \\\"lang\\\": \\\"en\\\"}\n---\n\nBody of JSON post.\n'''\njson_post = frontmatter.loads(json_content_string, handler=frontmatter.handlers.JSONHandler)\nprint(f\"\\nJSON Post Title: {json_post['title']}\")","lang":"python","description":"This quickstart demonstrates how to load content with YAML frontmatter from a string, access its metadata and content, modify them, and dump the post back into a string. It also shows how to explicitly use a `JSONHandler` for different frontmatter formats."},"warnings":[{"fix":"Upgrade to Python 3.6+ or use an older version of the library if constrained to older Python environments.","message":"Version 1.0.0 removed official support for Python 2.x, Python 3.4, and Python 3.5. Users on these older Python versions should stick to `python-frontmatter<1.0.0`.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use `frontmatter.load(file_object)` for files and `frontmatter.loads(string_data)` for strings.","message":"The `load()` function expects a file-like object (e.g., from `open()`), while `loads()` expects a string. Mixing them up is a common error.","severity":"gotcha","affected_versions":"All"},{"fix":"Import the relevant handler (e.g., `from frontmatter.handlers import JSONHandler`) and pass it to the loading function: `frontmatter.loads(my_string, handler=JSONHandler)`.","message":"By default, `load` and `loads` parse frontmatter using the YAML format. If your content uses JSON or TOML frontmatter, you must explicitly provide the correct handler.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}