complete embed_images with doctest, unittest, documentation. ref pull request #2 and commit bdd8fbc4a30a

* skip http, https, and data schemes
* print out message and keep image tag untouched when file is not found
* BaseHandler.SUPPORT_EMBED_IMAGES is added for subclass to turn off as text handler does

Author: livibetter

CHANGES.rst

@@ -5,6 +5,18 @@ CHANGES
 Development
 ===========
 
+* add ``embed_images`` configuration option to embed image files via data URI
+  scheme for all but text handler (pull request #2, by Adam Kemp)
+
+  * skip ``http``, ``https``, and ``data`` schemes
+  * if file not found, a message is printed out, rendered HTML tag is kept
+    untouched
+  * related doctest and unittest tests are added, testing ``embed_images``
+    function and with ``generate``, if with text handler, it will raise
+    ``RuntimeError`` or treat ``img`` tag as plain text, respectively
+  * ``BaseHandler`` has class attribute ``SUPPORT_EMBED_IMAGES`` for subclass
+    to turn off the support as text handler utilizing it
+
 Version 0.8.0 (2014-08-26T12:17:09Z)
 ====================================
 

bpy/handlers/__init__.py

@@ -56,6 +56,9 @@
 
         # use smartypant to process the output of markup processor
         'smartypants': False,
+
+        # support image embedding via data URI scheme
+        'embed_images': False,
       },
     },
   }
@@ -94,6 +97,40 @@
 
 .. _smartypants: https://pypi.python.org/pypi/smartypants
 
+.. _embed_images:
+
+``embed_images``
+----------------
+
+.. note::
+
+  Only :mod:`bpy.handlers.text` does not support this option.
+
+When this option is enabled, it looks for the ``src`` attribute of ``img`` tag
+in rendered HTML, see if there is a local files, excluding ``http``, ``https``,
+and ``data`` schemes, if found, it reads the file and embeds with Base64
+encoded content.
+
+For example, in reStructuredText:
+
+.. code:: rst
+
+  .. image:: /path/to/test.png
+
+Instead of
+
+.. code:: html
+
+  <img alt="/path/to/test.png" src="/path/to/test.png" />
+
+It could be replaced with, if ``/path/to/test.png`` exists:
+
+.. code:: html
+
+  <img alt="/path/to/test.png" src="data:image/png;base64,..." />
+
+If the image file can't be found, a message will be printed out, the rendered
+image tag will be kept untouched.
 
 .. _custom-handler:
 

bpy/handlers/asciidoc.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -20,7 +20,17 @@
 # THE SOFTWARE.
 
 """
-No options are available at this moment.
+You can specify embed_images_, for example:
+
+.. code:: python
+
+  handlers = {
+    'AsciiDoc': {
+      'options': {
+        'embed_images': True,
+      },
+    },
+  }
 """
 
 from __future__ import print_function, unicode_literals

bpy/handlers/base.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -25,9 +25,9 @@
 import re
 import warnings
 from abc import ABCMeta, abstractmethod
-from hashlib import md5
-from os.path import basename, splitext, exists
 from base64 import b64encode
+from hashlib import md5
+from os.path import basename, exists, splitext
 
 HAS_SMARTYPANTS = False
 try:
@@ -58,7 +58,15 @@ class BaseHandler():
                         re.DOTALL | re.MULTILINE)
   RE_HEADER = re.compile(r'.*?([a-zA-Z0-9_-]+)\s*[=:]\s*(.*)\s*')
 
-  RE_IMG = re.compile(r'(<img.*?)src="([^"]*)"(.*?>)')
+  SUPPORT_EMBED_IMAGES = True
+  RE_IMG = re.compile(
+    r'''
+    (?P<prefix><img.*?)
+    src="(?!data:image/|https?://)(?P<src>[^"]*)"
+    (?P<suffix>.*?>)
+    ''',
+    re.VERBOSE
+  )
 
   def __init__(self, filename, options=None):
 
