Move to jinja2

[palindromed]

No description provided.

[tseaver]

@palindromed Thanks for the patch! Is there some out-of-band discussion about the motivation?

Although I prefer Chameleon myself, I can almost see a case for it for the starter scafflod, which otherwise exposes very little of Pyramid's Zopeish roots. OTOH, avoiding Chameleon in the zodb scaffold seems a very strange choice: I would bet that a large majority of folks interested in using ZODB with Pyramid (e.g., Plone developers) would already be familiar with ZPT/Chameleon, making it an easier transition for them,

[stevepiercy]

@tseaver this is one of the items in issue #2384.

It comes down to which audience would feel the least pain: all new users to Pyramid or a subset of that group, Plone developers. If I had to guess what is the percentage of Plone developers of the whole new to Pyramid users, I'd say no more than 5%. There are far more Django and Flask developers trying out Pyramid and seeking help in #pyramid on IRC.

[stevepiercy]

tox now passes:

$ tox -e{py27,py34,py35,pypy}-scaffolds

[tseaver]

Plone developers. If I had to guess what is the percentage of Plone developers of the whole new to Pyramid users, I'd say no more than 5%. There are far more Django and Flask developers trying out Pyramid and seeking help in #pyramid on IRC.

How many of the Django / Flask developers you encounter care about the zodb scaffold, though?

[stevepiercy]

None or very few, because they don't know about it at first. We mention traversal and ZODB sometimes, especially when they want to learn as much as possible about what Pyramid offers.

Grabbing Google Analytics data, looking at only the index pages of both tutorials, about 5 times as many users visit the SQL wiki tutorial than the ZODB wiki tutorial. Some may visit just one or both.

[mmerickel]

I agree with @tseaver that we should leave the zodb scaffold as using chameleon.

[stevepiercy]

@mmerickel @tseaver that would mean

• reverting today's work on the ZODB scaffold
• changing course on deprecate pcreate and update scaffolds to cookiecutter #2384

Is that correct and what you think is best?

[mmerickel]

I don't understand what #2384 has to do with this? That's about splitting out cookiecutter scaffolds, not about changing the templates for zodb.

[stevepiercy]

#2384 is about making it easier to create a project. Jinja2 is the most familiar templating language. I created the checklist on Jun 5, including the switch to Jinja 2 templates, as a result of conversations at the PyCon sprints. Since then I have added to it as I uncovered more tasks.

[mmerickel]

zodb is more likely to be used by people coming from the plone community which also uses zope templates, which is what chameleon is built on. I think keeping that tutorial focused on that community is a smarter plan going forward. I apologize I hadn't thought through the implications of switching all of the scaffolds to jinja2 in that issue until @tseaver mentioned it today.

[stevepiercy]

OK, I just want to make sure that we're all on the same page. We'll revert the ZODB changes, keep the starter scaffold changes, and move forward. We'll pick it up tomorrow when sprints resume.

[stevepiercy]

I thought again about this issue last night while conversing with @calvinhp and @mcdonc. I'm reversing my position because:

• We can retain the cookiecutter that uses Chameleon, duplicate it, and modify the copy to use Jinja2.
• Jinja2 is the most widely used Python templating language and is familiar to those who use templating in other languages (e.g., JavaScript, PHP).
• Brand spanking new users would have to learn only one templating language to work through all the tutorials instead of two
• Tutorials are focused on new users, not the seasoned developer who is more likely to dive into the API and narrative docs for how to do a specific thing than a tutorial.
• I described this issue to several Plonistas and trainers here at ploneconf, and they unanimously said use one templating language and use Jinja2.
• Plonistas already know how to template, and can easily adjust from Chameleon to Jinja2

Sorry to vacillate.

[mmerickel]

We can retain the cookiecutter that uses Chameleon, duplicate it, and modify the copy to use Jinja2.

If you want to maintain one cookiecutter that uses chameleon and one that uses jinja2 that just seems like you're adding more maintenance burden on yourself for little benefit. There will already be 2 of 3 scaffolds (3 of 4 if you could pyramid_jinja2's scaffold) that use jinja2. I think keeping one that uses something else is not so bad.

Jinja2 is the most widely used Python templating language and is familiar to those who use templating in other languages (e.g., JavaScript, PHP).

Mako itself is also incredibly popular and we don't have any of those.

Brand spanking new users would have to learn only one templating language to work through all the tutorials instead of two

Tutorials are focused on new users, not the seasoned developer who is more likely to dive into the API and narrative docs for how to do a specific thing than a tutorial.

The point of tutorials is to learn new things and see new ways of doing things. Not to show you what you already know. They are both beginner tutorials - they aren't building on top of each other in which you would keep some things similar to show more advanced concepts.

