librelist archives

Re: [flask] Flask 0.7 in Soft Feature Freeze

From:

Daniele Nicolodi

Date:

2011-06-18 @ 13:05

On 18/06/11 02:05, Armin Ronacher wrote:
> The blueprint branch in the Flask repository is now in soft feature
> freeze.  By that we mean that we don't expect to add any more features
> or change behavior unless something absolutely needs to be changed.

I have an application using a few modules, and I'm giving this branch a
try right now. One of the things I like is the reversal of the meaning
of '.index' vs 'index' in url_for(), the new one is much more intuitive
to me.

> Because 0.7 will bring some changes to backwards compatibility we
> introduced a script in the 'scripts' folder that can generate a diff
> with the necessary changes.
> 
> If you have an application currently in use that uses the 'flask.Module'
> object we could love you to checkout the blueprints branch and check if
> the script properly upgrades the application to blueprints for you.

I have tried this script on my application and it mostly works, but it
handles url_for() changed semantics sub optimally, IMHO. If I'm in a
module declared like this::

  Module(__name__, 'admin.users')

becoming (I like this change too!)::

  Blueprint('admin.users', __name__)

I would expect lines like::

  return redirect(url_for('manage.users.index'))

to become::

  return redirect(url_for('.index'))

while the scripts turns them into::

  return redirect(url_for(.manage.users.index'))

which (I think, I haven't tried) is not going to work. If you agree I
may find time to look into providing patch for this.

> If you run "make html" from the docs folder it will generate the current
> documentation which also has a chapter of how the upgrades are supposed
> to work.

Sphinx rocks! :-)  I haven't understood yet how to obtain Flask sphinx
templates, but that is definitely a minor annoyance.

> The only thing the script will not be able to detect are the new
> mechanics for templates.  If a blueprint now has a template folder you
> have to explicitly add a 'templates="templates"' to the constructor
> *and* move the templates from blueprint/templates to
> blueprint/templates/blueprint (eg: inside the template folder you have
> to repeat the blueprint name).

In my application Flask related code is organized like this:

application/
  __index__.py  # application object construction,
                # configuration, modules registration,
  views/
    foo.py      # module operating on foo objects
    bar.py      # module operating on bar objects
  static/
    style.css
    jquery.js
  templates/
    foo/        # templates for foo module/objects
      view.html
      edit.html
    bar/        # templates for bar module/objects
      view.html
      edit.html

Is this sub-optimal? There is a consolidated best practice for
organizing code and templates differently?

> We know the documentation right now is lacking, but we will work on
> that.  The estimated release is the end of next week together with a new
> version of Werkzeug as well.

I had a quick look at the documentation and indeed the new blueprint
system documentation is not yet as nice as documentation for other areas
of Flask. This makes it difficult to evaluate the improvements.

For example, from the description of the new Blueprints system, I infer
that it would be possible to register before and after request handlers,
or other app level handlers, on the blueprint themselves, but I haven't
found this mentioned anywhere. Is my impression wrong or is the
documentation still incomplete?

I would much appreciate a more detailed changelog, better highlighting
changes in best practices, for example.

Thank you for your nice work!

Cheers,
-- 
Daniele

On Sat, Jun 18, 2011 at 9:05 AM, Daniele Nicolodi <daniele@grinta.net> wrote:
> On 18/06/11 02:05, Armin Ronacher wrote:
>> If you run "make html" from the docs folder it will generate the current
>> documentation which also has a chapter of how the upgrades are supposed
>> to work.
>
> Sphinx rocks! :-)  I haven't understood yet how to obtain Flask sphinx
> templates, but that is definitely a minor annoyance.

Here's how I build the Flask docs, from scratch, including themes.

    git clone git://github.com/mitsuhiko/flask.git
    cd flask
    mkvirtualenv flask
    python setup.py develop
    pip install sphinx
    git submodule update --init
    cd docs
    make html
    cd _build/html
    python -m SimpleHTTPServer

Then you have the docs on http://localhost:8000/.

You get the themes with `git submodule update --init`.

-Ron