@@ -233,8 +241,8 @@ def generate(self, markup=None):
       Attr = smartypants.Attr
       html = smartypants.smartypants(html, Attr.set1 | Attr.w)
 
-    if self.options.get('embed_images', False):
-        html = self.embed_images(html)
+    if self.SUPPORT_EMBED_IMAGES and self.options.get('embed_images', False):
+      html = self.embed_images(html)
 
     return html
 
@@ -356,21 +364,36 @@ def write(self, forced=False):
     self.modified = False
 
   def embed_images(self, html):
-    return self.RE_IMG.sub(self.embed_image, html)
-
-  def embed_image(self, match):
-    img_name = match.group(2)
-    if exists(img_name):
-      img_prefix = match.group(1)
-      src_attr = "src=\"" + self.encode_image(img_name) + "\""
-      img_suffix = match.group(3)
-      return img_prefix + src_attr + img_suffix
-    else:
+    """Embed images on local filesystem as data URI
+
+    >>> class Handler(BaseHandler):
+    ...   def _generate(self, source=None): return source
+    >>> handler = Handler(None)
+    >>> html = '<img src="http://example.com/example.png"/>'
+    >>> print(handler.embed_images(html))
+    <img src="http://example.com/example.png"/>
+    >>> html = '<img src="tests/test.png"/>'
+    >>> print(handler.embed_images(html))  #doctest: +ELLIPSIS
+    <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...QmCC"/>
+    """
+    if not self.SUPPORT_EMBED_IMAGES:
+      raise RuntimeError('%r does not support embed_images' % type(self))
+
+    return self.RE_IMG.sub(self._embed_image, html)
+
+  @staticmethod
+  def _embed_image(match):
+
+    src = match.group('src')
+    if not exists(src):
+      print('%s is not found.' % src)
       return match.group(0)
 
-  def encode_image(self, name):
-    with open(name, "rb") as f:
-      image_data = f.read()
-      ext = splitext(name)[1].lstrip('.')
-      encoded_image = b64encode(image_data)
-      return "data:image/" + ext + ";base64," + encoded_image
+    with open(src, 'rb') as f:
+      data = b64encode(f.read()).decode('ascii')
+
+    return '%ssrc="%s"%s' % (
+      match.group('prefix'),
+      'data:image/%s;base64,%s' % (splitext(src)[1].lstrip('.'), data),
+      match.group('suffix'),
+    )

bpy/handlers/html.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -22,7 +22,17 @@
 HTML handler simply takes the file content as its output, and assume it's valid
 HTML, therefore the handler doesn't edit or validate the content.
 
-No options are available at this moment.
+You can specify embed_images_, for example:
+
+.. code:: python
+
+  handlers = {
+    'HTML': {
+      'options': {
+        'embed_images': True,
+      },
+    },
+  }
 """
 
 from __future__ import print_function, unicode_literals

bpy/handlers/mkd.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -19,8 +19,8 @@
 # THE SOFTWARE.
 
 """
-You can specify `configuration`__ for Python Markdown in :ref:`brc.py`, for
-example:
+You can specify `configuration`__ for Python Markdown in :ref:`brc.py` or
+embed_images_, for example:
 
 __ http://packages.python.org/Markdown/reference.html#markdown
 
@@ -33,6 +33,7 @@
           'extensions': ['extension1', 'extension2'],
           'tab_length': 8,
         },
+        'embed_images': True,
       },
     },
   }

bpy/handlers/rst.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2011-2013 by Yu-Jie Lin
+# Copyright (C) 2011-2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -19,14 +19,15 @@
 # THE SOFTWARE.
 
 """
-You can specify settings-overrides_ for reStructuredText in :ref:`brc.py`, for
-example:
+You can specify settings-overrides_ for reStructuredText in :ref:`brc.py` or
+the embed_images_, for example:
 
 .. code:: python
 
   handlers = {
     'reStructuredText': {
       'options': {
+        'embed_images': True,
         'register_directives': {
           'dir_name': MyDir,
         },

bpy/handlers/text.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -69,6 +69,8 @@ class Handler(base.BaseHandler):
   PREFIX_END = ''
   HEADER_FMT = '%s: %s'
 
+  SUPPORT_EMBED_IMAGES = False
+
   def generate_title(self, markup=None):
     """Generate HTML from plain text
 

