.. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. % Copyright 2001 by Object Craft P/L, Melbourne, Australia. .. % LICENCE - see LICENCE file distributed with this software for details. .. %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% .. _changes: ****************** Summary of Changes ****************** This chapter describes the changes made to Albatross between releases. .. _rel-1.42: Release 1.42. ============= This section describes the changes made to Albatross since release 1.40. Incompatibilities ----------------- * As of version 1.42, Albatross **no longer supports Python 2.3** - version 2.4 or up is required (Python 3 is not supported at this time). * `Application.handle_exception(ctx, req)` no longer escapes the python and template tracebacks before executing any application-supplied trackback template. As this change could result in a potential security problem, the application-supplied exception template has been renamed from `traceback.html` to `uncaught_exception.html`. If you used this functionality, you **must remove "noescape" from your `traceback.html` template** before renaming it to `uncaught_exception.html`. * `SessionExpired` handling was made consistent across session models and `SessionExpired` is now caught by the `Application.run()` method. When `run()` catches a `SessionExpired` exception, it calls `Application.handle_session_expired()`. This method attempts to display an application-supplied `session_expired.html` template before falling back to an internal "Your session has expired" message. * The `noescape` attribute (which disables the escaping of special HTML characters) is now only honoured for tag content, not tag attributes. Formerly, `noescape` on a tag would turn off escaping of all attributes and tag content. On reflection, this is too broad to be used safely. The `noescape` attribute will now raise an exception if used on any tag other than ``, ``, `` or ``, and only applies to the tag content. The new `htmlsafe()` mechanism provides an alternative way to disable escaping of evaluated attributes (see :ref:`tag-escaping`). * The session daemon ``al-session-daemon`` and the stand-alone development server ``al-httpd`` are now part of the Albatross command line tool. Usage remains largely the same, but rather than invoking ``al-session-daemon start``, use ``albatross session-server start``, and rather than ``al-httpd module.app 8080``, use ``albatross serve --port=8080 module.app``. You can also symlink the ``albatross`` script to ``al-session-daemon`` and ``al-httpd``. For more information on the session server, see :ref:`app-ses-daemon`, and for more information on the stand-alone development server, see :ref:`app-deploypyhttpd`. New Features ------------ * **Template evaluation namespaces** Evaluation of expressions in templates normally takes place within the scope of ``ctx.locals``. The new ```` tag allows you to switch temporarily to a subordinate namespace. Expression evaluation will take place with respect to that namespace, and input names will automatically be prefixed with the name of the namespace. For example: .. code-block:: python class Field: prompt = 'Enter age' data = 23 field = Field() And .. code-block:: albatross : Would produce: .. code-block:: html Enter age: A ``namespace="..."`` attribute has also been added to the ```` and ```` tags allowing you to execute their contained content in the specified namespace. * **Easier selection of Application and Context classes** A new ``get_app_classes(page_model, context_model)`` function has been added that makes choosing Application and Context classes easier. Previously, you had to choose between one of twelve Application classes and match this with an appropriate Context class. With the ``get_app_classes()`` function, you just need to choose a page model and a session model, and the appropriate Application and Context classes are returned. For more information, see :ref:`pack-overview`. * **Albatross command line and quick-start application skeleton** An **albatross** command line utility has been added. This utility currently has four sub-commands: * **create** - creates the basic framework of an application. * **add-page** - adds a page to an application so created. * **serve** - starts a stand-alone development server for the specified application. * **session-server** - starts a session server (see :ref:`app-ses-daemon` for more information). This makes it very easy to get started writing Albatross applications: .. code-block:: sh $ albatross create myapp $ cd myapp $ ls app.ini app.py pages session static $ ls pages environment.html macros.html new_session.py session_expired.html environment.py main.html page_not_found.html uncaught_exception.html __init__.py main.py raise_exception.py unhandled_exception.html 1$ ls static alxform.css favicon.ico logo.png style.css $ albatross serve Starting web server for "myapp" on port 8000 Stop the server with Ctrl-C http://localhost:8000/ Enhancements ------------ * A new alternative to the noescape attribute has been implemented that allows a data source to signal that a given string does not require escaping when it is rendered by template execution by casting it to the `htmlsafe()` type. This moves the responsibility for this potentially risky action from the template closer to the code that generated the string. The `htmlsafe()` type can also be used to selectively disable the escaping of evaluated attributes. While the "noescape" attribute still works, it's scope has been reduced, and it should be considered deprecated. * RandomModular applications will now attempt to render an application-supplied `page_not_found.html` template, before falling back to an internal *"URL .. was not found on this server"* message. * A simple logging mechanism has been added. Calling the `Application.set_logger(logger)` method with a logger compatible with the standard python logging module registers that logger with the application. Exceptions will be logged to the logger at "error" level, and a `ctx.log(msg)` method allows messages to be logged at "info" level. Bug Fixes --------- * If an application supplied it's own traceback.html template, the HTML headers would be emitted twice. **Also see the important note above regarding escaping of the tracebacks and renaming the template.** * `PageModuleMixin.load_page_module()` now raises a new `PageNotFound` exception (a subclass of `ApplicationError`) if the page module is not found. This addresses a bug where the `RandomPageModuleMixin` would not reliably handle an unknown page. * The standard exception handling bypasses the context logic, writing directly to the Request object. This created an issue with the session cookie not being cleared when an exception occurred. The exception handler now explicitly adds a "Set-Cookie:" header to clear the application cookie. .. _rel-1.40: Release 1.40. ============= This section describes the changes made to Albatross since release 1.36. Major Changes ------------- * **Conversion of documentation to reStructuredText** With the Python documentation moving from LaTeX markup to `reStructuredText `_ and the `Sphinx documentation generator `_, we could no longer rely on the documentation utilities released with Python. The Albatross documentation has been converted to ReST, and uses Sphinx to render this to HTML and PDF formats. * **Albatross Forms** A simple HTML form generation and validation framework has been added to Albatross (as an optional extension under the module name :mod:`albatross.ext.form`). Bug Fixes --------- * Redirects were not calling :meth:`req.return_code()` - for FastCGI deployment, this meant the request would hang [11164]. * The python built-in :func:`__import__` gained extra arguments with python 2.6 - the decode session import hook has been changed to pass all arguments (positional and keyword) [14823]. * When rendering tags to HTML, the handling of the noescape attribute was not consistently honoured. Attribute rendering has been moved to the common Tag base class as the :meth:`write_attrib()` method [15398]. * Relaxed tag recognition regular expressions, so that malformed tag attributes with no value, such as ````, are still recognised as valid Albatross tags, albeit with a null name attribute (which subsequently generates an error) [15398]. Miscellaneous Changes --------------------- * Miscellaneous changes to RedHat, Ubuntu, Solaris and OS X packaging rules. * Reorganised the unit tests to eliminate the use of explicitly assembled test suites, relying instead on the ``unittest`` module to collect methods of TestCase subclasses. The documentation example tests were also reimplemented as TestCase subclasses, allowing them to be run via common test driver. .. _rel-1.36: Release 1.36 ============ This section describes the changes in release 1.36 of Albatross that were made since release 1.35. .. _rel-1.36-new: New Features ------------ .. _rel-1.36-alforvar: New attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A ``vars`` attribute has been added to - this inserts the iterator value into the local namespace. The iterator value was previously only accessible via the iterator ``value()`` method. .. _rel-1.36-alforiter: now accepts iterators ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ now loops over sequences using the iterator protocol by default. The previous behaviour of indexing the sequence is retained where pagination or columns are requested. .. _rel-1.36-alsetdefault: Default arguments for macros using ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ New tag which allows macros to define default values for their arguments (suggested by Greg Bond). .. _rel-1.36-alexpandargs: argument shorthand ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Macro expansion can now use attributes on the tag to specify macro arguments (suggested by Greg Bond). .. _rel-1.36-envvars: Access to HTTP environment variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Added get_param() method to Request classes, which deployment method agnostic access to http "environment" variables. .. _rel-1.36-func: Functional Changes ------------------ .. _rel-1.36-reqmerge: Safer request merging ^^^^^^^^^^^^^^^^^^^^^ :class:`NameRecorderMixin` no longer falls back to merging all request fields if no ``__albform__`` field is present. Applications using the :class:`NameRecorderMixin` and GET-style requests will need to explicitly merge relevent fields with the ``ctx.merge_vars(...)`` method. .. _rel-1.36-sha1: Switch from MD5 to SHA1 ^^^^^^^^^^^^^^^^^^^^^^^ Pickles embedded in hidden fields are now signed using the HMAC-SHA1 algorithm (was MD5). .. _rel-1.36-fastcg: New FastCGI driver now default ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The experimental FastCGI driver included in version 1.35 now becomes the default FastCGI driver. The old driver has been renamed fcgiappold. The new driver implements the FastCGI protocol itself, rather than depending on an external module. .. _rel-1.36-bug: Bug Fixes --------- .. _rel-1.36-aloption: fixes ^^^^^^^^^^^^^^^^^ If the tag was not immediately enclosed within an tag, it would be silently ignored. now works within containing flow control tags such as or , has improved error reporting, and supports attributes for dynamically setting value and label. .. _rel-1.36-sessclient: Session server client code enhancements ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Communication with the session server has been made more robust. EINTR is handled, as are partial reads and writes, and requests are restarted if the socket closes. .. _rel-1.36-fixinputrec: Fix to input type recording ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Mixing radio inputs with other inputs of the same name did not raise an exception (reported by Michael Neel). .. _rel-1.36-fastcgifix: Fixed incorrect constant in FastCGI driver ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ FCGI_MAX_DATA was incorrect due to an operator precedence mistake. Found by Tom Limoncelli. .. _rel-1.36-misc: Miscellaneous Changes --------------------- .. _rel-1.36-oldpython: Clean up pre-python 2.2 constructs ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Cleaned up and replaced many pre-python 2.2 constructs. .. _rel-1.36-unittests: New and updated unit tests ^^^^^^^^^^^^^^^^^^^^^^^^^^ Many new tests have been added, and existing tests restructured. .. _rel-1.35: Release 1.35 ============ This section describes the changes in release 1.35 of Albatross that were made since release 1.34. Note that release 1.34 was an internal release. .. _rel-1.35-new: New Features ------------ .. _rel-1.35-fcgiappnew: New FastCGI module ^^^^^^^^^^^^^^^^^^ A drop-in replacement for the ``fcgiapp`` module, called ``fcgiappnew`` has been added. This version implements the FastCGI protocol itself, rather than relying on an external module to implement the protocol (we have not been able to clarify the license of the fcgi.py module). This new module addresses several minor problems with fcgi.py, and should be faster, although it should not be used in critical applications until it has received wider testing. This module will eventually be renamed to replace fcgiapp (at which point, the fcgiappnew name will dropped). .. _rel-1.35-func: Functional Changes ------------------ .. _rel-1.35-check-ext-tag: Validate extension tag names ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When extension tags (alx-\*) are registered, their name is now checked against the template parsing regexp to ensure they can subsequently be matched. .. _rel-1.35-bug: Bug Fixes --------- .. _rel-1.35-empty-anytag: Enhance AnyTag with knowledge of empty HTML tags ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The AnyTag functionality was given knowledge of HTML tags for which the close tag is forbidden, so it can avoid generating XHTML empty tag (which could cause the page to fail HTML validation). .. _rel-1.35-disabledbool: Input tags with disabledbool attribute ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When the disabledbool attribute was used on input tags, the disabled state was not being passed through to the input registry within the :class:`NameRecorderMixin`. .. _rel-1.35-sess-srv-abort: Improve session server handling of aborted connections ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a client closed it's connection to the session server while the server had data pending for the client, a subsequent del_write_file would generate an exception, killing the session server. .. _rel-1.33: Release 1.33 ============ This section describes the changes in release 1.33 of Albatross that were made since release 1.32. .. _rel-1.33-bug: Bug Fixes --------- .. _rel-1.33-set-value: ctx.set_value() ^^^^^^^^^^^^^^^ Fixed handling of tree iterator backdoor and improved error reporting. .. _rel-1.32: Release 1.32 ============ This section describes the changes in release 1.32 of Albatross that were made since release 1.31. .. _rel-1.32-bug: Bug Fixes --------- .. _rel-1.32-bug-frame: _caller_globals() ^^^^^^^^^^^^^^^^^ To obtain a reference to the current frame, _caller_globals was raising and catching an exception, then extracting the tb_frame member of sys.exc_traceback. sys.exc_traceback was deprecated in python 1.5 as it is not thread-safe. It now appears to be unreliable in 2.4, so _caller_globals has been changed to use sys._getframe(). .. _rel-1.32-start-page: ctx.set_page() from start page ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If ctx.set_page() was called from within the start page, then the wrong page methods (page_enter, page_display, etc) would be called (those of the initial page, rather than the page requested via set_page). .. _rel-1.31: Release 1.31 ============ This section describes the changes in release 1.31 of Albatross that were made since release 1.30. .. _rel-1.31-bug: Bug Fixes --------- .. _rel-1.31-randompage: RandomPage error handling ^^^^^^^^^^^^^^^^^^^^^^^^^ Fixes to handling of missing RandomPage page modules. .. _rel-1.30: Release 1.30 ============ This section describes the changes in release 1.30 of Albatross that were made since release 1.20. .. _rel-1.30-func: Functional Changes ------------------ .. _rel-1.30-anytag: Evaluate any attribute of any tag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Arbitrary HTML tags can now access the templating engine by prefixing the tag with "al-". Attributes of the tag can then be selectively evaluated to derive their value. Appending "expr" to the attribute name causes the result of evaluating the expression to be substituted for the value of the attribute. Appending "bool" results in the attribute value being evaluated in a boolean context, and if true, a boolean HTML attribute is emitted. For example: .. code-block:: albatross could produce .. code-block:: html and: .. code-block:: albatross could produce .. code-block:: html .. _rel-1.30-checkdefs: Enforce only one definition of macros and lookups ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Since macros and lookups are an application global resource, they can only be defined once per application, however this was not previously enforced. Redefinition of macros or lookups will now result in an ApplicationError exception. .. _rel-1.30-inlinelookup: In-line expansion of ```` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The ```` tag can now be optionally expanded in place. If the tag has an expr= attribute, this will be evaluated and used as the value to look up, and the results of the lookup substituted for the tag. Functionality of named lookups remains unchanged. .. _rel-1.30-require: New ```` tag ^^^^^^^^^^^^^^^^^^^^^^^^ A new tag has been added to allow templates to assert that specific Albatross features are available, or templating scheme version number is high enough. For instance, the addition of the "Any Tag" functionality has resulting in the templating version incrementing from 1 to 2. .. _rel-1.30-cachecontrol: Set Cache-Control header ^^^^^^^^^^^^^^^^^^^^^^^^ ``Cache-Control: no-cache`` is now set in addition to ``Pragma: no-cache``. ``Cache-Control`` was introduced in HTTP/1.1, prior to this the same effect was achieved with ``Pragma``. Some browsers change their behaviour depending on whether the page was delivered via HTTP/1.1 or HTTP/1.0. .. _rel-1.30-simplecookie: Simplified Session Cookie handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Session cookie handling has been simplified. .. _rel-1.30-bug: Bug Fixes --------- .. _rel-1.30-fcgifinalise: FastCGI finalisation ^^^^^^^^^^^^^^^^^^^^ FastCGI apps were not being explicitly finalised, relying instead on their object destructor, with the result that writing application output (or errors) would be indefinitely deferred if object cycles existed. We now call ``fcgi.Finish()`` from the fcgiapp ``Request.return_code()`` method. .. _rel-1.30-tbcycle: Delete traceback objects ^^^^^^^^^^^^^^^^^^^^^^^^ When handling exceptions, the traceback is now explicitly deleted from the local namespace to prevent cycles (otherwise the garbage collection of other objects in the local namespace will be delayed). .. _rel-1.30-alselect: ```` fixes ^^^^^^^^^^^^^^^^^^^^^ Two fixes to the ```` tag: the albatross-specific "list" attribute was leaking into resulting markup, and the use of the "expr" attribute would result in invalid markup being emitted. .. _rel-1.30-hiddeninput: Illegal placement of ```` tag ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Thanks to Robert Fendt for picking this up: the Albatross-generated hidden field input element must not appear naked inside a form element for strict HTML conformance. The solution is to wrap the input elements in div. .. _rel-1.30-branchsessdel: Allow BranchingSessions to be deleted ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ BranchingSession sessions could not be "deleted" because each interaction is a separate session. The solution implemented is to add a dummy "session" shared by all branches, which is deleted when one branch "logs out". .. _rel-1.20: Release 1.20 ============ This section describes the changes in release 1.20 of Albatross that were made since release 1.11. .. _rel-1.20-func: Functional Changes ------------------ .. _rel-1.20-branchingsession: New ``BranchingSessionContext`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A persistent problem with server-side sessions is the browser state getting out of synchronisation with the application state. This occurs when the user reloads the page or uses the "back" button. A new ``BranchingSessionContext`` application context class has been added that attempts to work around this problem by creating a new server-side session for every interaction with the browser. The unique session identifier is stored in a hidden form field, rather than a cookie. The new Context class is intended to be used with the server-side Application classes, and provides a similar experience to storing the context in a hidden form field, without the overhead and security issues of sending the context on a round-trip through the user's browser. No effort is made at this time to control the resources used by these server- side sessions, other than expiring them after ``session_age`` seconds. .. _rel-1.20-refactorrequest: Improved Request classes ^^^^^^^^^^^^^^^^^^^^^^^^ The Request classes provide the interface between specific application deployment models (CGI, FastCGI, mod_python, etc), and the Albatross application. These classes have been refactored to extract common functionality into a new RequestBase class. The Request classes also now have methods for passing status back to browser. .. _rel-1.20-pagemodule: Page Module loading ^^^^^^^^^^^^^^^^^^^ The page module loader in PageModuleMixin has been reimplemented so that it does not pollute ``sys.modules``. Page modules are now loaded into a synthetic module's namespace, rather than the global module namespace. This will break code that defined classes in page modules and placed instances of those classes into the session. .. _rel-1.20-responsemultiheader: Multi-instance response headers now supported ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Some HTTP headers can appear multiple times (for example Set-Cookie) - the response handling has been modified to allow multiple instances of a header. ``ResponseMixin.get_header()`` now returns a list of strings, rather than just a string. The httpdapp module has also been updated to allow multiple instances of a header, keeping headers in a list rather than a dictionary. .. _rel-1.20-reqequalsimgmap: simpler ``req_equals()`` matching with image maps ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ``ctx.req_equals(name)`` now checks for ``name.x`` if ``name`` is not found. This makes using image maps as buttons easier (from Michael C. Neel). .. _rel-1.20-bug: Bug Fixes --------- .. _rel-1.20-fixredirecturl: ``redirect_url()`` fixes ^^^^^^^^^^^^^^^^^^^^^^^^ Under some circumstances, ``redirect_url()`` would redirect to incorrect or invalid URLs (for example, an https app would redirect to http) - the URI parsing has been refactored, and this bug has been fixed. Tests were also added for the refactored URI parsing. .. _rel-1.20-requeststatus: Improved request status handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ #. Symbolic names are now defined for the RFC1945 status header values, such as HTTP_OK, HTTP_MOVED_PERMANENTLY, HTTP_MOVED_TEMPORARILY and HTTP_INTERNAL_SERVER_ERROR #. The Request classes (deployment model adaptors) and Application ``run()`` method have been updated to correctly pass the returned status back to the client. .. _rel-1.20-responseheadercase: Response header matching now case-insensitive ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Response header names were being matched in a case-sensitive way - this was incorrect and has been fixed. .. _rel-1.20-cookiefixes: Cookie handling fixes ^^^^^^^^^^^^^^^^^^^^^ #. A Cookie path bug was noticed when Albatross applications were used with the Safari browser. ``absolute_base_url()`` was generating a trailing slash on the returned application URL (so /path/app.cgi/ instead of /path/app.cgi). This was causing problems for requests like /path/app.cgi?blah in that Safari did not send the cookie (probably correctly). #. When an application was accessed via https, the ``secure`` attribute on any resulting cookies was not being set. This attribute marks the cookie to be only returned via an https connection. The ``secure`` attribute is now set. #. Cookie max-age was being allowed to default - this is now explicitly set to match the configured session age (from the Application ``session_age`` parameter). .. _rel-1.11: Release 1.11 ============ This section describes the changes in release 1.11 of Albatross that were made since release 1.10. .. _rel-1.11-func: Functional Changes ------------------ .. _rel-1.11-alselectconsistency: ``/`` consistency ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ```` handling of ``name``, ``expr``, ``valueexpr`` and ``value`` attributes has been made consistent with that of ````. .. _rel-1.11-absbaseurl: ``absolute_base_url`` method ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ New method :meth:`absolute_base_url` has been added to the :class:`AppContext`. .. _rel-1.11-httpd: ``al-httpd`` enhancements ^^^^^^^^^^^^^^^^^^^^^^^^^ Matt Goodall has continued to improve the capabilities of the ``al-httpd`` program and :mod:`httpdapp.py` so that it is now possible to run all of the CGI based sample applications. You can now initialise the ``static_resources`` from the command line. For example, the tree samples can be executed to serve up their images like this: .. code-block:: sh $ cd samples/tree2 $ al-httpd tree.app 8080 /alsamp/images ../images/ .. _rel-1.11-xhtml: XHTML fixes ^^^^^^^^^^^ The ```` and ```` tags now output XHTML compliant end tags. .. _rel-1.11-bug: Bug Fixes --------- .. _rel-1.11-modpython: ``mod_python`` support ^^^^^^^^^^^^^^^^^^^^^^ Greg Bond fixed a :mod:`cgiapp` field handling incompatibility with ``mod_python`` 3. .. _rel-1.11-servername: ``get_servername()`` support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :meth:`get_servername` method of the :mod:`cgiapp` and :mod:`fcgiapp` :class:`Request` classes now use the ``HTTP_HOST`` environment variable rather than ``SERVER_NAME``. .. _rel-1.11-cookie: Multiple cookies ^^^^^^^^^^^^^^^^ All session cookies now include a path attribute. This prevents multiple redundant cookies being set for all URI paths in an application. .. _rel-1.10: Release 1.10 ============ This section describes the changes in release 1.10 of Albatross that were made since release 1.01. .. _rel-1.10-func: Functional Changes ------------------ .. _rel-1.10-fastcgi: FastCGI support ^^^^^^^^^^^^^^^ Matt Goodall developed support for deployment of applications via FastCGI. FastCGI applications import their :class:`Request` class from :mod:`albatross.fcgiapp`. .. _rel-1.10-standalone: Standalone BaseHTTPServer support ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Matt Goodall developed support for standalone deployment of applications via the standard Python :mod:`BaseHTTPServer` module. The ``al-httpd`` program can be used to deploy a CGI application as a standalone :mod:`BaseHTTPServer` server. .. _rel-1.10-exc: Exception Classes ^^^^^^^^^^^^^^^^^ All Albatross exceptions have been redefined to indicate the source of the error; user (:exc:`UserError`), programmer (:exc:`ApplicationError`), or Albatross itself (:exc:`InternalError`). The :exc:`ServerError` exception reports problems related to the session server, :exc:`SecurityError` reports either a programmer error, or a user attempt to access restricted values in the execution context, and :exc:`TemplateLoadError` reports failures to load templates. All of the exceptions inherit from :exc:`AlbatrossError`. The :mod:`albatross.common` module defines the exceptions. .. _rel-1.10-headers: Response Header Management ^^^^^^^^^^^^^^^^^^^^^^^^^^ All response header management has been moved to the :class:`ResponseMixin` class. The :class:`AppContext` class now inherits from :class:`ResponseMixin`. The :class:`Request` class no longer tracks whether or not headers have been sent. :class:`ResponseMixin` provides the ability to set, get, delete, and send headers. Headers are automatically sent when the application sends any content to the browser. The :meth:`write_headers` method has been deleted from the following classes; :class:`SimpleAppContext`, :class:`SessionAppContext`, :class:`SessionServerContextMixin`, :class:`SessionFileContextMixin`, :class:`SessionFileAppContext`. For :class:`SessionServerContextMixin` and :class:`SessionFileContextMixin` the ``Set-Cookie`` header is set when session is created or loaded. .. _rel-1.10-response: HTTP Response Codes ^^^^^^^^^^^^^^^^^^^ The :meth:`Application.run` method no longer unconditionally returns an HTTP response code of ``200``. The returned response code is retrieved from the :class:`Request.status()` method. You can call the :meth:`Request.set_status` method to override the default HTTP response code of ``200``. .. _rel-1.10-upload: File Uploading ^^^^^^^^^^^^^^ The ```` tag now supports ``type="file"`` input tags. When you use file input tags the enclosing ```` tag automatically adds the ``enctype="multipart/form-data"`` attribute to the generated ``
`` tag. The :mod:`albatross.cgiapp` and :mod:`albatross.apacheapp` modules define a :class:`FileField` class which provides access to uploaded files. During request merging the :meth:`Request.field_file` method returns instances of :class:`FileField` for uploaded files. .. _rel-1.10-session: Session Changes ^^^^^^^^^^^^^^^ The :meth:`Application.run` method now saves the session before flushing the response to the browser. This allows applications to support dynamically generated images. The :meth:`SessionBase.add_session_vars` method now raises an :exc:`ApplicationError` exception if you attempt to add variables to the session which do not exist in the local namespace. The :meth:`SessionBase.default_session_var` method allows you to add a variable to the session and place it in the local namespace at the same time. Session saving previously silently removed session values which could not be pickled. Now unpickleable values are reported via an :exc:`ApplicationError` exception. Errors handling and reporting during session loading has been improved. .. _rel-1.10-excfmt: Exception Formatting and Handling ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The exception formatting in :meth:`Application.handle_exception` has been moved into the :meth:`format_exception` method. Applications can perform their own exception formatting and/or send formatted exceptions to locations other than the browser. .. _rel-1.10-unicode: Unicode ^^^^^^^ The :meth:`ExecuteMixin.write_content` method now converts unicode to UTF-8. .. _rel-1.10-ctx: Execution Context Available to Template Expressions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ During :meth:`NamespaceMixin.eval_expr` the execution context is temporary placed into the local namespace as the variable *__ctx__*. .. _rel-1.10-merging: Request Merging ^^^^^^^^^^^^^^^ :meth:`NamespaceMixin.set_value` ignores attempts to set Albatross iterators that are not present in the namespace. :meth:`NamespaceMixin.set_value` produces a nice syntax error like report when an illegal field name is used. .. _rel-1.10-globals: Locating Globals for Template Expressions ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The :func:`_caller_globals` function has been changed to use the name of a function rather a stack frame count. This is used by the methods :meth:`AppContext.run_template`, :meth:`AppContext.run_template_once`, :meth:`RandomPageModuleMixin.display_response`, and :meth:`SimpleContext.__init__` to locate the module whose globals will be used as the global namespace for evaluating template expressions. .. _rel-1.10-tree: Tree Handling ^^^^^^^^^^^^^ The ```` tag now has a ``single`` attribute which enables the single select mode. In single select mode, selecting a node automatically deselects any previously selected node. The ```` tag now supports the ``treefold="expr"``, ``treeselect="expr"``, and ``treeellipsis="expr"`` attributes. The expression specifies a tree node that is used to construct a tree iterator input value. The following methods have been added to the :class:`LazyTreeIterator` class; :meth:`load_children`, :meth:`is_selected`, :meth:`select_alias`, :meth:`open_alias`. .. _rel-1.10-lookup: Lookup Evaluation ^^^^^^^^^^^^^^^^^ The ```` tag now registers the lookup during template parsing rather than during evaluation. This allows template code to make use of lookups that are defined later in the same file. The item dictionary is created the first time that the lookup is used rather than when the template is interpreted. .. _rel-1.10-macro: Macro Argument Evaluation ^^^^^^^^^^^^^^^^^^^^^^^^^ Macro arguments are now evaluated when they are referenced rather than before they are passed to a macro. This removes a limitation where you could not define macros including ```` tags that retrieved ```` tags from their arguments. Previously the ```` tags passed as macro arguments would have been evaluated outside of the context of the form defined in the macro. This effectively made the input tags invisible to the form recorder. .. _rel-1.10-select: ``