I will defer to the majority but it'd be good to hear what @tseaver has to say as well as he originally raised the issue. I personally see no issue with keeping one of our 3 tutorials using pyramid_chameleon. A lot of your arguments could easily be applied to dropping the ZODB scaffold entirely as it's not nearly as popular as SQLAlchemy and not like anything people use in other languages (Java, Ruby, PHP). I'd prefer not to do that of course.

[tseaver]

I'm still strongly in favor of leaving Chameleon in place as the templating language for the zodb scaffold. One of Pyramid's strengths compared to Django is that we don't force everybody into a single mold: having the crowd who would never even consider using ZODB dictate the default templating language for those who do seems just wrong.

[stevepiercy]

@tseaver In the checklist from #2384:

• Duplicate zodb cookiecutter, rename copy to pyramid-cookiecutter-zodb-chameleon, retain it in perpetuity

Would that satisfy the concern you expressed?

@mmerickel in the Quick Tutorial and Quick Tour, we address how to configure different templating languages from the default:

• http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tour.html#templating
• http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/jinja2.html

When I train new users using both of the wiki tutorials, I hit a point of friction where I have to explain different templating languages instead of focusing on the differences between ZODB and SQL databases.

[mmerickel]

I'm sorry but I don't see how adding a 4th scaffold is good for anyone here. It's more maintenance and I'm sure you'll argue next to make the zodb-chameleon scaffold the version that is not explained in the wiki tutorial, so it's just dangling somewhere with no real docs (similar to starter, but that one's simpler and more self-explanatory).

I respect the issue with explaining things to new users, but that is a benefit of Pyramid in that it can support many different configurations. And yes, any system that does that is inherently harder to explain.

I'm strongly -1 on dropping chameleon from the zodb scaffold as well as changing the tutorial to use zodb+jinja2. Newcomers need to be able to choose what they want to use and the best we can do is provide examples that they can use wholesale or pick apart and use.

[blaflamme]

I'm also with @tseaver on this, thats common sense

Sent from my iPhone

On Oct 22, 2016, at 16:49, Michael Merickel notifications@github.com wrote:

I agree with @tseaver that we should leave the zodb scaffold as using chameleon.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub, or mute the thread.

[davisagli]

For what it's worth, everyone at the Pyramid table at the Plone Conference sprint agreed that they did not have a strong opinion about which template system to use, and that there might be some benefit to using the same one in all the tutorials so that the focus is on other differences.

[stevepiercy]

I'm sorry but I don't see how adding a 4th scaffold is good for anyone here.

@mmerickel we're talking about adding a fourth cookiecutter, not a fourth scaffold, in order to mitigate the switch from Chameleon to Jinja2 in the ZODB wiki tutorial. Furthermore we're talking about removing all scaffolds and using cookiecutters to start a project in a future release.

I'm sure you'll argue next to make the zodb-chameleon scaffold the version that is not explained in the wiki tutorial, so it's just dangling somewhere with no real docs

We don't provide any docs now about templating language syntax or usage, other than how to switch between them (update setup.py, pip install -e ., use new template language).

Newcomers need to be able to choose what they want to use and the best we can do is provide examples that they can use wholesale or pick apart and use.

We do this now:

• http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tour.html#templating
• http://docs.pylonsproject.org/projects/pyramid/en/latest/quick_tutorial/jinja2.html

With fewer differences between the two wiki tutorials, it makes it easier to compare and contrast the functional differences between ZODB and SQL based wiki applications. Preserving one more difference does not make sense, especially when it is explained elsewhere in the documentation. It increases the burden to new users to become familiar with yet another templating language syntax and structure.

[mmerickel]

@mmerickel we're talking about adding a fourth cookiecutter, not a fourth scaffold, in order to mitigate the switch from Chameleon to Jinja2 in the ZODB wiki tutorial. Furthermore we're talking about removing all scaffolds and using cookiecutters to start a project in a future release.

I'm using scaffold and cookiecutter interchangeably because I still plan to maintain them for a while so they aren't very different to me. Sorry if that wasn't clear. Of course the issue which this work is going under is the one I created, so I'm not sure why you're trying to tell me this.

We don't provide any docs now about templating language syntax or usage, other than how to switch between them (update setup.py, pip install -e ., use new template language).

Neither do we provide any docs for zodb or sqlalchemy.

We do this now:

You are tunnel-visioning on the differences between ZODB and SQLAlchemy and arguing that it's the only thing that matters. I wholly disagree and think that providing concrete examples of alternate, and fully supported, configurations is a good thing and templating languages is one area where this is good. How many new users legitimately even consider ZODB? I'd argue for dropping the entire scaffold before modifying it if we just want to go with the most popular thing. However I don't want to argue for that because I think showing concrete, working apps, with different configurations, that people can compare, is very useful.

[stevepiercy]

You are tunnel-visioning on the differences between ZODB and SQLAlchemy

I'd call it focusing on the functional differences, and avoiding the distractions, which is a good thing for new users.

One more new point, for documentation maintainers, it is one fewer thing to pause upon and compare and contrast. It would significantly reduce my maintenance effort to keep the two tutorials as similar as possible. The current difference gets in my way every time I update the two.

How many new users legitimately even consider ZODB?

From above.

Grabbing Google Analytics data, looking at only the index pages of both tutorials, about 5 times as many users visit the SQL wiki tutorial than the ZODB wiki tutorial.

I have no idea how to measure "legitimately even consider ZODB" with any accuracy, but that's the best indicator of relative usage between the two.

When I introduce ZODB to new users in trainings, they are excited to try out the ZODB wiki tutorial and compare it to the SQL wiki tutorial, but most of them pause whenever they hit an unfamiliar templating language (Chameleon) in ZODB.

[digitalresistor]

I have a hard time understanding why we have a tutorial delivering the same end goal with two vastly different database systems.

I find it very difficult to understand why someone would use a Pyramid tutorial to do a compare/contrast of database systems (ZODB vs SQL).

IMHO they could be different tutorials that stand on their own. Showcase some of the strengths of ZODB, like nesting and traversal, stuff that is more difficult in SQL.

Then having them use two different templating languages won't change anything. If someone is going through the docs and they first learn the Wiki with SQLAlchemy and Jinja2 they can then go through the ZODB tutorial and learn how to build a arbitrary nested folder structure site using Chameleon for templating for example.

I think we would be doing even beginners a disservice if we limited ourselves to just Jinja2. I personally much prefer mako over Jinja2 (Jinja feels so much more limiting) but there is limited information, let alone a tutorial, on how to switch to another templating system.

[stevepiercy]

I have a hard time understanding why we have a tutorial delivering the same end goal with two vastly different database systems.

I find it very difficult to understand why someone would use a Pyramid tutorial to do a compare/contrast of database systems (ZODB vs SQL).

The ZODB wiki tutorial is a gateway drug to ZODB and traversal, coming from SQLAlchemy and URL dispatch (and their counterparts in other programming languages and frameworks). Those are not insignificant features to compare and absorb.

Showcase some of the strengths of ZODB, like nesting and traversal, stuff that is more difficult in SQL.
...
go through the ZODB tutorial and learn how to build a arbitrary nested folder structure site using Chameleon for templating for example.

I'd like to showcase ZODB's strengths, too, but the current state of the ZODB+traversal wiki tutorial does not do that. It is a replacement for doing the same things as those in the SQLAlchemy+URL dispatch tutorial, but without using nesting or other compelling ZODB+traversal features.

Now if the ZODB+traversal wiki tutorial were enhanced to showcase the features and strengths of both ZODB and traversal, AND only Chameleon is capable of rendering said features, then it would make sense to me to keep Chameleon in the ZODB scaffold and tutorial.

I couldn't find any showcase of template language features in the docs (including the Pyramid Community Cookbook). Nor could I find a relevant feature comparison between any two of Jinja2, Chameleon, mako, or Django templates.

[blaflamme]

I'd like to showcase ZODB's strengths, too, but the current state of the ZODB+traversal wiki tutorial does not do that. It is a replacement for doing the same things as those in the SQLAlchemy+URL dispatch tutorial, but without using nesting or other compelling ZODB+traversal features.

It's normal since the ZODB+traversal tutorial existed before the SQLAlchemy+URL dispatch tutorial by the time of repoze.bfg. So in fact the SQLAlchemy+URL dispatch tutorial is a replacement for doing the same things as those in the ZODB+traversal tutorial and it was done when repoze.bfg became pyramid to help pylons people feel home.

At some point it's sad to see the diversity pyramid provides getting lost at the cost of looking like other frameworks like flask and django instead of showing what makes us different :(

[blaflamme]

To correct myself, both existed in repoze.bfg and I'm almost sure ZODB+traversal existed first. Also their project names are still the same, wiki == ZODB+traversal and wiki2 == SQLAlchemy+URL dispatch, but we inverse them in listings and how we prioritize URL dispatch over traversal.

[stevepiercy]

They are replacements for one another, depending on your perspective—either historical or modern.

[stevepiercy]

It sounds like I'm the only person who advocates a switch to Jinja2 from Chameleon for the zodb scaffold, so I will step aside and not oppose whatever is needed to get this PR accepted by the majority.