documentation updated

bckohan · bckohan · commit 90fb9802a9ea · 2021-04-21T13:01:13.000-07:00
diff --git a/README.rst b/README.rst
@@ -209,9 +209,8 @@ Your settings file might look like:
                 'loaders': [
                     ('render_static.loaders.StaticLocMemLoader', {
                         'urls.js': (
-                            'var urls = {\n
-                                {% urls_to_js exclude=exclude %}
-                            \n};'
+                            '{% urls_to_js visitor="render_static.ClassURLWriter" '
+                            'exclude=exclude %}'
                         )
                     })
                  ],
@@ -255,31 +254,49 @@ Then urls.js will look like this:
 
 .. code:: javascript
 
-    var urls = {
-        "simple": function(kwargs={}, args=[]) {
-            if (Object.keys(kwargs).length === 0 && args.length === 0)
-                return "/simple";
-            if (
-                Object.keys(kwargs).length === 1 &&
-                ['arg1'].every(value => kwargs.hasOwnProperty(value))
-            )
-                return `/simple/${kwargs["arg1"]}`;
-            throw new TypeError("No reversal available for parameters at path: simple");
-        },
-        "different": function(kwargs={}, args=[]) {
-            if (
-                Object.keys(kwargs).length === 2 &&
-                ['arg1','arg2'].every(value => kwargs.hasOwnProperty(value))
-            )
-                return `/different/${kwargs["arg1"]}/${kwargs["arg2"]}`;
-            throw new TypeError("No reversal available for parameters at path: different");
+    class URLResolver {
+
+        match(kwargs, args, expected) {
+            if (Array.isArray(expected)) {
+                return Object.keys(kwargs).length === expected.length &&
+                    expected.every(value => kwargs.hasOwnProperty(value));
+            } else if (expected) {
+                return args.length === expected;
+            } else {
+                return Object.keys(kwargs).length === 0 && args.length === 0;
+            }
         }
-    }
+
+        reverse(qname, kwargs={}, args=[]) {
+            let url = this.urls;
+            for (const ns of qname.split(':')) {
+                if (ns && url) { url = url.hasOwnProperty(ns) ? url[ns] : null; }
+            }
+            if (url) {
+                let pth = url(kwargs, args);
+                if (typeof pth === "string") { return pth; }
+            }
+            throw new TypeError(`No reversal available for parameters at path: ${qname}`);
+        }
+
+        urls = {
+            "simple": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args)) { return "/simple/"; }
+                if (this.match(kwargs, args, ['arg1'])) { return `/simple/${kwargs["arg1"]}`; }
+            },
+            "different": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args, ['arg1','arg2'])) {
+                    return `/different/${kwargs["arg1"]}/${kwargs["arg2"]}`;
+                }
+            },
+        }
+    };
 
 
 So you can now fetch paths like this:
 
 .. code:: javascript
 
     // /different/143/emma
-    urls.different({'arg1': 143, 'arg2': 'emma'});
+    const urls = new URLResolver();
+    urls.reverse('different', {'arg1': 143, 'arg2': 'emma'});
diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst
@@ -3,6 +3,19 @@ Change Log
 ==========
 
 
+v1.0.0
+====================
+
+* New abstract visitor pattern allows customization of generated URL resolution javascript
+* A class generator is included which generates fully-fledged JavaScript class that includes a
+  `reverse` function for urls that's directly analogous to Django's `reverse` function.
+* More common placeholders have been added as defaults that are always attempted if no
+  registered placeholders are found to work, this should increase the success rate of
+  out-of-the box URL generation.
+* Removed Jinja2 as a direct dependency - it is now in extras.
+* API is now considered production/stable.
+
+
 v0.1.1
 ====================
 
diff --git a/doc/source/reference.rst b/doc/source/reference.rst
@@ -80,3 +80,28 @@ placeholders
    .. autofunction:: register_unnamed_placeholders
    .. autofunction:: resolve_placeholders
    .. autofunction:: resolve_unnamed_placeholders
