[Subversion] / PEAK / CHANGES.txt  

View of /PEAK/CHANGES.txt

Parent Directory | Revision Log
Revision: 1847 - (download)
Mon Oct 11 19:36:04 2004 UTC (16 years, 3 months ago) by pje
File size: 16385 byte(s)
In order to support obtaining the line and column locations of problems in
XML files, we are now using Python 2.4's version of the 'pyexpat' module,
built as 'peak.util.pyexpat'.  Also, added "empty" option to negotiating
XML parser, so that tags which don't want any children can force an error
if a child element appears within them.
Fixes and Enhancements since Version 0.5 alpha 3

 - In order to support obtaining the line and column locations of problems in
   XML files, we are now using Python 2.4's version of the 'pyexpat' module,
   built as 'peak.util.pyexpat'.

 - There's a new class, 'config.IniLoader', that can be used to lazily load
   .ini files as configuration.  'IniLoader' instances have an 'iniFiles'
   attribute that lists the configuration sources (filenames/URLs/factories)
   to be used, and automatically load the .ini files as soon as you try to get
   any configuration data for them.  Previously, similar functionality was only
   available via 'config.makeRoot()'.

   Also, there's now an 'ini' reference type that instantiates an 'IniLoader'
   for one or more addresses.  You can use it like this::

     [Named Services]

     some.example = naming.Reference('ini',
         ['pkgfile:peak/peak.ini', '/etc/something.ini']

     another.example = naming.LinkRef(
   The two examples above will each load the same pair of specified .ini files.
   You can also directly instantiate an 'IniLoader', as in::

     cfg = config.IniLoader(self, iniFiles=['pkgfile:peak/peak.ini'])

   Attempting to look up any configuration properties via the 'cfg' object
   will cause it to load the specified .ini file.
 - 'config.fileNearModule()' is DEPRECATED, in favor of 'config.packageFile()'.
   The latter returns a 'naming.IStreamFactory', which is more suitable for
   working with e.g. module data files compressed in a zipfile.  Uses of
   'fileNearModule()' that were being passed to 'config.loadConfigFile()' can
   be safely changed to 'config.packageFile()' without needing any other code
   changes, but if you were directly using 'fileNearModule()' as a filename,
   you will need to rewrite appropriately.  

 - 'config.loadConfigFile()' and 'config.loadConfigFiles()' now accept URLs,
   'naming.IStreamFactory' objects, and 'config.IStreamSource' objects as well
   as filenames.  This was primarily added to support use of
   'config.packageFile()' or 'pkgfile:' URLs, in place of using

 - There is a new 'config.IStreamSource' protocol, to make it easy to accept
   URLs, filenames, or 'naming.IStreamFactory' objects as the source of a

   Its typical usage is just::

       factory = config.IStreamSource(data).getFactory(self)
       stream = factory.open('t')  # open for reading in text mode

   where 'data' is a string or a 'naming.IStreamFactory', and 'self' is a
   component to be used as lookup context.  The returned 'factory' is a
   'naming.IStreamFactory' that can then be '.open()'-ed for reading, or used
   in other ways as needed.

   Wherever practical, as we encounter them, we'll be changing PEAK API's that
   take filenames to also accept stream sources.

 - The 'naming.IStreamFactory' interface now has an 'address' attribute, which
   is the string form of the canonical URL of the target stream.  This was
   added to make it easier to e.g. report errors in a stream that's being
   parsed, since the parser only needs the factory in order to report the
   location of an error.  (Note: if you implement 'naming.IStreamFactory', be
   sure to add this attribute to your implementations.)

 - The 'peak.util.WSGIServer' module has been moved to the
   'wsgiref.simple_server' module.  The 'wsgiref' reference library for WSGI
   (aka PEP 333) is now distributed with PEAK.

 - Added a 'WSGI' command to the 'peak' script, to allow you to run "foreign"
   (i.e. non-PEAK) PEP 333 applications in PEAK's various servers and
   launchers.  Basically, by prefixing 'WSGI' before the import specifier, you
   can now run such foreign apps.

   For example::

       peak launch WSGI import:some_app.application

   will run 'some_app.application' in the local web browser, and::

       peak CGI WSGI import:some_app.application
   will run it under the CGI/FastCGI runner.  Similarly, you can use this in
   the "Command" spec for the "peak supervise" pre-forking FastCGI supervisor
 - There is a new 'running.IWSGIApplication' interface, for PEP 333-compliant
   "application" objects, and all of PEAK's provided applications now implement
   it instead of 'running.IRerunnableCGI'.  If you write your apps to the newer
   interface, they'll be portable to any PEP 333-compliant web server, not just
   the PEAK CGI, FastCGI, and "supervisor" containers.  There is a simple
   adapter that allows 'IWSGIApplication' objects to run in the CGI-based
   containers, but not the other way around, so using 'IRerunnableCGI' directly
   now limits your portability.  (For example, the "peak launch" and "peak
   serve" commands will soon require 'IWSGIApplication', and will not support
   'IRerunnableCGI' any more.)

   Of course, if you use the 'peak.web' framework, you don't need to worry
   about any of this; your apps will automatically be wrapped as
   'IWSGIApplication', and run in any PEAK server or gateway.

 - Most 'peak.web' interfaces have changed significantly.  If you implemented
   anything based on the older interfaces, and it still works, it's sheer
   bloody luck.  In particular, note that every method in 'web.IWebTraversable'
   now has different inputs and/or outputs than before.  Please read the new
   interface docs and update your code!  The changed interfaces offer much
   more flexibility and functionality than before, but they will require you to
   update your code.

 - 'web.ContainerAsTraversable' has been removed.  It was redundant, since the
   new default traversal mechanism used by 'Traversable' and 'Decorator' now
   handles getitem, getattr, and views.
 - Added Zope 3-like "namespaces" to 'peak.web'.  Path segments in a URL
   may be prefixed with '"++some_id++"' in order to invoke a corresponding
   namespace handler registered under '"peak.web.namespaces.some_id"'.
   Namespace handlers must implement 'web.INamespaceHandler', and they are
   supplied with the original path segment as well as the separated namespace
   and name.  Also, as in Zope 3, '"@@foo"' is a shortcut for '"++view++foo"'.
   Builtin namespaces at this time include 'view', 'item', 'attr', 'skin', and
   'resources'.  'skin' treats the rest of its path segment as a skin name,
   and sets the current skin, while 'resources' begins traversal to resources
   found in the current skin.  The other namespaces are as described at:

   "Resources and traversal in peak.web":http://www.eby-sarna.com/pipermail/peak/2004-August/001712.html

 - Fixed several 'peak.events' bugs, as reported by Vladimir Iliev, Yaroslav
   Samchuk, and Alexander Smishlajev:

   * 'events.AnyOf' could hold multiple references to a single event source,
     and nesting 'AnyOf()' calls could leak references to the nested events.

   * 'events.subscribe()' had a potential race condition wherein a callback
     could be invoked after its weak reference was garbage collected, leading
     to bizarre error messages about 'self' being 'None'.

   * 'select()' could be called on select event objects even if there were
     no current subscribers to the event, potentially leading to calling
     'select()' on a closed socket.

   * Non-default signal handlers were remaining installed even when there
     were no current subscribers to the applicable event, as long as a
     reference to the event object existed.

   As a result of these changes, certain I/O event types (esp. signals and
   stream readable/writeable events) are now longer-lived.  For example,
   signal event objects are now immortal, and the read/write event for a
   particular 'fileno()' will be reused for as long as its supplying
   'Selector' or 'EventLoop' instance exists.  (Previously, weak references
   were used so that these objects would be recycled when not in use.)

 - Added 'config.registeredProtocol()' API, that supports defining named and
   local protocols.  This allows easy emulation of Zope 3's "named" and "local"
   adapters and views.
 - 'binding.Component' objects no longer support instance configuration at
   runtime (i.e., they no longer implement 'config.IConfigurable').  If you
   need a component to be configurable at runtime, you must now derive from
   (or mix in) 'binding.Configurable' instead.  If you get errors about
   a missing 'registerProvider' attribute, or about being unable to adapt to
   'IConfigurable', try changing your base class from 'binding.Component'
   to 'binding.Configurable', or add it as a mixin if you're deriving from
   a class that uses 'binding.Component' as its base.

 - 'binding.IComponent' no longer derives from 'config.IConfigurable' or
   'config.IConfigMap', only 'config.IConfigSource'.  This means that
   'IComponent' no longer guarantees or requires the presence of the
   'registerProvider()' method: now only 'config.IConfigurable' does that.

 - The 'config.IConfigMap' interface is now DEPRECATED.  Use
   'config.IConfigurable' instead.  The '_configKeysMatching()' method
   of 'IConfigMap' was moved to 'config.IConfigSource', so if you've
   implemented a custom 'IConfigSource', be sure to add this method.

 - 'web.ISkinService' and 'web.ILayerService' were consolidated into
   'web.IInteractionPolicy', because the need to have configurable
   implementations of these services is negligible.  That is, the
   corresponding property namespaces ('peak.web.skins' and 'peak.web.layers')
   are more than adequate as registries.
 - Removed 'peak.running.timers' and 'peak.util.dispatch'.  Neither was in
   active use, and both are being replaced by the new generic functions
   package in PyProtocols.

 - The 'config.iterParents' API is now moved to 'binding.iterParents', and all
   'binding' functions that walk the component hierarchy use it.  It has also
   been changed to avoid infinite loops in the case of a pathological
   component structure.

 - The 'persistence' package has been moved to 'peak.persistence' to avoid
   conflicts with ZODB3 and the latest version of Zope 3.  It will eventually
   be phased out, but for now this move is the simplest way to get it out of
   the way.
 - The 'peak.util.SOX' module now uses only one parser, based directly on
   'expat', instead of using SAX.  The new parser expects a new node interface,
   'IXMLBuilder', but adapters from the previous interfaces ('ISOXNode' and
   'ISOXNode_NS') are supplied for backward compatibility.  All of PEAK's
   direct XML handling (currently just 'peak.storage.xmi' and
   'peak.web.templates') have been refactored to use the new interface.  Some
   parsing classes (such as 'ObjectMakingHandler', 'NSHandler', and
   'DOMletParser') are no longer available.

 - 'peak.web' no longer uses Zope X3 for HTTP publishing support; it has been
   refactored to use a "simpler, more uniform architecture":http://www.eby-sarna.com/pipermail/peak/2004-May/001462.html
   See also "more on the architecture":http://www.eby-sarna.com/pipermail/peak/2004-June/001482.html
   and subsequent posts in that thread.

   As a consequence, "various features have been removed":http://www.eby-sarna.com/pipermail/peak/2004-June/001500.html
   from 'peak.web', for possible return at a future date.  Here is a rough
   outline of the changes made so far:
    * The 'pageProtocol', 'pathProtocol', and 'errorProtocol' machinery are
      gone.  They will be replaced in the future with an explicit "controller"
      wrapping mechanism to allow application-specific renderings of the same
      underlying components.

    * The Zope 'request' and 'response' objects are gone, along with all of
      their special handling for cookies, character sets, form variables,
      automatically marshalling parameters to functions, etc.  These items of
      functionality will be gradually replaced by functions in 'peak.web.api'.

      As a result of this, arbitrary functions and methods can no longer be
      used as web pages; instead, functions and methods to be published must
      use the same inputs and outputs as the 'IHTTPHandler.handle_http()'

    * The 'IWebPage', 'IWebInteraction', 'ITraversalContext', 'Traversal',
      'TraversalContext', and 'Interaction' interfaces and classes no longer
      exist, as they are unneeded in the new architecture.  Instead of
      having a central 'IWebInteraction' that's referenced by numerous
      'ITraversalContext' objects, the new approach uses an 'environ' mapping
      for most functions.  For access control, a 'security.IInteraction' is
      now used, whose function is limited to security checks.  Most
      functions previously performed by 'IWebInteraction' have moved to
      'IInteractionPolicy' or to 'peak.web.api' functions operating on
      'environ' mappings.

    * Web exceptions can define a 'levelName' attribute that determines the
      severity level with which the exception will be logged.  This allows
      one to e.g. avoid logging tracebacks for 'NotFound' errors.

    * Various interface calling signatures have changed slightly.  For example,
      'IAuthService.getUser()' now accepts an 'environ' mapping instead of
      an interaction.  'IInteractionPolicy.newInteraction()' now takes keyword
      arguments, but not a 'request'.  The 'IWebTraversable' interface no longer
      has a 'getObject()' method, and the 'IWebException.handleException()'
      method signature has changed as well.  Finally, all methods that
      previously accepted 'ITraversalContext' (such as
      'IDOMletState.renderFor()') now expect 'environ' mappings.

    * 'web.TestInteraction' was replaced with 'web.TestPolicy', and
      'web.Interaction' was removed, since 'IWebInteraction' is no longer part
      of the architecture.

 - The 'log()' method of PEAK loggers ('logs.ILogger') now accepts a level name
   *or* a number, for convenient invocation.

 - SQL transaction semantics have changed.  Now, issuing an SQL statement
   *always* causes the connection to join the active PEAK transaction, even if
   you request that the SQL be issued "outside" a transaction.  Such SQL will
   be issued outside of the *database* transaction, but not outside of the
   PEAK transaction.  This simplifies the overall processing model for dealing
   with "untransacted" SQL such as Sybase DDL or read-only Oracle transactions.
   (In particular, the requirement that triggered this change was to allow
   Oracle read-only transactions to be released at the end of the current PEAK
   transaction.)  Also, got rid of the now-meaningless 'begin' command in n2.

 - The 'events.IEventSource' interface now returns a 'canceller' function from
   the 'addCallback()' method, allowing you to cancel a previously-scheduled
   callback.  This fixes a memory leak and performance problem with
   'events.AnyOf()', which previously could accumulate unneeded callbacks on
   the sources it was monitoring.  Note that if you have developed any custom
   event sources with 'addCallback()' methods, you must make sure that they
   return a canceller from now on.

 - Added 'ref:factory@addr1||addr2' URL scheme that maps to a corresponding
   'naming.Reference("factory",["addr1","addr2"])'.  'factory' can be either a
   dotted import string referencing a 'naming.IObjectFactory', or you can
   define a factory in the 'peak.naming.factories' property space.

 - Added a 'zconfig.schema' factory, so that 'ref:zconfig.schema@streamURL'
   will load a schema loader.  Schema loaders are themselves object factories,
   so you can do something like::

     [Named Services]
     peak.naming.factories.myschema = \

   in order to make URLs like 'ref:myschema@filename' work.  Note, by the way,
   that the above could also read::

     [Named Services]
     peak.naming.factories.myschema = \

   which runs somewhat faster at lookup time.  Similarly, one can also use
   'naming.Reference("myschema",["somefile"])' in place of a
   'naming.LinkRef("ref:myschema@filename")'.  As well as being faster, for
   some use cases it's easier to 'Reference' directly than to glue together
   a 'ref:' URL string.


Powered by ViewCVS 1.0-dev

ViewCVS and CVS Help