python-frontmatter VS pyyaml

❯ inspect(frontmatter.load("pages/til/python-frontmatter.md")) ╭────────────────────────────────────────────────────────── ───────────────────────────────────────────────────────────╮ │ A post contains content and metadata from Front Matter. This is what gets │ │ returned by :py:func:`load ` and :py:func:`loads `. │ │ Passing this to :py:func:`dump ` or :py:func:`dumps ` │ │ will turn it back into text. │ │ │ │ ╭─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ │ │ │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ │ │ content = "I use a package\n[eyeseast/python-frontmatter](https://github.com/eyeseast/python-frontmatter)\nto load files with frontmatter in │ │ them. Its a handy package that allows you to\nload files with structured frontmatter (yaml, json, or toml).\n\n## Install\n\nIt's │ │ on pypi, so you can install it into your virtual environment with pip.\n\n``` {% endraw %} bash\npython -m pip install │ │ python-frontmatter\n {% raw %} ```\n\n## 🙋 What's Frontmatter\n\nFrontmatter is a handy way to add metadata to your plain text files. │ │ It's\nquite common to have yaml frontmatter in markdown. All of my blog posts have\nyaml frontmatter to give the post metadata such │ │ as post date, tags, title, and\ntemplate. dev.to is a popular developer blogging platform that also builds all\nof its posts with │ │ markdown and yaml frontmatter.\n\n## Let's see an example\n\nHere is the exact frontmatter for this post you are reading on my │ │ site.\n\n``` {% endraw %} markdown\n---\ndate: 2022-03-24 03:18:48.631729\ntemplateKey: til\ntitle: How I load Markdown in Python\ntags:\n - │ │ linux\n - python\n\n---\n\nThis is where the markdown content for the post goes.\n {% raw %} ```\n\n## So it's yaml\n\nyaml is the most │ │ commmon, but\n[eyeseast/python-frontmatter](https://github.com/eyeseast/python-frontmatter)\nalso │ │ supports\n[Handlers](https://python-frontmatter.readthedocs.io/en/latest/handlers.html?highlight=toml#module-frontmatter.default_ha… │ │ toml and json.\n\nIf you want a good set of examples of yaml\n[learnxinyminutes](https://learnxinyminutes.com/docs/yaml/) has a │ │ fantastic set\nof examples in one page.\n\n## How to load yaml frontmatter in python" │ │ handler = │ │ metadata = { │ │ 'date': datetime.datetime(2022, 3, 24, 3, 18, 48, 631729), │ │ 'templateKey': 'til', │ │ 'title': 'How I load Markdown in Python', │ │ 'tags': ['linux', 'python', 'python'] │ │ } │ ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Chris Amico - For parsing front matter from Markdown file

Then I went to Uncle Google for cython and got this issue from last year: https://github.com/yaml/pyyaml/issues/724 Good news - it's closed!

PyYAML knew about the breakage since january 2022[0], and nothing really happened. After a year and a half with lots of alphas and betas, I don't think there is much cython could do, short of fixing PyYAML themselves.

[0]: https://github.com/yaml/pyyaml/issues/601

They did finally change the default, in PyYAML 6, after many many bugs pointing out that their previous approach is broken (including one by yours truly), so the default is now safe.

Note some parsers, most notably pyyaml are still at yaml 1.1, because 13 years is just not enough time to update it.

That part of the YAML 1.2 spec is in conflict with reality, though. The base of YAML 1.1 documents is large enough that a backwards-incompatible change to default behavior is for practical purposes impossible.

YAML 1.1 was released in 2005, and 1.2 in 2009 -- only four years later. But here we are, in 2022, and YAML 1.1 is still the default (in many cases, only) version supported. That's why the "Norway problem" persists -- it's not possible for the parser to know whether an un-versioned YAML document containing "a: no" should parse the same as {"a": false} or {"a": "no"}.

Python (PyYAML) doesn't support 1.2 yet: https://github.com/yaml/pyyaml/issues/116

Ruby (Psych) ditto -- I can't even find a tracking issue to enable it.

Go (go-yaml) is a mixture of YAML 1.1 and 1.2, depending on the author's preferences.

Also, as a rough guideline, you can't have a backwards-incompatible revision of a versioned spec declare that it's the new default version, because that breaks all existing users.

Many parsers either default to YAML pre-1.2 or do not even expose a YAML 1.2 option. PyYAML has no 1.2 option, for example. So unless Ansible is using something other than PyYAML...

Relevant (open) PR: https://github.com/yaml/pyyaml/pull/555