Moban extension

.gitignore

@@ -1,7 +1,6 @@
 # moban hashes
 .moban.hashes
 
-
 # Extra rules from https://github.com/github/gitignore/
 # Python rules
 # Byte-compiled / optimized / DLL files

.moban.cd/changelog.yml

@@ -1,6 +1,14 @@
 name: moban
 organisation: moremoban
 releases:
+- changes:
+  - action: Updated
+    details:
+    - '`#18`: file exists test'
+    - "`#23`: custom jinja plugins"
+    - '`#26`: repr filter'
+  date: unreleased
+  version: 0.2.0
 - changes:
   - action: Updated
     details:

.moban.cd/moban.yml

@@ -3,8 +3,8 @@ organisation: moremoban
 author: C. W.
 contact: [email protected]
 license: MIT
-version: 0.1.4
-current_version: 0.1.4
+version: 0.2.0
+current_version: 0.2.0
 release: 0.1.4
 branch: master
 command_line_interface: "moban"
@@ -15,6 +15,7 @@ keywords:
 dependencies:
   - pyyaml>=3.11
   - jinja2>=2.7.1
+  - lml==0.0.2
   - crayons
 description: Yet another jinja2 cli command for static text generation
 scm_host: github.com

CHANGELOG.rst

@@ -1,6 +1,16 @@
 Change log
 ================================================================================
 
+0.2.0 - unreleased
+--------------------------------------------------------------------------------
+
+Updated
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+#. `#18 <https://github.com/moremoban/moban/issues/18>`_: file exists test
+#. `#23 <https://github.com/moremoban/moban/issues/23>`_: custom jinja plugins
+#. `#26 <https://github.com/moremoban/moban/issues/26>`_: repr filter
+
 0.1.4 - 29-May-2018
 --------------------------------------------------------------------------------
 

docs/extension.rst

@@ -0,0 +1,32 @@
+Development guide
+=======================
+
+Jinja2 extensions for Moban
+------------------------------
+
+Since version 0.2, mobanfile supports an extra field `plugin_dir`, along with
+`template_dir`. When you put your own jinja2 filters, tests and globals in
+your moban repo, you can let moban know about them via this keyword.
+
+Importantly, you have to have `__init__.py` file in your `plugin_dir`. Otherwise,
+your plugins will NOT be loaded.
+
+Jinja2 Filter
+*******************
+
+.. literalinclude:: ../../moban/filters/repr.py
+
+
+Jinja2 Test
+*******************
+
+.. literalinclude:: ../../moban/tests/files.py
+
+Jinja2 Globals
+*******************
+
+.. literalinclude:: ../../tests/test_engine.py
+   :lines: 49-61
+
+It is possible to write an installable package including your own jinja2
+filters, tests and globals. Please email me for more details.

docs/index.rst

@@ -21,9 +21,17 @@ examples folder.
    level-4-single-command/README.rst
    level-5-custom-configuration/README.rst
    level-6-complex-configuration/README.rst
+   level-7-use-custom-jinja2-filter-test-n-global/README.rst
 
 For more complex use case, please look at `its usage in pyexcel project <http://pyexcel.readthedocs.io/en/latest/guide.html>`_
 
+Developer Guide
+================================================================================
+
+.. toctree::
+
+   extension
+
 .. include:: ../CHANGELOG.rst
 
 Indices and tables

docs/level-7-use-custom-jinja2-filter-test-n-global/.moban.yml

@@ -0,0 +1,10 @@
+configuration:
+  template_dir:
+    - my-templates
+  plugin_dir:
+    - custom-jj2-plugin
+  configuration: data.yml
+targets:
+  - filter.output: filter.jj2
+  - test.output: test.jj2
+  - global.output: global.jj2

docs/level-7-use-custom-jinja2-filter-test-n-global/README.rst

@@ -0,0 +1,45 @@
+Level 7: Custom jinja filters, tests and globals
+================================================================================
+
+Level 7 example demonstrates advanced plugin capabilities of moban. The following
+moban file had `plugin_dir` specified::
+
+
+    configuration:
+      template_dir:
+        - my-templates
+      plugin_dir:
+        - custom-jj2-plugin
+      configuration: data.yml
+    targets:
+      - filter.output: filter.jj2
+      - test.output: test.jj2
+
+Where `custom-jj2-plugin` is a directory holding all jinja2 filters, tests
+and globals. Under it, there are 4 files::
+
+    __init__.py     filter.py       test.py     global.py
+
+It is very important to have `__init__.py`, otherwise, it will NOT work. Other three
+files are named to show case the feature. You can choose whichever name you prefer,
+as long as you and your team could make sense of the names.
+
+
+Evaluation
+--------------------------------------------------------------------------------
+
+Please go to `docs/level-7-use-custom-jinja2-filter-test-n-global` directory,
+
+Here is the command to launch it:
+
+.. code-block:: bash
+
+   $ moban
+   Templating filter.jj2 to filter.output
+   Templating test.jj2 to test.output
+   Templating global.jj2 to global.output
+   Templated 3 files.
+   Everything is up to date!
+
+Please examine individual template and its associated plugin for more details.
+

docs/level-7-use-custom-jinja2-filter-test-n-global/custom-jj2-plugin/filter.py

@@ -0,0 +1,13 @@
+import sys
+import base64
+from moban.extensions import JinjaFilter
+
+
+@JinjaFilter('base64encode')
+def base64_encode(string):
+    if sys.version_info[0] > 2:
+        content = base64.b64encode(string.encode('utf-8'))
+        content = content.decode('utf-8')
+    else:
+        content = base64.b64encode(string)
+    return content

