Merge pull request #76 from eyeseast/v1.0

V1.0

.github/workflows/publish.yml

@@ -0,0 +1,56 @@
+name: Publish Python Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/cache@v2
+        name: Configure pip caching
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -e '.[test]'
+      - name: Run tests
+        run: pytest
+  deploy:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+        with:
+          python-version: "3.8"
+      - uses: actions/cache@v2
+        name: Configure pip caching
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-publish-pip-${{ hashFiles('**/setup.py') }}
+          restore-keys: |
+            ${{ runner.os }}-publish-pip-
+      - name: Install dependencies
+        run: |
+          pip install setuptools wheel twine
+      - name: Publish
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          python setup.py sdist bdist_wheel
+          twine upload --verbose dist/*

.github/workflows/test.yml

@@ -0,0 +1,29 @@
+name: Test
+
+on: [push]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8, 3.9]
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - uses: actions/cache@v2
+        name: Configure pip caching
+        with:
+          path: ~/.cache/pip
+          key: ${{ runner.os }}-pip-${{ hashFiles('**/setup.py') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-
+      - name: Install dependencies
+        run: |
+          pip install -e '.[test]'
+      - name: Run tests
+        run: |
+          pytest . --doctest-modules --doctest-glob "README.md"

.gitignore

@@ -55,3 +55,4 @@ docs/_build/
 target/
 
 .DS_Store
+.vscode/

LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2019 Chris Amico, Glass Eye Media LLC
+Copyright (c) 2021 Chris Amico
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,43 +1,46 @@
-Python Frontmatter
-==================
+# 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 front matter.
+This is a small package to load and parse files (or just text) with YAML (or JSON, TOML or other) front matter.
 