+
+
+.. _javascript:
+
+javascript
+----------------------------------------------------------------
+
+.. automodule:: render_static.javascript
+
+   .. autoclass:: JavaScriptGenerator
+
+
+.. _url_tree:
+
+url_tree
+----------------------------------------------------------------
+
+.. automodule:: render_static.url_tree
+
+   .. autoclass:: URLTreeVisitor
+   .. autoclass:: SimpleURLWriter
+   .. autoclass:: ClassURLWriter
+   .. autoclass:: Substitute
+   .. autofunction:: normalize_ns
+   .. autofunction:: build_tree
diff --git a/doc/source/templatetags.rst b/doc/source/templatetags.rst
@@ -113,19 +113,35 @@ Tags
 ``urls_to_js``
 ~~~~~~~~~~~~~~
 
-This tag spits out a JavaScript object that can be used in the same manner as Django's URL
-`reverse <https://docs.djangoproject.com/en/3.1/ref/urlresolvers/#reverse>`_ function.
+Often client side JavaScript needs to fetch site URLs asynchronously. These instances either
+necessitate using dynamic templating to reverse the url via the `url` tag or to hardcode the path
+into the JavaScript thereby violating the DRY principle. Frequently the need to generate these paths
+are the only thing driving the need to generate the JavaScript dynamically. But these paths might
+change only at deployment, not runtime, so the better approach is to generate JavaScript at
+deployment time and serve it statically. This tag makes that process even easier by automatically
+translating the site's url configuration into a JavaScript utility that can be used in the same
+manner as Django's URL `reverse <https://docs.djangoproject.com/en/3.1/ref/urlresolvers/#reverse>`_
+function.
 
 It accepts a number of different parameters:
 
+    - **visitor** A string import path or a class that implements `URLTreeVisitor`. The visitor
+      walks the URL tree and generates the JavaScript, users may customize the JavaScript generated
+      by implementing their own visitor class. Two visitors are included. The default,
+      `SimpleURLWriter`, spits out an object structure that indexes paths by their namespaces. The
+      `ClassURLWriter`, spits out ES5 or 6 classes that provide a `reverse` function directly
+      analogous to Django's reverse function.
     - **url_conf** The root url module to dump urls from. Can be an import string or an actual
       module type. default: settings.ROOT_URLCONF
-    - **indent** String to use for indentation in javascript, default: '\\t'
+    - **indent** String to use for indentation in javascript, default: '\\t', If None or the empty
+      string is specified, the generated code will not contain newlines.
     - **depth** The starting indentation depth, default: 0
     - **include** A list of path names to include, namespaces without path names will be treated as
       every path under the namespace. Default: include everything
     - **exclude** A list of path names to exclude, namespaces without path names will be treated as
       every path under the namespace. Excludes override includes. Default: exclude nothing
+    - **raise_on_not_found** If True (default), the generated JavaScript will raise a TypeError if
+      asked to reverse an unrecognized URL name or set of arguments.
     - **es5** If True, dump es5 valid JavaScript, if False JavaScript will be es6, default: False
 
 Includes and excludes are hierarchical strings that contain the fully qualified name of a namespace
@@ -136,6 +152,12 @@ not include paths directly under `namespace1`. Excludes always override includes
 path is included and no paths are excluded. If any includes are provided, then only those includes
 are included (everything else is by default excluded).
 
+.. note::
+
+    When implementing custom URL visitors, any additional named arguments passed to the `urls_to_js`
+    tag will be passed as kwargs to the URL visitor when this tag instantiates it. These parameters
+    are meant to provide configuration toggles for the generated JavaScript.
+
 .. warning::
 
     All the URLs embedded in JavaScript are exposed client side. Its never a good idea to have site
@@ -240,3 +262,60 @@ Paths with unnamed arguments are also supported, but be kind to yourself and don
 Any number of placeholders may be registered against any number of variable/app_name combinations.
 When `urls_to_js` is run it won't give up until its tried all placeholders that might potentially
 match the path.