docs/level-7-use-custom-jinja2-filter-test-n-global/custom-jj2-plugin/global.py

@@ -0,0 +1,4 @@
+from moban.extensions import jinja_global
+
+
+jinja_global('global', dict(hello='world'))

docs/level-7-use-custom-jinja2-filter-test-n-global/custom-jj2-plugin/test.py

@@ -0,0 +1,6 @@
+from moban.extensions import JinjaTest
+
+
+@JinjaTest('level7')
+def test_level7(value):
+    return value == 'level7'

docs/level-7-use-custom-jinja2-filter-test-n-global/data.yml

@@ -0,0 +1,2 @@
+level: level7
+level8: level8

docs/level-7-use-custom-jinja2-filter-test-n-global/filter.output

@@ -0,0 +1 @@
+YWJj

docs/level-7-use-custom-jinja2-filter-test-n-global/global.output

@@ -0,0 +1 @@
+world

docs/level-7-use-custom-jinja2-filter-test-n-global/my-templates/filter.jj2

@@ -0,0 +1 @@
+{{ 'abc' | base64encode }}

docs/level-7-use-custom-jinja2-filter-test-n-global/my-templates/global.jj2

@@ -0,0 +1 @@
+{{ global.hello }}

docs/level-7-use-custom-jinja2-filter-test-n-global/my-templates/test.jj2

@@ -0,0 +1,11 @@
+{% if level is level7%}
+Hello, you are in level 7 example
+{% else %}
+Hello, you are not in {{level}}
+{% endif %}
+
+{% if level8 is level7%}
+Hello, you are in level 7 example
+{% else %}
+Hello, you are not in level 7
+{% endif %}

moban/constants.py

@@ -20,6 +20,7 @@
 # Command line options
 LABEL_CONFIG = "configuration"
 LABEL_CONFIG_DIR = "configuration_dir"
+LABEL_PLUGIN_DIRS = "plugin_dir"
 LABEL_TEMPLATE = "template"
 LABEL_TMPL_DIRS = "template_dir"
 LABEL_OUTPUT = "output"
@@ -68,3 +69,9 @@
 HAS_CHANGES = 1
 ERROR = 2
 NO_CHANGES = 0
+
+
+# Extension
+JINJA_FILTER_EXTENSION = "jinja_filter"
+JINJA_TEST_EXTENSION = "jinja_test"
+JINJA_GLOBALS_EXTENSION = "jinja_globals"

moban/copier.py

@@ -5,6 +5,7 @@
 
 
 class Copier(object):
+
     def __init__(self, template_dirs):
         self.template_dirs = template_dirs
         self._count = 0
@@ -19,7 +20,8 @@ def copy_files(self, file_list):
                     self._count = self._count + 1
                 else:
                     reporter.report_error_message(
-                        "{0} cannot be found".format(src))
+                        "{0} cannot be found".format(src)
+                    )
 
     def number_of_copied_files(self):
         return self._count

moban/engine.py

@@ -3,15 +3,30 @@
 from collections import defaultdict
 from jinja2 import Environment, FileSystemLoader
 
+from lml.loader import scan_plugins
+
 from moban.hashstore import HashStore
-from moban.filters.text import split_length
-from moban.filters.github import github_expand
+from moban.extensions import JinjaFilterManager, JinjaTestManager
+from moban.extensions import JinjaGlobalsManager
 import moban.utils as utils
 import moban.constants as constants
 import moban.exceptions as exceptions
 import moban.reporter as reporter
 
 
+BUILTIN_EXENSIONS = [
+    "moban.filters.repr",
+    "moban.filters.github",
+    "moban.filters.text",
+    "moban.tests.files",
+]
+
+_FILTERS = JinjaFilterManager()
+_TESTS = JinjaTestManager()
+_GLOBALS = JinjaGlobalsManager()
+scan_plugins("moban_", "moban", None, BUILTIN_EXENSIONS)
+
+
 class EngineFactory(object):
 
     @staticmethod
@@ -39,9 +54,17 @@ def __init__(self, template_dirs, context_dirs):
             trim_blocks=True,
             lstrip_blocks=True,
         )
-        self.jj2_environment.filters["split_length"] = split_length
-        self.jj2_environment.filters["github_expand"] = github_expand
+        for filter_name, filter_function in _FILTERS.get_all():
+            self.jj2_environment.filters[filter_name] = filter_function
+
+        for test_name, test_function in _TESTS.get_all():
+            self.jj2_environment.tests[test_name] = test_function
+
+        for global_name, helper_obj in _GLOBALS.get_all():
+            self.jj2_environment.globals[global_name] = helper_obj.payload
+
         self.context = Context(context_dirs)
+        self.template_dirs = template_dirs
         self.hash_store = HashStore()
         self.__file_count = 0
         self.__templated_count = 0
@@ -53,7 +76,7 @@ def render_to_file(self, template_file, data_file, output_file):
 
         rendered_content = template.render(**data)
         utils.write_file_out(output_file, rendered_content)
-        utils.file_permissions_copy(template_file, output_file)
+        self._file_permissions_copy(template_file, output_file)
 
     def render_to_files(self, array_of_param_tuple):
         sta = Strategy(array_of_param_tuple)
@@ -114,6 +137,14 @@ def _apply_template(self, template, data, output):
             utils.file_permissions_copy(template.filename, output)
         return flag
 
+    def _file_permissions_copy(self, template_file, output_file):
+        true_template_file = template_file
+        for a_template_dir in self.template_dirs:
+            true_template_file = os.path.join(a_template_dir, template_file)
+            if os.path.exists(true_template_file):
+                break
+        utils.file_permissions_copy(true_template_file, output_file)
+
 
 class Context(object):