Deprecate flask.ext and create migration tool to flask_*

[Daniel Neuhäuser]

[Markus Unterwaditzer]

A migration tool could be a simple lib2to3-based, but i am not sure if such a thing is necessary. This case seems to be an easy enough task for simple search-and-replace or regexes.

[Markus Unterwaditzer]

Some introductory information for new contributors:

• Flask used to have flaskext as a namespace for extensions, so they were importable as flaskext.foo. This didn't work well, so the new form flask_foo was introduced. flask.ext.foo is a compatibility layer that will try to import both variants. See http://flask.pocoo.org/docs/0.10/extensions/
• flask.ext.foo is hard to maintain, and since now all extensions have switched to the new package naming scheme, it is no longer worth it. We want to deprecate it for 1.0, so we need some sort of tool which can help users to rewrite all their old imports in their apps.
• One could write a Python script similar to this beast. This will get the job done, but as its docstring says, it's a terrible hack.
• lib2to3 proved useful for writing larger migration tools, but it's nontrivial to use it.
  • https://github.com/mitsuhiko/python-modernize/ is one based on it, and it seems to me that's the easiest project one could rip off from.
  • I wasn't able to find complete tutorials that are useful for this. Most seem to be focused on porting to Python 3, which would imply running the default 2to3 fixers on the user's codebase (which we definetly don't want)
  • One will have to read the sourcecode of 2to3 and lib2to3 to understand, i think. This is doable by entering libraryname hg.python.org into Google, where the libraryname is either 2to3 or lib2to3.
  • The current state for doing sourcecode manipulation in Python sucks, and i'd like to see a library which wraps lib2to3 and provides a more concise API.

[Keyan Pishdadian]

I'd like to try to tackle this. Just to get some clarification, the proposed migration tool would essentially search old sourcecode and replace instances of import flask.ext.foo with import flask_foo, am I understanding this correctly?

[Adrian]

Yes. It would have to cover these imports (unless I missed anything):

from flask.ext import foo
from flask.ext.foo import <anything>
import flask.ext.foo[.anything]

[Keyan Pishdadian]

And the aforementioned imports would be replaced with what?

[Adrian]

flask.ext.foo => flask_foo

[Markus Unterwaditzer]

Exactly what ThiefMaster said. Thanks for giving this a try!

And the aforementioned imports would be replaced with what?

• from flask.ext import foo => import flask_foo as foo
• from flask.ext.foo import bam => from flask_foo import bam
• import flask.ext.foo => We'd have to rewrite any reference to flask.ext.foo in the code further below. If that's too hard, just skip those and show a warning.

[David Lord]

If you can actually evaluate the import, you could try to figure out the actual package name, rather than guessing that it's flask_<name>. But that might be overkill over just printing "make sure we got it right" at the end.

[Markus Unterwaditzer]

True, but then you'd be dependent on whether the migration script is running in the correct virtualenv, and things like that. Also I don't think anybody actually uses flaskext extensions anymore.

[Hsiaoming Yang]

Let's correct every answer on http://stackoverflow.com/search?q=flask.ext, and encourage users to use flask_foo instead of flask.ext.foo.

There are many Flask extentions whose documentation contains from flask.ext.foo import bar. We should encourage the developers to change the documentation. For example: https://pythonhosted.org/Flask-Testing/

[Keyan Pishdadian]

@lepture that's certainly ambitious, I think it would be nice to resolve #1367 and #1366 before doing something like that. The current documentation still suggests using the .ext format. It will be easier to encourage a transition once the docs are fixed and use of the migration tool is fully supported and documented.

That said, I've fixed it a couple times when I happen to be using extensions and notice they had the old format in their examples.

[Hsiaoming Yang]

@keyanp in the meanwhile, we should notify Flask extention developers. Their documentations would also confuse users.

[Keyan Pishdadian]

@lepture sure, we can certainly try to let some developers know, alerting all extension developers is probably unrealistic.

[Hsiaoming Yang]

@keyanp that's what I am doing. I will do a search on these projects, find out who should be notified.

[Keyan Pishdadian]

Figured I would at least change pocoo documentation regarding it.

[Markus Unterwaditzer]

@lepture thanks for notifying extension authors!

[Jeff Widman]

#1484 made the deprecation explicit in the docs and added runtime warnings if you try to import flask.ext.*.

The migration script is here: https://github.com/pocoo/flask-ext-migrate
#1765 tracks making sure the migration script is linked from the docs.

For anyone coming here researching how to migrate their Flask project, the migration script is convenient but not a necessity. I've migrated multiple Flask projects to the new format using a simple find-and-replace for flask.ext. to flask_.

Closing.