bckohan/django-render-static

Use Django's template engine(s) to render static files at deployment or package time. Includes transpilers for extending Django's url reversal and enums to JavaScript.

django-render-static's Issues

Change all filters to tags

Migrate all of the legacy transpiler filters to tags.

Add set of common placeholders to always try

Most url arguments are fairly simple and most cases can be handled with a common set of simple string and integer placeholders. Add these to the placeholders to try for url reversal to drastically increase the number of urls that work "out of the box".

Implement node.js tests for all js2py tests.

Entirely drop dependency on Js2Py.

Allow 'lazy' contexts built after Django bootstrapping

Right now, static files are limited to context's specifiable directly in settings. Richer behavior can be produced if implemented directly in template tags, but there should be a way to build a context off the Django stack post-initialization (i.e. have access to the database).

TypeScript transpilers

Jinja2 shouldnt be a required depenency

Only require Jinja2 if it's engine is used.

Support backup destination to STATIC_ROOT on permissions error

If static_templates are delivered with a package downloaded from pypi into a repo, render_static might not have permissions to render those files into the app's static directories. Default behavior should be to use STATIC_ROOT as a backup in the case of permissions error.

Current workaround is to just provide a destination.

Support python 3.11

Will have to drop test dependencies on js2py for this.

Upgrade build tooling to poetry 1.2

Poetry 1.2 is finally here. Includes breaking changes and requires pyproject.toml updates to work.

Extension points for transpiled code.

Should be able to do something like this:

{% enums_to_js enums=enums %}
  
  {% override 'get' %}
  static get(value) {
     if ( < custom value mapping >) {
         return {{ class_name }}.ENUM_VALUE;
     }
     {{ default_impl }} <!-- transpiler puts default get function code here -->
  }
  {% endoverride %}

{% endenums_to_js %}

urls_to_js namespace argument

Add a namespace argument to the ES6 URLResolver class that will be prefixed to all lookups.

Support 'package' time rendering

Right now, render_static is meant to be run at deployment time, before collectstatic is run. This works best for apps that are part of source of the site being deployed.

Reusable apps packaged into repositories like pypi would want to generate their static files at package time. Is there anything that can be done in render_static to explicitly support this? It would be possible to bootstrap this currently.

Bound complexity of URL Generation

For urls with large numbers of arguments for which specific placeholders are not registered, the guess and check mechanism could produce a complexity explosion. This is a O(n^p) operation where n is the number of potential placeholders to try and p is the number of arguments in the URL.

There should be a, potentially configurable, hard limit on the number of iterations of the guess and check mechanism. An exception should bound the number of iterations of each reversal attempt, which should indicate to the user that more specific placeholders should be registered to speed up reversal success.

urls_to_js output is incorrect when default kwargs specified in path()

    path(
        'qr/<int:qr>/download',
        QRDownloadView.as_view(),
        kwargs={'format': 'png'},
        name='download_qr'
    ),
    path(
        'qr/<int:qr>/download/png',
        QRDownloadView.as_view(),
        kwargs={'format': 'png'},
        name='download_qr'
    ),
    path(
        'qr/<int:qr>/download/svg',
        QRDownloadView.as_view(),
        kwargs={'format': 'svg'},
        name='download_qr'
    ),
    path(
        'qr',
        QRDownloadView.as_view(),
        kwargs={'format': 'svg'},
        name='download_qr'
    )

produces this:

"download_qr": (kwargs={}, args=[]) => {
      kwargs={'qr': {'converter': <class 'django.urls.converters.IntConverter'>, 'app_name': 'demoply.qr'}} */
      kwargs={'qr': {'converter': <class 'django.urls.converters.IntConverter'>, 'app_name': 'demoply.qr'}} */
      if (this.match(kwargs, args, ['qr'])) { return `/qr/${kwargs["qr"]}/download/svg`; }
      if (this.match(kwargs, args)) { return "/qr"; }
},

Enum support

Provide a python enum based pattern and JS translation tags to single source Model fields with choices.

Django4.0 Support

Run regressions/add CI for Django 4.0.

Combine classes_to_js and modules_to_js into defines_to_js

classes_to_js and modules_to_js are too ambiguous. Remove them, and combine functionality into defines_to_js which is a specialization of transpile that uses the Define visitor transpiler.

Unnamed/named urls of the same name sometimes fail

This is wrong:

urlpatterns = [
    re_path(r'^special1/(?P<choice>(:?first)|(:?second))$', TestView.as_view(), name='special'),
    re_path(r'^special1/(?P<choice>(:?first)|(:?second))/(?P<choice1>(:?first)|(:?second))$', TestView.as_view(), name='special'),
    re_path(r'^special2/((?:first)|(?:second))$', TestView.as_view(), name='special')
]

urls = {
  "special": (kwargs={}, args=[]) => {
	  if (this.match(kwargs, args, 1)) { return `/special2/${args[0]}`; }
  },
}

And when reversed, it throws an exception:

urlpatterns = [
    re_path(r'^special2/((?:first)|(?:second))$', TestView.as_view(), name='special'),
    re_path(r'^special1/(?P<choice>(:?first)|(:?second))$', TestView.as_view(), name='special'),
    re_path(r'^special1/(?P<choice>(:?first)|(:?second))/(?P<choice1>(:?first)|(:?second))$', TestView.as_view(), name='special'),
]

Exclude admin urls by default from urls_to_js output

Just seems like a smart thing to do for security...

Rename render_static -> renderstatic

This might seem overly pedantic, but given the goal to work calls to render_static into deployment processes it would be nice if the casing type was consistent. i.e:

./manage.py renderstatic
./manage.py collectstatic

looks better than:

./manage.py render_static
./manage.py collectstatic

Should deprecate the snake case name and remove in version 2.0.

Max line length from 100 -> 80

Support batch rendering & glob patterns in template selectors

The static template engine is fundamentally different from the dynamic template engine because of the batch-render use case. In a batch-render the loader should return multiple matching files, that each get rendered with the given context.

This change would enable loaders to accept glob patterns and the like. File load should end when the first loader to return non-empty list of files returns.

This has implications for dest. Namely that when multiple files are returned dest must be a directory.

Deprecate render_static command in favor of renderstatic.

Accelerating this move to 1.2 instead of 2.0.

Remove multi-arg call style from url reverse()

URL resolver reverse() function honors an option argument with {kwargs: {}, args: [], query: {}}. But these can also be specified individually on the call (remove this).

Tie in code generation to the docs

All the code examples in the docs should be run or generated directly.

Drop support for python 3.6

Upgrade to poetry 1.2 requires this. 3.6 has also been end of lifed many months ago.

Require importlib-resources for python < 3.9

The resource() function will automatically work in python >3.9. In 3.7-3.8 it requires importlib_resources to be installed as an optional dependency. Change this dependency to required for python versions below 3.9.

Test re_path nested arguments

From the Django docs, this should work:

from django.urls import re_path

urlpatterns = [
    re_path(r'^blog/(page-([0-9]+)/)?$', blog_articles),                  # bad
    re_path(r'^comments/(?:page-(?P<page_number>[0-9]+)/)?$', comments),  # good
]

LICENSE is packaged as source.

LICENSE is not installed correctly.

Disable system checks for renderstatic command

No need for DB to be live...

urls_to_js should gracefully handle default kwargs supplied to path()

Django seems to support path resolution based on default kwargs that are not part of the named parameters on a path. See #65.

Should make a good faith effort to support path resolution based on these parameters. It would involve modifying match() in the javascript to look for named parameters with specific values. This can become tricky because type becomes important. '1' and 1 are treated differently by reverse in the context of a named default parameter value. Not all types will easily extend to Javascript, so some restriction and possible warning should be thrown.

This is a corner case - good patterns should not rely on this and should instead use named parameters with converters that restrict the values if necessary. This pattern has been seen in the wild tho and urls_to_js should "just work" as much as it can.

The key thing to note here is that these default kwargs are essentially named path() parameters for the purposes of reverse - but they lack converters. That this "works" in Django seems almost to be by accident.

Conditionally collect tests requiring optional dependencies

Port all DTL filters and tags to Jinja2

All tag and filters should be offered in both DTL and Jinja2

Refactor classes_to_js and modules_to_js to use JavascriptGenerator pattern.

Unify all python -> javascript transpilation behind the JavascriptGenerator pattern. Will make things like #85 easier.

Set the urls_to_js default visitor to the Class visitor

This is a breaking change that reflects the superiority of ClassURLVisitor to the SimpleURLVisitor. Slate for 2.0.

Include render_static filters and tags in engine be default.

Jinja2 include breaks Jinja2 as optional dependency

File "/Users/bkohan/Library/Caches/pypoetry/virtualenvs/genesis-ed7ge2WL-py3.6/lib/python3.6/site-packages/render_static/engine.py", line 11, in
from django.template.backends.jinja2 import Template as Jinja2Template
File "/Users/bkohan/Library/Caches/pypoetry/virtualenvs/genesis-ed7ge2WL-py3.6/lib/python3.6/site-packages/django/template/backends/jinja2.py", line 3, in
import jinja2
ModuleNotFoundError: No module named 'jinja2'

Provide Pluggable Visitor Pattern to customize generated javascript

As the title says, currently the javascript generated can't be customized. Implement a visitor pattern that will allow users to customize the javascript generated by all the template filters. Also provide a visitor that generates es6 classes that are more minification friendly for urls_to_js.

Default placeholders not activated

If no placeholders are registered the defaults are never tried because an exception is hit.

Lint transpiled javascript code.

Ensure no linting errors on vanilla configuration of javascript linter. Todo which linter?

Add GET query parameters to ClassURLWriter's reverse function

The URLResolver class's reverse function should optionally take kwargs and arg as named options and a query option should be added from which url search parameters will be built.

Change templates config parameter to be a list of tuples.

Its currently impossible to render one template multiple times using different contexts and destinations using just the settings configuration -- this IS possible using multiple invocations of renderstatic. The constraint on settings however is unnecessary.

Change STATIC_TEMPLATES['templates'] to optionally be a list of (template name, {config}) tuples.

Document deployment time vs package time use cases.

Depending on the static templates rendered there are two major use cases for static rendering. Deployment time for things like urls.js and package time for self-contained app artifacts. The nuances involved deserve discussion in the docs.

Flexible context specifiers

Allow contexts to be loaded from:

• json files
• pickled dictionaries
• python modules (locals)
• yaml files
• string file paths, path like objects or packaged resources of any of the above

Provide customization point for all javascript value output.

For instance a user should be able to easily control how a date is transpiled.

Generate JDoc comments in the generated URLResolver class.

Allow contexts to be loaded from paths or resources

Directly support specifying contexts as paths to python/json files or as packaged resources to the same.

Multilevel url arguments not working

url_to_js generation fails if you have arguments on the stem of a url and then include urls onto that stem.

Deprecate es5 support.

Deprecate all es5 specific code generation and move it into separate transpilers. This is now considered beyond the scope of django-render-static and rendered code should be run through an external transpiler like babel if es5 compat is required.

Unify all transpilation tags as specializations of {% transpile %}

The transpilation tags should all be shortcut specializations of a general purpose transpile tag.