tests/test.png

@@ -52,3 +52,17 @@ def setUp(self):
   # =====
 
   test_smartypants_EXPECT = '<p>foo &#8220;bar&#8221;</p>'
+
+  # =====
+
+  @unittest.skip('tested in BaseHandler')
+  def test_embed_images(self):
+
+    pass
+
+  test_embed_images_generate_SOURCE = 'image:tests/test.png[tests/test.png]'
+  test_embed_images_generate_EXPECT = (
+    '<p><img src="%s" style="border-width: 0;" alt="tests/test.png"></p>' % (
+      test_base.BaseHandlerTestCase.test_embed_images_data_URI
+    )
+  )

tests/test_bpy_handlers_asciidoc.py

@@ -1,4 +1,4 @@
-# Copyright (C) 2013 by Yu-Jie Lin
+# Copyright (C) 2013, 2014 Yu-Jie Lin
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal
@@ -360,3 +360,60 @@ def test_update_source(self):
 
     handler.update_source()
     self.assertEqual(handler.source, source)
+
+  # =====
+
+  test_embed_images_src = 'tests/test.png'
+  test_embed_images_data_URI = (
+    'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAI'
+    'AAACQd1PeAAAADElEQVQI12Oorq4GAALmAXLRBAkWAAAAAElFTkSuQmCC'
+  )
+
+  test_embed_images_SOURCE1 = '<img src="http://example.com/example.png"/>'
+  test_embed_images_EXPECT1 = test_embed_images_SOURCE1
+
+  test_embed_images_SOURCE2 = '<img src="tests/test.png"/>'
+  test_embed_images_EXPECT2 = '<img src="%s"/>' % test_embed_images_data_URI
+
+  test_embed_images_SOURCE3 = '<img alt="foo" src="tests/test.png"/>'
+  test_embed_images_EXPECT3 = '<img alt="foo" src="%s"/>' % (
+                              test_embed_images_data_URI)
+
+  test_embed_images_SOURCE4 = '<img src="tests/test.png" title="bar"/>'
+  test_embed_images_EXPECT4 = '<img src="%s" title="bar"/>' % (
+                              test_embed_images_data_URI)
+
+  test_embed_images_SOURCE5 = '<img src="%s"/>' % test_embed_images_data_URI
+  test_embed_images_EXPECT5 = test_embed_images_SOURCE5
+
+  def test_embed_images(self):
+
+    handler = self.handler
+
+    result = handler.embed_images(self.test_embed_images_SOURCE1)
+    self.assertEqual(result, self.test_embed_images_EXPECT1)
+
+    result = handler.embed_images(self.test_embed_images_SOURCE2)
+    self.assertEqual(result, self.test_embed_images_EXPECT2)
+
+    result = handler.embed_images(self.test_embed_images_SOURCE3)
+    self.assertEqual(result, self.test_embed_images_EXPECT3)
+
+    result = handler.embed_images(self.test_embed_images_SOURCE4)
+    self.assertEqual(result, self.test_embed_images_EXPECT4)
+
+    result = handler.embed_images(self.test_embed_images_SOURCE5)
+    self.assertEqual(result, self.test_embed_images_EXPECT5)
+
+  test_embed_images_generate_SOURCE = '<img src="tests/test.png"/>'
+  test_embed_images_generate_EXPECT = '<img src="%s"/>' % (
+                                      test_embed_images_data_URI)
+
+  def test_embed_images_generate(self):
+
+    handler = self.handler
+    handler.options['embed_images'] = True
+
+    handler.markup = self.test_embed_images_generate_SOURCE
+    html = handler.generate()
+    self.assertEqual(html, self.test_embed_images_generate_EXPECT)