python-frontmatter 1.1.0__tar.gz → 1.3.0__tar.gz

{python-frontmatter-1.1.0/python_frontmatter.egg-info → python_frontmatter-1.3.0}/PKG-INFO

@@ -1,30 +1,41 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-frontmatter
-Version: 1.1.0
+Version: 1.3.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
+Author: Chris Amico
+Author-email: Chris Amico <eyeseast@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
 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
-Provides-Extra: test
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: pyyaml
+Requires-Dist: sphinx ; extra == 'docs'
+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'
+Requires-Dist: toml ; extra == 'toml'
+Requires-Python: >=3.10
+Project-URL: repository, https://github.com/eyeseast/python-frontmatter
+Project-URL: issues, https://github.com/eyeseast/python-frontmatter/issues
+Project-URL: documentation, http://python-frontmatter.rtfd.io
 Provides-Extra: docs
-License-File: LICENSE
+Provides-Extra: test
+Provides-Extra: toml
+Description-Content-Type: text/markdown
 
 # 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.
+[Front matter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) 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.
 
@@ -35,7 +46,16 @@ This is a small package to load and parse files (or just text) with YAML (or JSO
 
 ## Install:
 
-    pip install python-frontmatter
+```shell
+# with pip
+pip install python-frontmatter
+
+# or uv
+uv add python-frontmatter
+
+# local development, with uv
+uv sync
+```
 
 ## Usage:
 
@@ -134,10 +154,10 @@ Well, hello there, world.
 Or write to a file (or file-like object):
 
 ```python
->>> from io import BytesIO
->>> f = BytesIO()
+>>> from io import StringIO
+>>> f = StringIO()
 >>> frontmatter.dump(post, f)
->>> print(f.getvalue().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE
+>>> print(f.getvalue()) # doctest: +NORMALIZE_WHITESPACE
 ---
 excerpt: tl;dr
 layout: post

{python-frontmatter-1.1.0 → python_frontmatter-1.3.0}/README.md

@@ -1,6 +1,6 @@
 # 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.
+[Front matter](https://docs.github.com/en/contributing/writing-for-github-docs/using-yaml-frontmatter) 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.
 
@@ -11,7 +11,16 @@ This is a small package to load and parse files (or just text) with YAML (or JSO
 
 ## Install:
 
-    pip install python-frontmatter
+```shell
+# with pip
+pip install python-frontmatter
+
+# or uv
+uv add python-frontmatter
+
+# local development, with uv
+uv sync
+```
 
 ## Usage:
 
@@ -110,10 +119,10 @@ Well, hello there, world.
 Or write to a file (or file-like object):
 
 ```python
->>> from io import BytesIO
->>> f = BytesIO()
+>>> from io import StringIO
+>>> f = StringIO()
 >>> frontmatter.dump(post, f)
->>> print(f.getvalue().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE
+>>> print(f.getvalue()) # doctest: +NORMALIZE_WHITESPACE
 ---
 excerpt: tl;dr
 layout: post

{python-frontmatter-1.1.0 → python_frontmatter-1.3.0}/frontmatter/__init__.py

@@ -4,12 +4,13 @@ Python Frontmatter: Parse and manage posts with YAML frontmatter
 """
 from __future__ import annotations
 
-import codecs
 import io
-from typing import TYPE_CHECKING, Iterable
+import pathlib
+from os import PathLike
+from typing import TYPE_CHECKING, Iterable, TextIO
 
-from .util import u
-from .default_handlers import YAMLHandler, JSONHandler, TOMLHandler
+from .default_handlers import JSONHandler, TOMLHandler, YAMLHandler
+from .util import can_open, is_readable, is_writable, u
 
 
 if TYPE_CHECKING:
@@ -96,7 +97,7 @@ def parse(
     return metadata, content.strip()
 
 
-def check(fd: str | io.IOBase, encoding: str = "utf-8") -> bool:
+def check(fd: TextIO | PathLike[str] | str, encoding: str = "utf-8") -> bool:
     """
     Check if a file-like object or filename has a frontmatter,
     return True if exists, False otherwise.
@@ -109,13 +110,17 @@ def check(fd: str | io.IOBase, encoding: str = "utf-8") -> bool:
         True
 
     """
-    if hasattr(fd, "read"):
+    if is_readable(fd):
         text = fd.read()
 
-    else:
-        with codecs.open(fd, "r", encoding) as f:
+    elif can_open(fd):
+        with open(fd, "r", encoding=encoding) as f:
             text = f.read()
 
+    else:
+        # no idea what we're dealing with
+        return False
+
     return checks(text, encoding)
 
 
@@ -138,7 +143,7 @@ def checks(text: str, encoding: str = "utf-8") -> bool:
 
 
 def load(
-    fd: str | io.IOBase,
+    fd: str | io.IOBase | pathlib.Path,
     encoding: str = "utf-8",
     handler: BaseHandler | None = None,
     **defaults: object,
@@ -154,13 +159,16 @@ def load(
         ...     post = frontmatter.load(f)
 
     """
-    if hasattr(fd, "read"):
+    if is_readable(fd):
         text = fd.read()
 
-    else:
-        with codecs.open(fd, "r", encoding) as f:
+    elif can_open(fd):
+        with open(fd, "r", encoding=encoding) as f:
             text = f.read()
 
+    else:
+        raise ValueError(f"Cannot open filename using type {type(fd)}")
+
     handler = handler or detect_format(text, handlers)
     return loads(text, encoding, handler, **defaults)
 
@@ -188,7 +196,7 @@ def loads(
 
 def dump(
     post: Post,
-    fd: str | io.IOBase,
+    fd: str | PathLike[str] | TextIO,
     encoding: str = "utf-8",
     handler: BaseHandler | None = None,
     **kwargs: object,
@@ -199,11 +207,11 @@ def dump(
 
     ::
 
-        >>> from io import BytesIO
+        >>> from io import StringIO
         >>> post = frontmatter.load('tests/yaml/hello-world.txt')
-        >>> f = BytesIO()
+        >>> f = StringIO()
         >>> frontmatter.dump(post, f)
-        >>> print(f.getvalue().decode('utf-8'))
+        >>> print(f.getvalue())
         ---
         layout: post
         title: Hello, world!
@@ -214,11 +222,11 @@ def dump(
 
     .. testcode::
 
-        from io import BytesIO
+        from io import StringIO
         post = frontmatter.load('tests/yaml/hello-world.txt')
-        f = BytesIO()
+        f = StringIO()
         frontmatter.dump(post, f)
-        print(f.getvalue().decode('utf-8'))
+        print(f.getvalue())
 
     .. testoutput::
 
@@ -231,13 +239,16 @@ def dump(
 
     """
     content = dumps(post, handler, **kwargs)
-    if hasattr(fd, "write"):
-        fd.write(content.encode(encoding))
+    if is_writable(fd):
+        fd.write(content)
 
-    else:
-        with codecs.open(fd, "w", encoding) as f:
+    elif can_open(fd):
+        with open(fd, "w", encoding=encoding) as f:
             f.write(content)
 
+    else:
+        raise ValueError(f"Cannot open filename using type {type(fd)}")
+
 
 def dumps(post: Post, handler: BaseHandler | None = None, **kwargs: object) -> str:
     """
@@ -278,6 +289,7 @@ def dumps(post: Post, handler: BaseHandler | None = None, **kwargs: object) -> s
     if handler is None:
         handler = getattr(post, "handler", None) or YAMLHandler()
 
+    assert handler is not None
     return handler.format(post, **kwargs)
 
 

{python-frontmatter-1.1.0 → python_frontmatter-1.3.0}/frontmatter/default_handlers.py

@@ -8,8 +8,8 @@ By default, ``frontmatter`` reads and writes YAML metadata. But maybe
 you don't like YAML. Maybe enjoy writing metadata in JSON, or TOML, or
 some other exotic markup not yet invented. For this, there are handlers.
 
-This module includes handlers for YAML, JSON and TOML, as well as a 
-:py:class:`BaseHandler <frontmatter.default_handlers.BaseHandler>` that 
+This module includes handlers for YAML, JSON and TOML, as well as a
+:py:class:`BaseHandler <frontmatter.default_handlers.BaseHandler>` that
 outlines the basic API and can be subclassed to deal with new formats.
 
 **Note**: The TOML handler is only available if the `toml <https://pypi.org/project/toml/>`_
@@ -32,10 +32,10 @@ A handler needs to do four things:
 
 An example:
 
-Calling :py:func:`frontmatter.load <frontmatter.load>` (or :py:func:`loads <frontmatter.loads>`) 
-with the ``handler`` argument tells frontmatter which handler to use. 
-The handler instance gets saved as an attribute on the returned post 
-object. By default, calling :py:func:`frontmatter.dumps <frontmatter.dumps>` 
+Calling :py:func:`frontmatter.load <frontmatter.load>` (or :py:func:`loads <frontmatter.loads>`)
+with the ``handler`` argument tells frontmatter which handler to use.
+The handler instance gets saved as an attribute on the returned post
+object. By default, calling :py:func:`frontmatter.dumps <frontmatter.dumps>`
 on the post will use the attached handler.
 
 
@@ -67,7 +67,7 @@ on the post will use the attached handler.
     <BLANKLINE>
     And this shouldn't break.
 
-Passing a new handler to :py:func:`frontmatter.dumps <frontmatter.dumps>` 
+Passing a new handler to :py:func:`frontmatter.dumps <frontmatter.dumps>`
 (or :py:func:`dump <frontmatter.dump>`) changes the export format:
 
 ::
@@ -283,6 +283,7 @@ class JSONHandler(BaseHandler):
     END_DELIMITER = ""
 
     def split(self, text: str) -> tuple[str, str]:
+        assert self.FM_BOUNDARY is not None
         _, fm, content = self.FM_BOUNDARY.split(text, 2)
         return "{" + fm + "}", content
 
@@ -298,7 +299,7 @@ class JSONHandler(BaseHandler):
 
 if toml:
 
-    class TOMLHandler(BaseHandler):
+    class TOMLHandler(BaseHandler):  # pyright: ignore
         """
         Load and export TOML metadata.
 

python_frontmatter-1.3.0/frontmatter/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561. This package uses inline types.

python_frontmatter-1.3.0/frontmatter/util.py

@@ -0,0 +1,31 @@
+# -*- coding: utf-8 -*-
+"""
+Utilities for handling unicode and other repetitive bits
+"""
+from os import PathLike
+from typing import TypeGuard, TextIO
+
+
+def is_readable(fd: object) -> TypeGuard[TextIO]:
+    return callable(getattr(fd, "read", None))
+
+
+def is_writable(fd: object) -> TypeGuard[TextIO]:
+    return callable(getattr(fd, "write", None))
+
+
+def can_open(fd: object) -> TypeGuard[str | PathLike[str]]:
+    return isinstance(fd, str) or isinstance(fd, PathLike)
+
+
+def u(text: str | bytes, encoding: str = "utf-8") -> str:
+    "Return unicode text, no matter what"
+
+    if isinstance(text, bytes):
+        text_str: str = text.decode(encoding)
+    else:
+        text_str = str(text)
+
+    # it's already unicode
+    text_str = text_str.replace("\r\n", "\n")
+    return text_str

python_frontmatter-1.3.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "python-frontmatter"
+version = "1.3.0"
+description = "Parse and manage posts with YAML (or other) frontmatter"
+readme = "README.md"
+authors = [{ name = "Chris Amico", email = "eyeseast@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = ["PyYAML"]
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["frontmatter"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Natural Language :: English",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+[project.urls]
+repository = "https://github.com/eyeseast/python-frontmatter"
+issues = "https://github.com/eyeseast/python-frontmatter/issues"
+documentation = "http://python-frontmatter.rtfd.io"
+
+[project.optional-dependencies]
+test = ["pytest", "toml", "pyaml", "mypy", "types-PyYAML", "types-toml"]
+docs = ["sphinx"]
+toml = ["toml"]
+
+[dependency-groups]
+dev = [
+    "pytest",
+    "toml",
+    "pyaml",
+    "mypy",
+    "types-PyYAML",
+    "types-toml",
+    "sphinx",
+]
+
+
+[build-system]
+requires = ["uv_build>=0.11.15,<0.12"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+module-name = "frontmatter"

python-frontmatter-1.1.0/MANIFEST.in

@@ -1,6 +0,0 @@
-include LICENSE
-include README.md
-
-recursive-include tests *
-
-exclude *.py[co]

python-frontmatter-1.1.0/PKG-INFO

@@ -1,150 +0,0 @@
-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
-Provides-Extra: test
-Provides-Extra: docs
-License-File: LICENSE
-
-# 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.
-
-[![Tests](https://github.com/eyeseast/python-frontmatter/workflows/Test/badge.svg)](https://github.com/eyeseast/python-frontmatter/actions?query=workflow%3ATest)
-[![PyPI](https://img.shields.io/pypi/v/python-frontmatter.svg)](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.

python-frontmatter-1.1.0/frontmatter/util.py

@@ -1,18 +0,0 @@
-# -*- coding: utf-8 -*-
-"""
-Utilities for handling unicode and other repetitive bits
-"""
-from typing import AnyStr
-
-
-def u(text: AnyStr, encoding: str = "utf-8") -> str:
-    "Return unicode text, no matter what"
-
-    if isinstance(text, bytes):
-        text_str: str = text.decode(encoding)
-    else:
-        text_str = text
-
-    # it's already unicode
-    text_str = text_str.replace("\r\n", "\n")
-    return text_str

python-frontmatter-1.1.0/python_frontmatter.egg-info/SOURCES.txt

@@ -1,40 +0,0 @@
-LICENSE
-MANIFEST.in
-README.md
-setup.py
-frontmatter/__init__.py
-frontmatter/conftest.py
-frontmatter/default_handlers.py
-frontmatter/util.py
-python_frontmatter.egg-info/PKG-INFO
-python_frontmatter.egg-info/SOURCES.txt
-python_frontmatter.egg-info/dependency_links.txt
-python_frontmatter.egg-info/not-zip-safe
-python_frontmatter.egg-info/requires.txt
-python_frontmatter.egg-info/top_level.txt
-tests/stub_tests.py
-tests/test_docs.py
-tests/test_files.py
-tests/unit_test.py
-tests/empty/empty-frontmatter.result.json
-tests/empty/empty-frontmatter.txt
-tests/empty/no-frontmatter.result.json
-tests/empty/no-frontmatter.txt
-tests/json/hello-json.md
-tests/json/hello-json.result.json
-tests/toml/hello-toml.md
-tests/toml/hello-toml.result.json
-tests/yaml/chinese.result.json
-tests/yaml/chinese.txt
-tests/yaml/extra-dash.result.json
-tests/yaml/extra-dash.txt
-tests/yaml/extra-space.result.json
-tests/yaml/extra-space.txt
-tests/yaml/hello-markdown.md
-tests/yaml/hello-markdown.result.json
-tests/yaml/hello-world.result.json
-tests/yaml/hello-world.txt
-tests/yaml/network-diagrams.md
-tests/yaml/network-diagrams.result.json
-tests/yaml/unpretty.md
-tests/yaml/unpretty.result.json

python-frontmatter-1.1.0/python_frontmatter.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

python-frontmatter-1.1.0/python_frontmatter.egg-info/not-zip-safe

@@ -1 +0,0 @@
-

python-frontmatter-1.1.0/python_frontmatter.egg-info/requires.txt

@@ -1,12 +0,0 @@
-PyYAML
-
-[docs]
-sphinx
-
-[test]
-pytest
-toml
-pyaml
-mypy
-types-PyYAML
-types-toml

python-frontmatter-1.1.0/python_frontmatter.egg-info/top_level.txt

@@ -1 +0,0 @@
-frontmatter

python-frontmatter-1.1.0/setup.cfg

@@ -1,4 +0,0 @@
-[egg_info]
-tag_build = 
-tag_date = 0
-