alchemy scaffold updates

[mmerickel]

This is a WIP to bring the alchemy scaffold in line with best practices.

• Remove scoped sessions.
• Connect session to request method.
• Switch to jinja2 templates.
• Add a meta module or package to avoid any circular references when importing.
• Switch models into a package instead of a module.
• Scan docs and tutorials for updates related to the changes. Here is the list of files. See comment below.
  • whatsnew-1.6.rst (Scaffolding Enhancements and Documentation Enhancements sections)
  • Quick Tour sqla_demo generated from scaffold and its associated files in quick_tour/sqla_demo/. Note that there are some comments inserted in these files for Sphinx rendering. See quick_tour.rst, Databases section.
  • quick_tour.rst, Databases section
  • tutorials/wiki2/src/*/tutorial/[authorization|basiclayout|models|tests|views]/ (5 directories)
  • tutorials/wiki2/authorization.rst (13 occurrences)
  • tutorials/wiki2/basiclayout.rst (2 occurrences)
  • tutorials/wiki2/definingmodels.rst (9 occurrences)
  • tutorials/wiki2/definingviews.rst (9 occurrences)
  • tutorials/wiki2/design.rst (4 occurrences)
  • tutorials/wiki2/tests.rst
• Pyramid Cookbook recipes
  • http://docs.pylonsproject.org/projects/pyramid-cookbook/en/latest/auth/wiki2_auth.html (Add a note that this recipe will no longer apply when Pyramid 1.7 is released, and is most likely out of date since Pyramid 1.3. Or maybe just delete it?)
• Add configure_mappers when initializing the session.

[stevepiercy]

I'll take on this todo, and list all the files (see above). That covers it. Most of the changes are easy (changing .pt to .jinja2), but the entire file replacement and any code references to :linenos: and :emphasize-lines: Sphinx directives should be carefully reviewed.

This does not include the community-contributed documentation, like the Cookbook.

I can work on this item when the alchemy scaffold is complete.

[digitalresistor]

Woah... switch to Jinja 2 templates?

[blaflamme]

I would have updated for mako. I don't think getting closer to flask/django is a good thing in the end. I would prefer getting closer to mike's stuff for our defaults if we have to make a choice.

Sent from my iPhone

On Oct 21, 2015, at 20:54, Bert JW Regeer [email protected] wrote:

Woah... switch to Jinja 2 templates?

—
Reply to this email directly or view it on GitHub.

[mmerickel]

I don't mind using jinja2. @pauleveritt uses it in the quick tutorial and I use it in all my projects. Since when is this "closer to flask/django" a good or bad thing? It's a framework-agnostic templating language used in many systems including ansible and salt.

I mean if people feel so strongly about it that's fine but I told @ergo he could use what he wanted since he was willing to do the work.

[ergo]

@blaflamme I was having a hard time to decide on mako/jinja2 since I know and use both for a long time - the reason why I decided on jinja2 was to use something that has a syntax that people are more used to - this lowers the entry barrier a bit which I find a good thing because we want to have more people use pyramid in the end.
If there is a big opposition I don't mind changing to mako instead - especially since its dependency of debugtoolbar, but in the end to switch from one to another it takes just 2 lines of code :)

[pauleveritt]

If we’re going to vote for unique, less-popular templating languages, we should go with the one ChrisM prefers, Chameleon. It’s the original template language for Pyramid. But I don’t think you’d like that choice. [wink]

At the end of the day, we all have different ideas, but Jinja2 and its syntax (Django) are far more popular. We shouldn’t make templating the place where newbies (the audience for a scaffold) thinks we are “different”. Wrong battle to pick, IMO.

—Paul

On Oct 21, 2015, at 9:25 PM, Blaise Laflamme [email protected] wrote:

I would have updated for mako. I don't think getting closer to flask/django is a good thing in the end. I would prefer getting closer to mike's stuff for our defaults if we have to make a choice.

Sent from my iPhone

On Oct 21, 2015, at 20:54, Bert JW Regeer [email protected] wrote:

Woah... switch to Jinja 2 templates?

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub #2024 (comment).

[blaflamme]

@ergo no need to change, I wondered why.

Sent from my iPad

On Oct 22, 2015, at 03:17, Marcin Lulek [email protected] wrote:

@blaflamme I was having a hard time to decide on mako/jinja2 since I know and use both for a long time - the reason why I decided on jinja2 was to use something that has a syntax that people are more used to - this lowers the entry barrier a bit which I find a good thing because we want to have more people use pyramid in the end.
If there is a big opposition I don't mind changing to mako instead.

—
Reply to this email directly or view it on GitHub.

[blaflamme]

@pauleveritt sure, I don't want to bring any battle to the table ;)

But I would have naturally coupled the zodb scaffold with chameleon and the sqla scaffold with mako.

Sent from my iPad

On Oct 22, 2015, at 06:29, Paul Everitt [email protected] wrote:

If we’re going to vote for unique, less-popular templating languages, we should go with the one ChrisM prefers, Chameleon. It’s the original template language for Pyramid. But I don’t think you’d like that choice. [wink]

At the end of the day, we all have different ideas, but Jinja2 and its syntax (Django) are far more popular. We shouldn’t make templating the place where newbies (the audience for a scaffold) thinks we are “different”. Wrong battle to pick, IMO.

—Paul

On Oct 21, 2015, at 9:25 PM, Blaise Laflamme [email protected] wrote:

I would have updated for mako. I don't think getting closer to flask/django is a good thing in the end. I would prefer getting closer to mike's stuff for our defaults if we have to make a choice.

Sent from my iPhone

On Oct 21, 2015, at 20:54, Bert JW Regeer [email protected] wrote:

Woah... switch to Jinja 2 templates?

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub #2024 (comment).

—
Reply to this email directly or view it on GitHub.

[piotr-dobrogost]

How about giving choice and making template system be a parameter of scaffolds? In the end scaffold should be opinionated in regard to its core functionality (SQLAlchemy in this case) and not peripheral things (template system in this case).

[ergo]

@piotr-dobrogost This might be problematic from maintenance perspective since we would have to understand and update all the templates simulatenously whenever anything would change.

@blaflamme At first my initial idea was to use mako, but because of the reasons @mmerickel and @pauleveritt mentioned it felt like the best option to go for jinja2.

[stevepiercy]

The suggestion from @piotr-dobrogost would inform newbies that there are several templating languages. It would also mean more development work, including the hardest task of all, naming things, compounded by the backward compatible alias of --template to --scaffold in pcreate. /play noooo

[mmerickel]

Showing multiple templating systems is great but also overly complex for the purposes of this scaffold and PR. Some future work to create alternate start scaffolds would probably be interesting though. pcreate -s starter-mako etc.

[ergo]

http://cookiecutter.readthedocs.org/en/latest/ - probably has all the functionality needed.

I've been doing some workshops recently introducing pyramid for people, and after got some feedback - especially when evangelizing to people who only did django before - jinja2 seems like a good choice for newcomers. Advanced users can switch to other template engine in few lines of code in the end.

[pauleveritt]

I reached the same conclusion a while back. @cguardia is doing a lot of work on this in https://github.com/cguardia/cookiecutter-pyramid

—Paul

On Oct 22, 2015, at 11:53 AM, Marcin Lulek [email protected] wrote:

http://cookiecutter.readthedocs.org/en/latest/ http://cookiecutter.readthedocs.org/en/latest/ - probably has all the functionality needed.

I've been doing some workshops recently introducing pyramid for people, and after got some feedback - especially when evangelizing to people who only did django before - jinja2 seems like a good choice.

—
Reply to this email directly or view it on GitHub #2024 (comment).

[blaflamme]

Same for me, I've been using cookiecutter for a while for my own stuff and prefer it over scaffolds. We could eventually have official cookiecutters maintained separately from the pyramid core, like we did with template stuff.

[digitalresistor]

Questions have come up if we want to add alembic migrations to the scaffold. I'd vote for yes, but I am biased in that I have 4 different projects, and I have implemented migrations 4 different ways, having one way that is standardised would be nice.

[stevepiercy]

What am I doing wrong in my git workflow? I want the commits in yonder PR #2103 to show up in this here PR #2014.

Here's what I did:

1. Checked out the branch Pylons/pyramid/feature/alchemy-scaffold-update
2. Made changes, committed, pushed to my fork of the repo
3. Compared: feature/alchemy-scaffold-update...stevepiercy:feature/alchemy-scaffold-update
4. Made a PR off the comparison

Instead of step 2, should I have pushed to Pylons/pyramid/feature/alchemy-scaffold-update?

[digitalresistor]

@stevepiercy You need to click the merge pull request button on #2103 and it will show up here. Just did that. Looking forward to seeing these changes :-)

[mmerickel]

@stevepiercy I'm not worried about issues with deprecation warnings introduced in py35 right now. It's better that the tutorial works on py27 and I'd like to avoid hacks in the code to work on both without warnings since our templates don't allow conditional rendering right now. Short answer - don't worry about it.

[stevepiercy]

@mmerickel please review #2385 for the feature to redirect to edit page when user attempts to add page that already exists.

[ztane]

cgi.escape was deprecated in Python 3.2, for the reason that it does not escape quotes by default. Since jinja2 is used there, the code could as well teach better habits and use for example markupsafe.escape()

[mmerickel]

@ztane Sure, my point was that I don't want the code forked on py2 vs py3. If there is a library available to do the escaping on both without warnings then fine. If you or anyone else wants to make that change then be sure to add markupsafe as a dependency in setup.py next to docutils and the text explaining why.

[mmerickel]

Awesome folks. Any further changes such as markupsafe should be made as PRs to master! Thanks for the work everyone put into this since Pycon 2014.

[pauleveritt]

Wow, merged to master. Mega kudos to @mmerickel and also @stevepiercy for keeping an eye on all the ramifications.

[digitalresistor]

Thank you @mmerickel and @stevepiercy!

[reedobrien]

applause