Merge pull request #19 from bckohan/v1.1

V1.1

Author: bckohan

.github/workflows/test.yml

@@ -23,15 +23,15 @@ jobs:
         python-version: ${{ matrix.python-version }}
 
     - name: Install Poetry
-      uses: snok/[email protected].1
+      uses: snok/[email protected].6
       with:
         virtualenvs-create: true
         virtualenvs-in-project: true
     - name: Install Release Dependencies
       run: |
         poetry config virtualenvs.in-project true
         poetry run pip install --upgrade pip
-        poetry install
+        poetry install -E all
         poetry run pip install -U "${{ matrix.django-version }}"
     - name: Run Unit Tests
       run: |

.gitignore

@@ -6,6 +6,12 @@ __pycache__/
 # C extensions
 *.so
 
+# MAC garbage
+.DS_Store
+
+# pycharm
+.idea
+
 # Distribution / packaging
 .Python
 build/
@@ -115,6 +121,7 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+.python-version
 
 # Spyder project settings
 .spyderproject
@@ -140,4 +147,6 @@ dmypy.json
 # Cython debug symbols
 cython_debug/
 /render_static/tests/app1/static/
+/render_static/tests/app2/static/exclusive
 /render_static/tests/global_static/
+/render_static/tests/resources/*.pickle

README.rst

@@ -35,8 +35,10 @@ defines, or enum like structures in server side Python code that are simply repl
 side JavaScript. Single-sourcing these structures by generating client side code from the server
 side code keeps the stack bone DRY.
 
-Have you ever wished you could replicate Django's ``reverse`` function in a JavaScript library for
-your site? Now you can with the ``urls_to_js`` template tag included with `django-render-static`.
+`django-render-static` includes builtins for:
+    - Replicating Django's `reverse` function in JavaScript (`urls_to_js`)
+    - Auto-translating basic Python class and module structures into JavaScript
+      (`modules_to_js`, `classes_to_js`)
 
 You can report bugs and discuss features on the
 `issues page <https://github.com/bckohan/django-render-static/issues>`_.
@@ -77,11 +79,11 @@ Installation
         }
 
 
-4. Run ``render_static`` preceding every run of ``collectstatic`` :
+4. Run ``renderstatic`` preceding every run of ``collectstatic`` :
 
 .. code:: bash
 
-        $> manage.py render_static
+        $> manage.py renderstatic
         $> manage.py collectstatic
 
 
@@ -151,11 +153,11 @@ class their settings file might look like this:
     }
 
 
-And then of course they would call `render_static` before `collectstatic`:
+And then of course they would call `renderstatic` before `collectstatic`:
 
 .. code:: bash
 
-    $> ./manage.py render_static
+    $> ./manage.py renderstatic
     $> ./manage.py collectstatic
 
 
@@ -229,9 +231,9 @@ Your settings file might look like:
     }
 
 
-Then call `render_static` before `collectstatic`::
+Then call `renderstatic` before `collectstatic`::
 
-    $> ./manage.py render_static
+    $> ./manage.py renderstatic
     $> ./manage.py collectstatic
 
 If your root urls.py looks like this:
@@ -301,6 +303,19 @@ So you can now fetch paths like this:
     // /different/143/emma
     const urls = new URLResolver();
     urls.reverse('different', {'arg1': 143, 'arg2': 'emma'});
+
+    // reverse also supports query parameters
+    // /different/143/emma?intarg=0&listarg=A&listarg=B&listarg=C
+    url.reverse(
+        'different',
+        {
+            kwargs: {arg1: 143, arg2: 'emma'},
+            query: {
+                intarg: 0,
+                listarg: ['A', 'B', 'C']
+            }
+        }
+    );
     
     
 URLGenerationFailed Exceptions & Placeholders

doc/requirements.txt

@@ -1,9 +1,9 @@
 sphinx-argparse==0.2.5
-sphinx-rtd-theme==0.5.1
+sphinx-rtd-theme==0.5.2
 sphinxcontrib-applehelp==1.0.2; python_version >= "3.5"
 sphinxcontrib-devhelp==1.0.2; python_version >= "3.5"
 sphinxcontrib-htmlhelp==1.0.3; python_version >= "3.5"
 sphinxcontrib-jsmath==1.0.1; python_version >= "3.5"
 sphinxcontrib-qthelp==1.0.3; python_version >= "3.5"
 sphinxcontrib-serializinghtml==1.1.4; python_version >= "3.5"
-django-render-static==0.1.0
+django-render-static==1.1.0

doc/source/changelog.rst

@@ -2,6 +2,16 @@
 Change Log
 ==========
 
+v1.1.0
+====================
+
+* Added `Support batch rendering & glob patterns in template selectors <https://github.com/bckohan/django-render-static/issues/15>`_
+* Fixed `Rename render_static -> renderstatic <https://github.com/bckohan/django-render-static/issues/11>`_
+* Added `Allow 'lazy' contexts built after Django bootstrapping <https://github.com/bckohan/django-render-static/issues/6>`_
+* Added `Flexible context specifiers <https://github.com/bckohan/django-render-static/issues/17>`_
+* Added `Add GET query parameters to ClassURLWriter's reverse function <https://github.com/bckohan/django-render-static/issues/12>`_
+
+
 v1.0.1
 ====================
 

doc/source/commands.rst

@@ -4,16 +4,18 @@
 Commands
 ========
 
-render_static
----------------
+.. _renderstatic:
 
-.. automodule:: render_static.management.commands.render_static
+renderstatic
+------------
+
+.. automodule:: render_static.management.commands.renderstatic
 
 Usage
 ~~~~~
 
 .. argparse::
-    :module: render_static.management.commands.render_static
+    :module: render_static.management.commands.renderstatic
     :func: get_parser
     :prog: manage.py
 
@@ -24,12 +26,12 @@ To generate all templates configured in ``STATIC_TEMPLATES`` settings:
 
 .. code::
 
-    $ manage.py render_static
+    $ manage.py renderstatic
 
 Alternatively individual templates can be generated, regardless of their presence
-in ``STATIC_TEMPLATES``. They will be given the global context:
+in ``STATIC_TEMPLATES``. They will be given the global context with any overriding context
+parameters supplied on the command line:
 
 .. code::
 
-    $ manage.py render_static name/of/template1.js name/of/template2.js
-
+    $ manage.py renderstatic path/*.js -c ./js_context.yaml -d outputdir

doc/source/configuration.rst

@@ -17,9 +17,9 @@ settings:
                 'app_dir': 'static_templates',  # search this directory in apps for templates
                 'loaders': [
                     # search apps for templates
-                    'render_static.loaders.StaticAppDirectoriesLoader',
+                    'render_static.loaders.StaticAppDirectoriesBatchLoader',
                     # search DIRS for templates
-                    'render_static.loaders.StaticFilesystemLoader'
+                    'render_static.loaders.StaticFilesystemBatchLoader'
                  ],
                 'builtins': ['render_static.templatetags.render_static']
             },
@@ -41,12 +41,14 @@ The ``STATIC_TEMPLATES`` setting closely mirrors the ``TEMPLATES`` setting by de
 template backends should be used. It extends the standard setting with a few options needed by the
 static engine including a global context available to all static templates and a set of template
 specific configuration parameters. It's advisable to first read about Django's ``TEMPLATES``
-setting.
+setting. The main difference with ``STATIC_TEMPLATES`` is that it supports batch rendering.
+Glob-like patterns can be used to select multiple templates for rendering. See :ref:`loaders` for
+more details.
 
 Minimal Configuration
 ---------------------
 
-To run render_static, ``STATIC_TEMPLATES`` must be defined in settings. If it's an empty
+To run `renderstatic`, ``STATIC_TEMPLATES`` must be defined in settings. If it's an empty
 dictionary (or None):
 
 .. code-block:: python
@@ -59,14 +61,13 @@ then the default engine and loaders will be used which is equivalent to:
 .. code-block:: python
 
     STATIC_TEMPALTES = {
-        'ENGINES': [
+        'ENGINES': [{
             'BACKEND': 'render_static.backends.StaticDjangoTemplates',
-            'DIRS': [],
             'OPTIONS': {
-                'loaders': ['render_static.loaders.StaticAppDirectoriesLoader'],
+                'loaders': ['render_static.loaders.StaticAppDirectoriesBatchLoader'],
                 'builtins': ['render_static.templatetags.render_static']
             },
-        ]
+        }]
     }
 
 
@@ -100,18 +101,42 @@ A list of configuration parameters to pass to the backend during initialization.
 parameters are inherited from the standard Django template backends. One additional parameter
 ``app_dir`` can be used to change the default search path for static templates within apps.
 
+.. _loaders:
+
 ``loaders``
 ***********
 
 Works the same way as the ``loaders`` parameter on ``TEMPLATES``. Except when using the standard
 template backend the loaders have been extended and static specific loaders should be used instead:
 
 - ``render_static.backends.StaticDjangoTemplates``
-    - ``render_static.loaders.StaticAppDirectoriesLoader``
-    - ``render_static.loaders.StaticFilesystemLoader``
-    - ``render_static.loaders.StaticLocMemLoader``
+    - ``render_static.loaders.django.StaticAppDirectoriesBatchLoader`` **default**
+    - ``render_static.loaders.django.StaticFilesystemBatchLoader``
+    - ``render_static.loaders.django.StaticAppDirectoriesLoader``
+    - ``render_static.loaders.django.StaticFilesystemLoader``
+    - ``render_static.loaders.django.StaticLocMemLoader``
+
+- ``render_static.backends.StaticJinja2Templates``
+    - ``render_static.loaders.jinja2.StaticFileSystemBatchLoader`` **default**
+    - ``render_static.loaders.jinja2.StaticFileSystemLoader``
+    - ``render_static.loaders.jinja2.StaticPackageLoader``
+    - ``render_static.loaders.jinja2.StaticPrefixLoader``
+    - ``render_static.loaders.jinja2.StaticFunctionLoader``
+    - ``render_static.loaders.jinja2.StaticDictLoader``
+    - ``render_static.loaders.jinja2.StaticChoiceLoader``
+    - ``render_static.loaders.jinja2.StaticModuleLoader``
+
+.. note::
+    The static template engine supports batch rendering. All loaders that have ``Batch`` in the name
+    support wild cards and glob-like patterns when loading templates. By default, if no loaders are
+    specified these loaders are used. For instance, if I wanted to render every .js file in a
+    directory called static_templates/js I could configure templates like so:
 
-The normal Jinja2 loaders are used for the ``StaticJinja2Templates`` backend.
+.. code-block:: python
+
+    'templates': {
+        'js/*.js': {}
+    }
 
 ``context``
 -----------
@@ -126,31 +151,58 @@ there is no request object to build context off of. Dynamic templates are also o
 contextual data built from the database but static templates are only rendered at deployment time,
 so stuffing dynamic database information in static template contexts is not advisable.
 
+Context configuration parameters may be any of the following:
+
+    - **dictionary**: Simply specify context dictionary inline
+    - **callable**: That returns a dictionary. This allows lazy context initialization to take
+      place after Django bootstrapping
+    - **json**: A path to a JSON file
+    - **yaml**: A path to a YAML file (yaml supports comments!)
+    - **pickle**: A path to a python pickled dictionary
+    - **python**: A path to a python file. The locals defined in the file will
+      comprise the context.
+    - **a packaged resource**: Any of the above files imported as a packaged resource via
+      :ref:`resource` to any of the above files.
+    - **import string**: to any of the above.
+
+For example:
+
+.. code-block:: python
+
+      from render_static import resource
+      STATIC_TEMPLATES = {
+        'context': resource('package.module', 'context.yaml')
+      }
+
+
 ``templates``
 -------------
 
-The ``templates`` dictionary lists all templates that should be generated when `render_static` is
+The ``templates`` dictionary lists all templates that should be generated when `renderstatic` is
 run with no arguments. If specific configuration directives including rendered path and context are
 needed for a template they must be specified here.
 
 .. note::
 
-    `render_static` will be able to generate templates not listed in ``templates``, but only if
-    supplied by name on the command line. Only the default context will be available to them.
+    `renderstatic` will be able to generate templates not listed in ``templates``, but only if
+    supplied by name on the command line. Contexts may also be augmented/overridden via the command
+    line.
 
 ``dest``
 ~~~~~~~~
 
 Override the default destination where a template will be rendered. Templates loaded from ``DIRS``
-instead of apps do not have a default destination and must be provided one here. The ``dest``
-parameter must contain the full path where the template will be rendered including the file name.
-
+instead of apps do not have a default destination and must be provided one here. When rendering a
+single template, if the ``dest`` parameter is not an existing directory, it will be assumed to be
+the full path including the file name where the template will be rendered. When rendering in batch
+mode, ``dest`` will be treated as a directory and created if it does not exist.
 
 ``context``
 ~~~~~~~~~~~
 
 Provide additional parameters for each template in the ``context`` dictionary. Any context variables
-specified here that clash with global context variables will override them.
+specified here that clash with global context variables will override them. May be specified using
+any of the same context specifiers that work for the global context.
 
 
 ``RENDER_STATIC_REVERSAL_LIMIT``

doc/source/index.rst

@@ -11,8 +11,10 @@ defines, or enum like structures in server side Python code that are simply repl
 side JavaScript. Single-sourcing these structures by generating client side code from the server
 side code maintains DRYness.
 
-Have you ever wished you could replicate Django's `reverse` function in a JavaScript library for
-your site? Now you can with the `urls_to_js` template tag included with `django-render-static`.
+`django-render-static` includes builtins for:
+    - Replicating Django's `reverse` function in JavaScript (:ref:`urls_to_js`)
+    - Auto-translating Python class and module structures into JavaScript
+      (:ref:`modules_to_js`, :ref:`classes_to_js`)
 
 You can report bugs and discuss features on the
 `issues page <https://github.com/bckohan/django-render-static/issues>`_.

doc/source/installation.rst

@@ -25,9 +25,9 @@ Installation
                 }
         }
 
-4. Run ``render_static`` preceding every run of ``collectstatic`` ::
+4. Run ``renderstatic`` preceding every run of ``collectstatic`` ::
 
-        manage.py render_static
+        manage.py renderstatic
         manage.py collectstatic