.. _migrate: Migrating from WebHelpers %%%%%%%%%%%%%%%%%%%%%%%%% This chapter explains how to migrate an application from WebHelpers to WebHelpers2. All helpers were reviewed and several were renamed or moved to organize them better, or changed their arguments to be more useful long term. WebHelpers2 focuses on the HTML generator and tag library, text processing, value formatting, container objects, and statistics. Other large subsystems were deleted if they're available separately on PyPI or were difficult to maintain. Also deleted were helpers that were little-used or no longer needed in Python 2.6+, or depended on the obsolete Pylons framework. New features are not mentioned here. Please read the rest of the documentation for them. Global changes ============== The top-level package was renamed to ``webhelpers2``, so you'll have to change your imports. (The reason it was renamed was to avoid breaking older applications that are still using the WebHelpers API but were not pinned to a specific version of it.) The test suite has been changed to PyTest. All doctests have been converted to unit tests. The remaining code examples in the documentation are solely for documentation. webhelpers.constants ==================== No changes. webhelpers.containers ===================== Renamed helpers: * del_quiet() -> ``del_keys()`` * except_keys() -> ``copy_keys_except()`` * extract_keys() -> ``split_dict()`` * only_some_keys() -> ``copy_keys()`` In all these helpers the ``keys`` argument changed to ``\*keys``, so pass the keys as positional arguments rather than in an iterable. Deleted 'get_many()'. It was little used. Deleted 'Accumulator'. Use ``collections.defaultdict(list)`` in the standard library or WebOb's 'MultiDict'. Deleted 'UniqueAccumulator'. Use ``collections.defaultdict(set)`` in the standard library. webhelpers.date =============== No changes. webhelpers.feedgenerator ======================== Deleted. PyPI has a feedgenerator_ distribution that is a more basic port of the Django original, and a feedgen_ distribution that's more modular. Neither of them support GeoRSS as the WebHelpers module did. (This module was dropped because it was significant work to periodically merge updates from the Django original, and the WebHelpers maintainers were not newsfeed experts and couldn't really evaluate the patches.) You can also generate newsfeeds with a simple template; XXX TODO here are Mako functions for that generate Atom and RSS with GeoRSS. webhelpers.html =============== No changes at the package level, except for imports from the ``builder`` module that have changed. builder ------- ``HTML.literal`` is now the ``literal`` class rather than a wrapper method. As a consequence it no longer accepts multiple positional args. Use ``HTML(..., lit=True)`` instead. The 'make_tag()' function was merged into ``HTML.tag()``. 'format_attrs' was split into ``HTML.optimize_attrs()`` and ``HTML.render_attrs()``. The 'empty_attrs' global was replaced by ``HTML.void_attrs``. All tag-generating helpers now convert underscores to hyphens in attribute names. This is to support HTML5 "data-" attributes as keyword args. Trailing underscores are still removed ("class\_" -> "class"). This was implemented at the lowest level, so both ``HTML.tag()`` and all the high-level helpers in the 'tags' module have this feature. The code for boolean HTML attributes was rewritten and new boolean attributes defined; see the :doc:`builder ` page for details. converters ---------- Deleted. Moved and renamed the following helpers: * format_paragraphs() -> ``webhelpers2.html.tools.text_to_html()`` * render() -> ``webhelpers2.html.tools.html_to_text()`` grid ---- Deleted the **html.grid** and **html.grid_demo** modules. These were third-party modules that were ill-advisedly included in WebHelpers. The author Marcin Lulek (Ergo^) has released then on PyPI as webhelpers2_grid_. Deleted the sample CSS stylesheet. tags ---- The **select** helpers were overhauled in 2.0rc2 and again in 2.0rc3: * The ``options`` argument to ``select()`` and ``ModelTags.select()`` is more restrictive. If you previously passed a list of value-label pairs, or embedded lists representing groups, or other complex data structures, you'll have to build up ``Options`` instance instead and pass it. This was changed in 2.0rc3. * ``Options.render()`` is a new feature. It renders the options without an enclosing select. This can be used to manually place options into an HTML