+
+`ClassURLWriter`
+****************
+
+A visitor class that produces ES5/6 JavaScript class is now included. This class is not used by
+default, but should be the preferred visitor for larger, more complex URL trees - mostly because
+it minifies better than the default `SimpleURLWriter`. To use the class writer::
+
+    {% urls_to_js visitor='render_static.ClassURLWriter' class_name='URLReverser' %}
+
+This will generate an ES6 class by default::
+
+    class URLReverser {
+
+        match(kwargs, args, expected) {
+            if (Array.isArray(expected)) {
+                return Object.keys(kwargs).length === expected.length &&
+                    expected.every(value => kwargs.hasOwnProperty(value));
+            } else if (expected) {
+                return args.length === expected;
+            } else {
+                return Object.keys(kwargs).length === 0 && args.length === 0;
+            }
+        }
+
+        reverse(qname, kwargs={}, args=[]) {
+            let url = this.urls;
+            for (const ns of qname.split(':')) {
+                if (ns && url) { url = url.hasOwnProperty(ns) ? url[ns] : null; }
+            }
+            if (url) {
+                let pth = url(kwargs, args);
+                if (typeof pth === "string") { return pth; }
+            }
+            throw new TypeError(`No reversal available for parameters at path: ${qname}`);
+        }
+
+        urls = {
+            "simple": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args)) { return "/simple/"; }
+                if (this.match(kwargs, args, ['arg1'])) { return `/simple/${kwargs["arg1"]}`; }
+            },
+            "different": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args, ['arg1','arg2'])) {
+                    return `/different/${kwargs["arg1"]}/${kwargs["arg2"]}`;
+                }
+            },
+        }
+    };
+
+Which can be used as::
+
+    // /different/143/emma
+    const urls = new URLReverser();
+    urls.reverse('different', {'arg1': 143, 'arg2': 'emma'});
+
+The default `class_name` is URLResolver. Reverse should behave exactly as Django's `reverse`.
diff --git a/doc/source/tldr.rst b/doc/source/tldr.rst
@@ -4,7 +4,7 @@
 TL/DR
 =====
 
-First go back to the install page and install `django-render-static` you lazy bum.
+First go back to the install page and install `django-render-static` if you haven't!
 
 Generating Javascript Defines
 -----------------------------
@@ -110,9 +110,8 @@ Your settings file might look like::
                 'loaders': [
                     ('render_static.loaders.StaticLocMemLoader', {
                         'urls.js': (
-                            'var urls = {\n
-                                {% urls_to_js exclude=exclude %}
-                            \n};'
+                            '{% urls_to_js visitor="render_static.ClassURLWriter" '
+                            'exclude=exclude %}'
                         )
                     })
                  ],
@@ -150,34 +149,57 @@ If your root urls.py looks like this::
 
 Then urls.js will look like this::
 
-    var urls = {
-        "simple": function(kwargs={}, args=[]) {
-            if (Object.keys(kwargs).length === 0 && args.length === 0)
-                return "/simple";
-            if (
-                Object.keys(kwargs).length === 1 &&
-                ['arg1'].every(value => kwargs.hasOwnProperty(value))
-            )
-                return `/simple/${kwargs["arg1"]}`;
-            throw new TypeError("No reversal available for parameters at path: simple");
-        },
-        "different": function(kwargs={}, args=[]) {
-            if (
-                Object.keys(kwargs).length === 2 &&
-                ['arg1','arg2'].every(value => kwargs.hasOwnProperty(value))
-            )
-                return `/different/${kwargs["arg1"]}/${kwargs["arg2"]}`;
-            throw new TypeError("No reversal available for parameters at path: different");
+    class URLResolver {
+
+        match(kwargs, args, expected) {
+            if (Array.isArray(expected)) {
+                return Object.keys(kwargs).length === expected.length &&
+                    expected.every(value => kwargs.hasOwnProperty(value));
+            } else if (expected) {
+                return args.length === expected;
+            } else {
+                return Object.keys(kwargs).length === 0 && args.length === 0;
+            }
         }
-    }
+
+        reverse(qname, kwargs={}, args=[]) {
+            let url = this.urls;
+            for (const ns of qname.split(':')) {
+                if (ns && url) { url = url.hasOwnProperty(ns) ? url[ns] : null; }
+            }
+            if (url) {
+                let pth = url(kwargs, args);
+                if (typeof pth === "string") { return pth; }
+            }
+            throw new TypeError(`No reversal available for parameters at path: ${qname}`);
+        }
+
+        urls = {
+            "simple": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args)) { return "/simple/"; }
+                if (this.match(kwargs, args, ['arg1'])) { return `/simple/${kwargs["arg1"]}`; }
+            },
+            "different": (kwargs={}, args=[]) => {
+                if (this.match(kwargs, args, ['arg1','arg2'])) {
+                    return `/different/${kwargs["arg1"]}/${kwargs["arg2"]}`;
+                }
+            },
+        }
+    };
 
 So you can now fetch paths like this::
 
     // /different/143/emma
