Add support for alternatives to simplates

[chadwhitacre]

The simplate file format does not play will with the tooling ecosystem. This PR looks to replace simplates with multiple files per resource, while preserving filesystem dispatch. See #27.

[chadwhitacre]

Here's a gist showing what Gratipay's team page would look like with multiple files (a Jinja template and ... a pyhook?) instead of a single simplate. Editing index.py immediately surfaced a few dead imports, since pyflakes could do its work. ;-)

[chadwhitacre]

In other words, the HTTP method functions in the pyhook are essentially additional algorithm (state chain) functions.

[Changaco]

• Putting the variables directly in the state would lead to conflicts.
• The python file feels like boilerplate, the only thing it's really doing is allowing you to work around Jinja's sandboxing by passing imports.

[chadwhitacre]

The python file feels like boilerplate, the only thing it's really doing is allowing you to work around Jinja's sandboxing by passing imports.

Sure, in the GET case, but that's not that different than the simplate. The POST case is where more work would be done.

[Changaco]

but that's not that different than the simplate

But the simplate isn't a separate file, and its implicit variable passing avoids the boilerplate.

[chadwhitacre]

Just one sec, I think I have an implementation that allows simplates to remain as one option for dynamic resources. Almost have a commit here ...

[Changaco]

In the example above it seems to me that you'd be better off using Mako instead of "pyhook" + Jinja:

+<%!
 """Show information about a single Team. It might be your team!
 """
 from collections import OrderedDict

 from aspen import Response
 from gratipay.utils import excerpt_intro, get_team, markdown

-[-----------------------------------------------------------------------------]
+%>
+<%

 team = get_team(state)
 banner = name = team.name
 suppress_sidebar = not(team.is_approved or user.ADMIN)
 is_team_owner = not user.ANON and team.owner == user.participant.username

-[-----------------------------------------------------------------------------]
-{% extends "templates/team-base.html" %}
+%>
+<%inherit file="templates/team-base.html"/>

+[… the rest of the Jinja template converted to Mako …]

[chadwhitacre]

better off using Mako

Check out e1bb5a8. That allows us to register different dynamic classes based on the file extension, which means we could have plugins for Pyhooks, Mako, Simplates, or whatever.

[chadwhitacre]

Actually, though, I think we should bake in the pyhook concept, because it's optional. If you don't want to use it, just don't have a foo.py file.

[chadwhitacre]

The inverse could also be possible: only have a foo.py file.

[Changaco]

Check out e1bb5a8.

Looks fine to me.

We'll need to further modify the dispatcher to detect conflicting dynamic resources.

You dropped the fs_media_type attribute on simplates, but apparently it wasn't used anywhere.

[chadwhitacre]

Do you think we should try to get this done before 1.0? Seems like if we're planning to still support simplates as an option then it's lower priority than if we were going to drop simplates entirely.

[chadwhitacre]

How about we try to merge this PR sooner rather than later, and then I/we can add the pyhooks feature in a later PR post-1.0?

[chadwhitacre]

Gah ... or maybe pre-1.0? I think I'm going to turn next to the Flask and Django plugins, and I might rather say "pyhooks" than "simplates" in the docs for those. Hmm ...

[chadwhitacre]

@Changaco Do you want to keep simplates? Could you use pyhooks to implement PAGES as you like?

[Changaco]

Do you want to keep simplates?

Yes, until I've determined from experience that they can be entirely replaced by the alternatives without leading to boilerplate or other unpleasantness.

Dropping simplates now would require more work to port liberapay to something else, which would make it harder to get Pando running in production before the 1.0 announcement.

Could you use pyhooks to implement PAGES as you like?

Support for PAGES will need to be put in the Dynamic subclass that handles .py files.

Do you think we should try to get this done before 1.0?

Yes, but not as a priority, so only if we have the time.

[chadwhitacre]

@kaguillera and I just worked through another example, Gratipay's reconciliation dashboard. Here's what we came up with. This illustrates nesting of pyhooks. The request processing state chain is extended with the GET from reconciliation.py when hitting all three of reconciliation.{html,csv,json}, and additionally with the GET from reconciliation.{csv,json}.py in the relevant case. Each of those second GETs updates the request processing state with a response. For the reconciliation.html case, the GET would be followed by a state chain function associated with the jinja2 extension, and that would update the state with a response.

[chadwhitacre]

(The {CSV,JSON}Response classes would be adaptations of the current {csv,json}_dump renderers.)

[Changaco]

As I said earlier, putting stuff in the state will lead to conflicts (remember AspenWeb/pando.py#426?).

[chadwhitacre]

@Changaco Ready for review.

[Changaco]

Looks okay to me. I've renamed the PR to match what it actually does. The changes aren't enough to implement your multiple-files idea (that would require bigger changes to the dispatcher), but they should allow implementing my original proposal from #27, as well as Mako templates, so I guess it's a good first step.