-[![Build Status](https://travis-ci.org/eyeseast/python-frontmatter.svg?branch=master)](https://travis-ci.org/eyeseast/python-frontmatter)
+[![Tests](https://github.com/eyeseast/feed-to-sqlite/workflows/Test/badge.svg)](https://github.com/eyeseast/feed-to-sqlite/actions?query=workflow%3ATest)
+[![PyPI](https://img.shields.io/pypi/v/python-frontmatter.svg)](https://pypi.org/project/python-frontmatter/)
 
-Install:
---------
+**[Documentation](https://python-frontmatter.readthedocs.io/en/latest/)**
 
-    pip install python-frontmatter
+## Install:
 
+    pip install python-frontmatter
 
-Usage:
-------
+## Usage:
 
 ```python
-import frontmatter
+>>> import frontmatter
+
 ```
 
 Load a post from a filename:
 
 ```python
-post = frontmatter.load('tests/hello-world.markdown')
+>>> post = frontmatter.load('tests/yaml/hello-world.txt')
+
 ```
 
 Or a file (or file-like object):
 
 ```python
->>> with open('tests/hello-world.markdown') as f:
+>>> with open('tests/yaml/hello-world.txt') as f:
 ...     post = frontmatter.load(f)
+
 ```
 
 Or load from text:
 
 ```python
->>> with open('tests/hello-world.markdown') as f:
+>>> with open('tests/yaml/hello-world.txt') as f:
 ...     post = frontmatter.loads(f.read())
+
 ```
 
 Access content:
@@ -49,13 +52,15 @@ 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:
@@ -68,15 +73,17 @@ Metadata is a dictionary, with some handy proxies:
 >>> 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/hello-world.markdown') as f:
+>>> 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:
@@ -90,6 +97,8 @@ title: Hello, world!
 ---
 Well, hello there, world.
 
+```
+
 Or write to a file (or file-like object):
 
 ```python
@@ -103,5 +112,7 @@ 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.

docs/conf.py

@@ -50,17 +50,17 @@
 
 # General information about the project.
 project = u"Python Frontmatter"
-copyright = u"2017, Chris Amico"
+copyright = u"2021, Chris Amico"
 author = u"Chris Amico"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = u"0.4.2"
+version = u"1.0.0"
 # The full version, including alpha/beta/rc tags.
-release = u"0.4.2"
+release = u"1.0.0"
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/handlers.rst

@@ -1,8 +1,6 @@
 Customizing input and output
 ============================
 
-.. module:: frontmatter
-
 .. automodule:: frontmatter.default_handlers
 
 .. autoclass:: frontmatter.default_handlers.BaseHandler

docs/index.rst

@@ -12,7 +12,7 @@ Python Frontmatter
 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
+This is a package to load and parse files (or text strings) with YAML
 front matter.
 
 
@@ -34,20 +34,20 @@ Load a post from a filename:
 
 ::
 
-    >>> post = frontmatter.load('tests/hello-world.markdown')
+    >>> post = frontmatter.load('tests/yaml/hello-world.txt')
 
 Or a file (or file-like object):
 
 ::
 
-    >>> with open('tests/hello-world.markdown') as f:
+    >>> with open('tests/yaml/hello-world.txt') as f:
     ...     post = frontmatter.load(f)
 
 Or load from text:
 
 ::
 
-    >>> with open('tests/hello-world.markdown') as f:
+    >>> with open('tests/yaml/hello-world.txt') as f:
     ...     post = frontmatter.loads(f.read())
 
 Access content:
@@ -80,11 +80,11 @@ Metadata is a dictionary, with some handy proxies:
     >>> pprint(post.metadata)
     {'excerpt': 'tl;dr', 'layout': 'post', 'title': 'Hello, world!'}
 
-If you don't need the whole post object, just parse:
+If you don't need the whole post object, use `frontmatter.parse` to return metadata and content separately:
 
 ::
 
-    >>> with open('tests/hello-world.markdown') as f:
+    >>> with open('tests/yaml/hello-world.txt') as f:
     ...     metadata, content = frontmatter.parse(f.read())
     >>> print(metadata['title'])
     Hello, world!

examples/content/pandoc.txt

@@ -0,0 +1,11 @@
+---
+lipsum: https://www.lipsum.com/
+ref: https://github.com/eyeseast/python-frontmatter/issues/42
+title: Pandoc-flavored Front Matter
+...
+
+Nulla pulvinar, turpis ullamcorper tempus posuere, sapien purus porttitor diam, id ullamcorper lorem neque id mauris. Sed facilisis, elit eget luctus posuere, quam nibh imperdiet magna, vel placerat arcu risus sit amet arcu. Morbi sit amet mollis leo. Mauris sit amet condimentum mi. Quisque lectus libero, varius scelerisque tempor ut, elementum ac diam. Morbi nisl sapien, ullamcorper ac elementum at, auctor quis magna. Curabitur nec neque purus.
+
+Proin tincidunt cursus turpis, mattis euismod sapien. Cras consectetur id felis non volutpat. Proin vulputate ante gravida quam euismod blandit. Nulla at varius nibh. Donec congue erat vel mattis volutpat. Sed fringilla lorem sit amet velit ornare gravida. Sed ac scelerisque nisi.
+
+Generated 2 paragraphs, 109 words, 730 bytes of Lorem Ipsum

examples/content/reversed.txt

@@ -0,0 +1,28 @@
+This is txt format to prevent reformatting
+============================================
+
+Dextra tempore deus
+-------------------
+
+Lorem markdownum est dicere pariter es dat si non, praesignis Styge, non
+Maenalon magnae miserrimus. Corpora frustra committere insuetum et fecit
+**Hippothousque arbore solio** inopem utraque concepit illa comantem me mortis
+epulis protinus putares! Piceis *manibus*. Erinys et parum morsusque repugnat
+ore corna sacris, pollice movet currus gestamina.
+
+Genitoris forti circumfuso videbit fertur vulnere simillima
+-----------------------------------------------------------
+
+Audit enim, est illa nervis loco inque hoc, et rigido! Monstris vatibus laetos
+contemptor Calydonia. Et visa capillo referens regia: usus: odiique nostro.
+**Vim** sensit inpulit virginis metuens secum cogit, corpus.
+
+Humus ater Dromas est honorem, Titanida glandibus sinit, e terras capillos
+cremet retinentibus male. Tertia et cedit eliso flectere haec, cute nihil
+marmore armo. Mihi [Olympi](http://que.org/saepepoenas), iam sustinet addidit
+humana similis.
+
+---
+title: Front matter, reversed
+ref: https://github.com/eyeseast/python-frontmatter/issues/67
+---

examples/content/sorted.txt

@@ -0,0 +1,12 @@
+---
+title: Pandoc-flavored Front Matter
+ref: https://github.com/eyeseast/python-frontmatter/issues/26
+lipsum: https://www.lipsum.com/
+alpha: false
+---
+
+Nulla pulvinar, turpis ullamcorper tempus posuere, sapien purus porttitor diam, id ullamcorper lorem neque id mauris. Sed facilisis, elit eget luctus posuere, quam nibh imperdiet magna, vel placerat arcu risus sit amet arcu. Morbi sit amet mollis leo. Mauris sit amet condimentum mi. Quisque lectus libero, varius scelerisque tempor ut, elementum ac diam. Morbi nisl sapien, ullamcorper ac elementum at, auctor quis magna. Curabitur nec neque purus.
+
+Proin tincidunt cursus turpis, mattis euismod sapien. Cras consectetur id felis non volutpat. Proin vulputate ante gravida quam euismod blandit. Nulla at varius nibh. Donec congue erat vel mattis volutpat. Sed fringilla lorem sit amet velit ornare gravida. Sed ac scelerisque nisi.
+
+Generated 2 paragraphs, 109 words, 730 bytes of Lorem Ipsum