python-frontmatter 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

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)
 
 

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.
 

frontmatter/py.typed

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

frontmatter/util.py

@@ -2,16 +2,29 @@
 """
 Utilities for handling unicode and other repetitive bits
 """
-from typing import AnyStr
+from os import PathLike
+from typing import TypeGuard, TextIO
 
 
-def u(text: AnyStr, encoding: str = "utf-8") -> str:
+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 = text
+        text_str = str(text)
 
     # it's already unicode
     text_str = text_str.replace("\r\n", "\n")

{python_frontmatter-1.1.0.dist-info → python_frontmatter-1.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: python-frontmatter
-Version: 1.1.0
+Version: 1.2.0
 Summary: Parse and manage posts with YAML (or other) frontmatter
 Home-page: https://github.com/eyeseast/python-frontmatter
 Author: Chris Amico
@@ -12,23 +12,35 @@ 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
+Classifier: Programming Language :: Python :: 3.13
 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'
+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"
+Provides-Extra: docs
+Requires-Dist: sphinx; extra == "docs"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: summary
 
 # Python Frontmatter
 
@@ -142,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.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+frontmatter/__init__.py,sha256=PtzuMdiQeiEq3r6FLgzDjT1pxkphlSt40VKtL-jUokY,9177
+frontmatter/conftest.py,sha256=LxRFalFdwQA2RtSYqCSB7V7THG7rHt5zZmMEzJlf0DA,220
+frontmatter/default_handlers.py,sha256=ucN_cv4nnPfRevZDZYbtio-r1aITcUZI4qBCKXWOAxA,9717
+frontmatter/py.typed,sha256=DtCsIDq6KOv2NOEdQjTbeMWJKRh6ZEL2E-6Mf1RLeMA,59
+frontmatter/util.py,sha256=utw8plpS0Ld6CJkY02k_VpT1vfiVm5ai1npsKR5Hius,784
+python_frontmatter-1.2.0.dist-info/licenses/LICENSE,sha256=LmiF34zbpRujrv40WY5ohW8bJGjR5YxxlhQAS4b7Q9U,1077
+python_frontmatter-1.2.0.dist-info/METADATA,sha256=Rn5Q4VXKA6eZx-lhGd8eeklpUBMoqjTFpknGs0mkD5k,4370
+python_frontmatter-1.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_frontmatter-1.2.0.dist-info/top_level.txt,sha256=o5ywgaMiFjjXFwNlYulDy2RAulwnLsZCmYQn0jy7w7M,12
+python_frontmatter-1.2.0.dist-info/RECORD,,

{python_frontmatter-1.1.0.dist-info → python_frontmatter-1.2.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.42.0)
+Generator: setuptools (82.0.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

python_frontmatter-1.1.0.dist-info/RECORD

@@ -1,9 +0,0 @@
-frontmatter/__init__.py,sha256=wL0nd60OKonncekh0qpxqX7PjquQscdF7ADyQurygJc,8809
-frontmatter/conftest.py,sha256=LxRFalFdwQA2RtSYqCSB7V7THG7rHt5zZmMEzJlf0DA,220
-frontmatter/default_handlers.py,sha256=kO4QMSqvUWAUOcKC2sCmVA0SX2aZRXrhlckFCqZttkg,9661
-frontmatter/util.py,sha256=hlyw6r54QvGdsln0EcXUHh51eQqYRnONy4P6fuemo6M,419
-python_frontmatter-1.1.0.dist-info/LICENSE,sha256=LmiF34zbpRujrv40WY5ohW8bJGjR5YxxlhQAS4b7Q9U,1077
-python_frontmatter-1.1.0.dist-info/METADATA,sha256=FKyXVYaz4nPtlhZxEDx0WcDqFlcajLbGLVCZ-jzHOZA,4137
-python_frontmatter-1.1.0.dist-info/WHEEL,sha256=oiQVh_5PnQM0E3gPdiz09WCNmwiHDMaGer_elqB3coM,92
-python_frontmatter-1.1.0.dist-info/top_level.txt,sha256=o5ywgaMiFjjXFwNlYulDy2RAulwnLsZCmYQn0jy7w7M,12
-python_frontmatter-1.1.0.dist-info/RECORD,,