Include a frontmatter_loaded signal.

docs/index.rst

@@ -79,6 +79,7 @@ Documentation
     configuration
     server
     composers
+    signals
     templates
     i18n
     releases

docs/signals.rst

@@ -0,0 +1,16 @@
+Signals
+=======
+
+handroll fires various signals while running. These signals provide hooks
+for extensions to execute additional code. The list of signals is provided
+below.
+
+frontmatter_loaded
+------------------
+
+``frontmatter_loaded`` fires whenever a file contains a front matter section
+(see :ref:`frontmatter`). Any handler function that connects to the signal
+will be called with:
+
+* ``source_file`` - The absolute path to the file containing front matter.
+* ``frontmatter`` - The front matter dictionary that was loaded.

handroll/composers/generic.py

@@ -10,7 +10,7 @@
 
 import yaml
 
-from handroll import logger
+from handroll import logger, signals
 from handroll.composers import Composer
 from handroll.i18n import _
 
@@ -77,6 +77,7 @@ def _get_data(self, source_file):
                 data = next(documents)
                 if 'title' in data:
                     data['title'] = escape(data['title'])
+                signals.frontmatter_loaded.send(source_file, frontmatter=data)
 
                 # Don't pass all file content to the composer. Find the markup.
                 match = re.search(self.yaml_scanner, source)

handroll/signals.py

@@ -0,0 +1,6 @@
+# Copyright (c) 2015, Matt Layman
+"""Signals fired during execution"""
+
+from blinker import signal
+
+frontmatter_loaded = signal('frontmatter_loaded')

handroll/tests/test_composers.py

@@ -151,6 +151,21 @@ def test_gets_frontmatter(self):
         self.assertEqual('A Fake Title', data['title'])
         self.assertEqual('The Content', source)
 
+    @mock.patch('handroll.composers.generic.signals')
+    def test_fires_frontmatter_loaded(self, signals):
+        source = inspect.cleandoc("""%YAML 1.1
+        ---
+        title: A Fake Title
+        ---
+        The Content
+        """)
+        with tempfile.NamedTemporaryFile(delete=False) as f:
+            f.write(source.encode('utf-8'))
+        composer = GenericHTMLComposer()
+        data, source = composer._get_data(f.name)
+        signals.frontmatter_loaded.send.assert_called_once_with(
+            f.name, frontmatter={'title': 'A Fake Title'})
+
     def test_needs_update(self):
         site = tempfile.mkdtemp()
         output_file = os.path.join(site, 'output.md')

setup.py

@@ -13,7 +13,7 @@
 from setuptools.command.sdist import sdist
 import sys
 
-__version__ = '1.5'
+__version__ = '1.6'
 
 
 class Sdist(sdist):
@@ -32,6 +32,7 @@ def run(self):
 
     install_requires = [
         'argparse',  # For Python 2.6 support
+        'blinker',
         'docutils',
         'Jinja2',
         'Markdown==2.4',  # 2.5 dropped support for Python 2.6.