-    urls.different({'arg1': 143, 'arg2': 'emma'});
+    const urls = new URLResolver();
+    urls.reverse('different', {'arg1': 143, 'arg2': 'emma'});
 
 
-.. note::
+.. warning::
 
     If you get an exception when you run render_static that originated from a PlaceholderNotFound
     exception, you need to register some :ref:`placeholders` before calling :ref:`urls_to_js`.
+
+.. note::
+    The JavaScript URL resolution is guaranteed to produce the same paths as Django's reversal
+    mechanism. If it does not, this is a bug and we kindly ask
+    `you to report it <https://github.com/bckohan/django-render-static/issues>`_.
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-render-static"
-version = "0.1.1"
+version = "1.0.0"
 description = "Use Django's template engine to render static files at deployment time. Extend Django's url reverse mechanism to JavaScript."
 authors = ["Brian Kohan <bckohan@gmail.com>"]
 license = "MIT"
@@ -13,7 +13,7 @@ classifiers = [
     "Framework :: Django",
     "Operating System :: OS Independent",
     "Topic :: Software Development :: Libraries :: Python Modules",
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Framework :: Django :: 2.2",
     "Framework :: Django :: 3.0",
     "Framework :: Django :: 3.1",
diff --git a/render_static/javascript.py b/render_static/javascript.py
@@ -11,11 +11,17 @@ class JavaScriptGenerator(metaclass=ABCMeta):
 
     To use this class derive from it and implement generate().
 
-    :param kwargs: A set of configuration parameters for the generator, including:
-        - depth: the integer starting indentation level, default: 0
-        - indent: the string to use as the indentation string. May be None or empty string for
-            no indent which will also cause no newlines to be inserted, default: \t
-        - es5: If true, generated JavaScript will be valid es5.
+    The configuration parameters that control the JavaScript output include:
+
+        * *depth*
+            the integer starting indentation level, default: 0
+        * *indent*
+            the string to use as the indentation string. May be None or empty string for no indent
+            which will also cause no newlines to be inserted, default: \t
+        * *es5*
+            If true, generated JavaScript will be valid es5.
+
+    :param kwargs: A set of configuration parameters for the generator, see above.
     """
 
     rendered_ = ''
diff --git a/render_static/placeholders.py b/render_static/placeholders.py
@@ -32,7 +32,7 @@
     'resolve_unnamed_placeholders'
 ]
 
-ALWAYS_TRY_THESE = [0, 'a', 1, 'A']
+ALWAYS_TRY_THESE = [0, 'a', 1, 'A', 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa']
 
 converter_placeholders: Dict[Type, List] = {
     converters.IntConverter: [0],
diff --git a/render_static/tests/tests.py b/render_static/tests/tests.py
diff --git a/render_static/url_tree.py b/render_static/url_tree.py

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@`
`32`	`32`	`'resolve_unnamed_placeholders'`
`33`	`33`	`]`
`34`	`34`
`35`		`-ALWAYS_TRY_THESE = [0, 'a', 1, 'A']`
	`35`	`+ALWAYS_TRY_THESE = [0, 'a', 1, 'A', 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa']`
`36`	`36`
`37`	`37`	`converter_placeholders: Dict[Type, List] = {`
`38`	`38`	`converters.IntConverter: [0],`