[Subversion] / PEAK / CHANGES.txt  

Diff of /PEAK/CHANGES.txt

Parent Directory | Revision Log

version 1431, Wed Oct 29 20:59:19 2003 UTC version 1606, Mon Jan 19 03:35:36 2004 UTC
Line 2 
Line 2 
   
  Changed, Enhanced, or Newly Deprecated Features   Changed, Enhanced, or Newly Deprecated Features
   
    - 'running.ISignalManager' is now DEPRECATED; please use 'events.ISignalSource'
      instead.
   
    - Added 'events.ISignalSource', that returns 'events.Broadcaster' objects for
      signals.  This allows you to yield to signals in an 'events.Thread', or
      safely set one-time callbacks on them.
   
    - 'running.IMainLoop' has been changed to use an 'events.IReadable' for
      the 'lastActivity' attribute, and the 'setExitCode' and 'childForked'
      methods have been replaced with an 'exitWith()' method.
   
    - The 'peak.running.mainLoop.signalHandler' property has been replaced with
      'peak.running.mainLoop.stopOnSignals', which defaults to including SIGINT,
      SIGTERM, and SIGBREAK.  If you need custom signal handling, please use
      the event sources provided by an 'events.ISignalSource'.
   
    - Simplified configuration for using Twisted, roughly as proposed in
      "this message.":http://www.eby-sarna.com/pipermail/peak/2004-January/001125.html
   
      You can now configure a service area as using Twisted by setting its
      'peak.running.isTwisted' property, or by depending upon the
      'running.ITwistedReactor' interface, as long as it happens early enough.
   
      If you need to make choices based on whether a Twisted reactor is being
      used, you should use the 'peak.running.scheduler.ifTwisted()' function.
      If you would like to try to force a service area to use a Twisted reactor,
      you may use 'peak.running.scheduler.makeTwisted()'.
   
    - Added automatic installation of 'csv' module for Python < 2.3.
   
    - Added 'peak.events' package, supporting a simple event-driven programming
      microkernel, including event-driven "ultralight" threads powered by
      generators.
   
    - "Global" services defined by '[Component Factories]' sections now live in
      the closest "service area" to the component that requests them.  A "service
      area" is a parent component that implements 'config.IServiceArea', such as
      a configuration root returned by 'config.makeRoot()'.  Applications loaded
      by the 'peak runIni' command are now created in their own service area,
      which means that settings in the .ini file being run will apply to services
      the application uses.  (Because the application will have its own,
      application-specific service instances, and they will use the configuration
      loaded into the service area.)
   
      If you need to create your own service area, you can do so by mixing in
      'config.ServiceArea' to your component class.  However, you should *not* do
      this unless you know exactly what "outside" services you may need to use
      from "inside" the newly created service area, so that you can explicitly
      connect them "into" the service area.  (In short, if you don't know *why*
      you're creating a service area, don't do it.)
   
    - 'config.Namespace()' objects now have a 'keys()' method that can be used
      when the namespace is bound to a context component.  It returns a list of
      strings that may be used as keys for that namespace.  Example usage::
   
       >>> from peak.api import *
       >>> r=config.makeRoot()
       >>> ns=config.Namespace('peak.naming.schemes',r)
       >>> ns.keys()
       ['https', 'smtp', 'logfile', 'psycopg', 'pkgfile', 'unix.dg', 'win32.dde',
       'sybase', 'timer', 'lockfile', 'pgsql', 'fd.socket', 'uuid', 'tcp', 'file',
       'gadfly', 'http', 'logger', 'icb', 'cxoracle', 'udp', 'winflockfile',
       'import', 'logging.logger', 'nulllockfile', 'nis', 'shlockfile',
       'zconfig.schema', 'flockfile', 'shellcmd', 'dcoracle2', 'config', 'ftp',
       'unix', 'ldap', 'sqlite', 'mockdb']
       >>> ns['ldap']
       'peak.storage.LDAP:ldapURL'
   
    - Log events don't use a positional 'message' argument any more, and
      loggers aren't responsible for interpolating message arguments any more.
      The new signature is 'Event(parent, msg=msg, args=args, ...)'.  Loggers
      also now tell events what logger name they are, via the 'ident' keyword.
   
    - The logging system now uses a property namespace, 'peak.logging.levels', to
      obtain log level names and values.  The various 'logs.LEVEL' constants are
      now DEPRECATED.  Please use the 'getLevelFor()' method of the nearest
      'logs.ILoggingService' instead.  Also note that URL schemes such as
      'logfile:' no longer convert their level names to numbers, since the
      level names are only meaningful in the context of a logging service.
   
    - Support for integration with the Python 2.3/PEP 282 logging module has been
      scaled back.  There are too many globalisms and dependencies there.  When we
      add plugin-based log configuration, it should be possible to use the logging
      package's handlers and formatters with the PEAK logging services.  At that
      point, you'll be able to replace 'logging.getLogger' and
      'logging.getLevelName' with the corresponding methods of a PEAK logging
      service, if you need to force non-PEAK packages to use PEAK's logging.
   
    - Logs are now accessed via a 'logs.ILoggingService' instance.  The 'logger:'
      URL scheme automatically accesses the nearest such service.  For backward
      compatibility, the old 'peak.logs' namespace is still used to supply the
      actual loggers.  This will be gradually replaced with a plugin-based
      mechanism.
   
    - Added 'binding.PluginKeys' and 'binding.PluginsFor'.  These are component
      keys that can be used to 'Obtain' plugins registered within a property
      namespace.  'PluginKeys' obtains a list of the plugins' configuration keys,
      while 'PluginsFor' obtains a list of the actual plugins.
   
    - Replaced 'peak.config.registries.EigenRegistry' with
      'peak.config.registries.ImmutableConfig'.  The only use we had for
      'EigenRegistry' was to keep track of 'offerAs' settings within classes, and
      it didn't need all the extra complexity of eigenstate management.  The new,
      more-specialized class is shorter, simpler, and easier to use.
   
    - Added 'config.iterKeys()' which iterates over all available configuration
      keys in a given namespace (just property names for now).  The 'config:'
      namespace is now a 'naming.IReadContext', so you can navigate it with the
      'n2' command, and do things like 'ls -l config:peak.naming.schemes' to list
      all configured naming schemes.
   
    - Added 'config.parentProviding()' and 'config.parentsProviding()', which
      find the first (or all) parent components of a given component that support
      a given protocol.
   
    - Renamings/refactorings/deprecations in 'peak.config':
   
       'config.getProperty' -- use 'config.lookup()' instead
   
       'config.findUtility' -- use 'config.lookup()' instead
   
       'config.findUtilities' -- use 'config.iterValues()' instead
   
       'config.IPropertyMap' -- use 'config.IConfigMap' or 'config.IConfigurable'
   
       'config.PropertyMap' -- use 'config.ConfigMap' instead
   
       'config.setPropertyFor' -- DEPRECATED, see source for replacement code.
   
       'config.setRuleFor' -- DEPRECATED, see source for replacement code.
   
       'config.setDefaultFor' -- DEPRECATED, see source for replacement code.
   
       'config.instancePerComponent' -- DEPRECATED, use factories instead.
   
       'config.IConfigurationRoot' -- interface has changed; 'propertyNotFound' is
       no longer a method, and 'noMoreUtilities' is now 'noMoreValues'.
   
       'exceptions.PropertyNotFound' -- use 'exceptions.NameNotFound' instead.
   
       'exceptions.OutOfScope' -- REMOVED; it was not actually used in PEAK.
   
      In all cases, the old interface, class, or function is DEPRECATED and will
      go away in the alpha 4 release cycle.  Please take particular note of the
      fact that 'IConfigMap' offers virtually none of the convenience
      methods provided by 'IPropertyMap', so adjust your code accordingly.  Note
      also that even though there are plenty of references to 'IPropertyMap'
      remaining in PEAK itself, these are strictly to provide backward
      compatibility.  Once we enter the alpha 4 release cycle, these will go away.
   
    - Added 'config.MultiKey()' and 'config.UnionOf()' configuration key classes,
      to generalize existing specialty keys such as 'ProviderOf' and 'FactoryFor'.
      (The latter two are now defined in terms of the former two.)  Also, made
      classes and types usable as configuration keys.  This was needed for the
      above generalization, but also makes many other class-lookup concepts
      possible.  (Note that there may be some slight changes to the effective
      registration and lookup order of these and other configuration keys as of
      this change, as there were some previous errors and/or ambiguities to the
      lookup order that were not covered by the test suite.)
   
    - Added "[Import on Demand]" section type to .ini files, allowing you to
      define shortcuts for modules that you frequently reference in your
      configuration.  This lets you replace e.g. 'importString("foo.bar.baz:Spam")'
      with 'foo_baz.Spam' in expressions, by adding something like this::
   
       [Import on Demand]
       foo_bar = "foo.bar.baz"
   
      to your configuration.  The defined shortcut is then available for the
      remainder of that configuration file, and in any .ini files included from
      the current file.  See 'peak.ini' for an example and more info.
   
    - Logging-related interfaces have been moved into the 'peak.running.logs'
      module.  So, what used to be 'running.ILogger' is now 'logs.ILogger'.
   
    - Log events now use a standard component construction signature, and the
      class used for event objects is now configurable as the factory for
      'logs.ILogEvent'.  (See "[Component Factories]" in 'peak.ini'.)
   
    - By popular demand, 'logs.ILogger' (and its default implementation) now
      includes 'trace()', 'notice()', 'alert()' and 'emergency()' methods that use
      the corresponding 'syslog' priority levels.  'logs.IBasicLogger' has been
      added, to reflect the narrower interface provided by PEP 282, and there is
      an adapter that can extend PEP 282 loggers with the other methods.
   
    - The 'logging.logger:' URL scheme has been simplified to 'logger:'.  Please
      convert your scripts and configuration files, as the longer form will go
      away in the alpha 4 development cycle.
   
    - Added 'commands.lookupCommand()' to look up a command shortcut or URL, ala
      the 'peak' script or 'commands.Bootstrap' class.  Also added various
      'commands.ErrorSubcommand' subclasses to make it easier to issue errors
      from/for subcommands.
   
    - Added 'peak.core' as a minimal subset of 'peak.api'.  'peak.core' offers
      only "core" API packages and primitives, not the full set of available
      framework APIs.  'peak.api' will continue to expand as frameworks are added,
      but 'peak.core' will stay as small as practical.  ('peak.exceptions' may in
      fact end up being removed from 'peak.core', or at least renamed.)
   
    - Added 'peak.util.symbol' module, to contain 'NOT_GIVEN', 'NOT_FOUND', and
      the 'Symbol' class used to create them.
   
    - 'peak.running.tools' was promoted to 'peak.tools'.  'peak.running.supervisor'
      was also moved to 'peak.tools.supervisor', and a new 'peak help' command was
      added in 'peak.tools.api_help'.
   
    - Replaced the "[Provide Utilities]" section of .ini files with "[Component
      Factories]".  The new section type is easier to use, much more versatile,
      and does all registration and imports lazily.  See the 'peak.ini' file for
      docs.  "[Provide Utilities]" and 'config.ProvideInstance()' are now
      DEPRECATED, so please convert ASAP.
   
    - 'binding.Make()' now accepts configuration keys, using them to look up a
      factory object that's then invoked to create the attribute.  This makes it
      a lot easier to define a component with its own transaction service,
      'IBasicReactor', or other normally "global" component.  It also makes it
      easier to globally specify a factory class for some interface.  Factories
      are looked up under the 'config.FactoryFor(key)' configuration key.  (See
      below.)
   
    - Added 'config.FactoryFor(key)', a 'config.IConfigKey' implementation that
      provides a configuration namespace for factories.
   
      When you use 'binding.Make(ISomething)', it's roughly equivalent to::
   
           binding.Make(
               lambda self,d,a:
                   binding.lookupComponent(
                       self, config.FactoryFor(ISomething),
                       adaptTo = binding.IRecipe
                   )(self,d,a)
           )
   
      That is, the 'config.FactoryFor(ISomething)' is looked up and invoked.
   
    - Added 'config.CreateViaFactory(key)', a 'config.IRule' implementation that
      creates an implementation of 'key', by looking up 'config.FactoryFor(key)'
      and invoking it.
   
    - Added 'config.ruleForExpr(name,expr)', that returns a 'config.IRule' that
      computes the Python expression in the string 'expr'.  This is the mechanism
      used by configuration files to create rules, factored out into an API call
      so that configuration extensions can use it, too.
   
    - The 'referencedType' of a 'model.StructuralFeature' can now be any
      'binding.IComponentKey', not just a type or a string.  Types are also now
      implicitly component keys, which means you can use 'binding.Obtain(SomeType)'
      to look up 'SomeType'.  (Right now, this is no different than using 'SomeType'
      without the 'binding.Obtain()', but in future releases this will use a
      "class replacement service" to allow easy replacement of model and other
      collaborator classes, while implementing AOP-like features.)
   
    - Added 'naming.Indirect(key)', a 'binding.IComponentKey' that can be used to
      do an indirect lookup via another 'IComponentKey' (such as a name).
   
      Using 'naming.Indirect()', you can replace code like this::
   
           socket = binding.Obtain(
               lambda self: self.lookupComponent(self.socketURL),
               adaptTo=[IListeningSocket]
           )
   
      with code like this::
   
           socket = binding.Obtain(
               naming.Indirect('socketURL'), adaptTo=[IListeningSocket]
           )
   
    - Added 'peak.tools.supervisor', a mini-framework for pre-forking,
      multiprocess servers, such as for FastCGI.  The framework includes a ZConfig
      schema for process supervisors, and support for automatically forking new
      children (up to a predefined maximum, with a minimum interval between
      launches) when a socket has pending connections and all of its child
      processes are busy.  With this setup, you can take more advantage of
      multiprocessor machines for CPU-intensive services.
   
    - Standardized these characteristics of name and address syntax:
   
      * '//' at the beginning of URL bodies is *mandatory* when the URL begins
        with an "authority" as described by RFC 2396.  When the URL is not
        required to contain an authority (e.g. 'peak.storage.SQL.GenericSQL_URL'),
        the '//' is *optional*, and the canonical form of the URL will not include
        it.
   
      * Standardized names for RFC 2396 fields: 'user', 'passwd', 'host', and
        'port'.
   
    - Added 'peak.metamodels.ASDL', a metamodel for the Zephyr Abstract Syntax
      Description Language.  ASDL is a convenient way to describe a domain model
      for an abstract syntax tree (AST), and the models generated with the new
      ASDL tool can be combined with concrete syntax to create a complete parsing
      solution for "mini languages", possibly including the Python language
      itself.  (Future versions of the Python and Jython compilers are likely to
      use AST models based on ASDL, and in the current Python CVS sandbox there's
      already an ASDL model of Python's AST available.)
   
    - Enhanced 'fmtparse' and 'peak.model' to allow using types as syntax rules
      for parsing, including abstract types.  An abstract type's syntax is the
      union (using 'fmtparse.Alternatives') of the syntaxes of its subclasses
      (as specified by 'mdl_subclassNames').
   
    - Added 'IMainLoop.setExitCode()' and 'IMainLoop.childForked()' methods, to
      allow reactor-driven components to control the mainloop's exit code.
   
    - Added 'IBasicReactor.crash()', which forces an immediate reactor loop exit,
      ignoring pending scheduled calls.
   
    - Added 'peak.running.commands.runMain()', a convenience function for starting
      an application's "main" command, that also makes it easy for forked child
      processes to exit and replace the parent process' "main".  The 'peak' script
      has now been shortened to::
   
          from peak.running import commands
          commands.runMain( commands.Bootstrap )
   
      so it's now much easier to create alternative startup scripts, if you need
      to, or to add an 'if __name__=="__main__"' clause to a module.
   
    - Added 'peak.util.mockdb', a "mock object" implementation of a DBAPI 2.0
      driver module.  'mockdb' connections can be told to 'expect()' queries
      and 'provide()' data to their callers, and will raise AssertionErrors when
      they are used in a way that doesn't conform to your supplied expectations.
      This is intended to be used for unit testing components that depend on
      a database connection: you can verify that they send the right SQL, and
      you can provide them with dummy data to use.  There is also a 'mockdb:' URL
      and peak.storage driver, so you can easily use a mock DB connection in place
      of a real one within a PEAK application, for testing purposes.  Note,
      however, that 'peak.util.mockdb' is a DBAPI 2.0 driver in itself, and thus
      can also be used to test DBAPI usage outside of PEAK.
   
    - SQL connection objects now provide an 'appConfig' attribute that is a
      driver-specific 'config.Namespace()'.  This allows you to easily set up
      configuration properties that are driver-specific.  For example, you could
      use properties to configure driver-specific SQL snippets, then access them
      via the connection's 'appConfig' namespace.  The namespaces are of the form
      'DRIVER.appConfig', where 'DRIVER' is the name of the DBAPI module for that
      connection type (e.g. 'pgdb', 'cx_Oracle', etc.).
   
    - Added 'config.Namespace()' convenience class for redirecting property
      lookups from one namespace to another.  See the docstring and 'peak.ini' for
      usage examples.  'PropertyName.of()' now returns 'Namespace' instances
      instead of 'PropertySet' instances.
   
    - DEPRECATED the 'config.PropertySet' class; please convert to using
      'config.Namespace', as 'PropertySet' will disappear in the 0.5alpha4 release
      cycle.
   
  - SQL connection objects now get their type converters from a distinct   - SQL connection objects now get their type converters from a distinct
    property namespace for each DBAPI driver.  For example a driver using the     property namespace for each DBAPI driver.  For example a driver using the
    'cx_Oracle' module will get its type converters from the     'cx_Oracle' module will get its type converters from the
Line 31 
Line 379 
   
    'Constant(value)' -- use 'Make(lambda: value)'     'Constant(value)' -- use 'Make(lambda: value)'
   
    'Acquire(key)' -- use 'Obtain(key, offerAs=[key])'     'Acquire(key)' -- use 'Obtain(key, offerAs=[key,])'
   
    'Copy(value)' -- use 'Make(lambda: <expr to copy value>)'     'Copy(value)' -- use 'Make(lambda: <expr to copy value>)'
   
Line 91 
Line 439 
    file that describes your project's version numbering scheme(s), formats,     file that describes your project's version numbering scheme(s), formats,
    and the files that need to be edited, while the 'version.dat' file contains     and the files that need to be edited, while the 'version.dat' file contains
    the current version number values.  Source for the tool, including the     the current version number values.  Source for the tool, including the
    configuration file schema, is in the 'peak.running.tools.version' package.     configuration file schema, is in the 'peak.tools.version' package.
    (Error handling and documentation, alas, are still minimal.)     (Error handling and documentation, alas, are still minimal.)
   
  - Added new 'Alias' command in 'peak.running.commands'.  An 'Alias' instance   - Added new 'Alias' command in 'peak.running.commands'.  An 'Alias' instance
Line 109 
Line 457 
    'naming.IBasicContext', which does something very different.     'naming.IBasicContext', which does something very different.
   
  - 'binding.Obtain()' (formerly 'binding.bindTo()' and 'binding.bindSequence()')   - 'binding.Obtain()' (formerly 'binding.bindTo()' and 'binding.bindSequence()')
    now pre-adapt their arguments to 'IComponentKey', to speed lookups at     now pre-adapt their arguments to 'IComponentKey', to speed up lookups at
    runtime, and to ensure that errors due to an unusable parameter type occur     runtime, and to ensure that errors due to an unusable parameter type occur
    at class creation time instead of waiting until lookup time.     at class creation time instead of waiting until lookup time.
   
Line 122 
Line 470 
    property ('peak.running.reactor.checkInterval') to determine how long it     property ('peak.running.reactor.checkInterval') to determine how long it
    should run 'select()' calls for, when there are no scheduled tasks.     should run 'select()' calls for, when there are no scheduled tasks.
   
  - 'peak.running.scheduler.UntwistedReactor' now supports using a "signal  
    manager" component (via the 'peak.running.signalManager' property) to  
    process signals while a 'run()' loop is in progress.  Signal managers can  
    also be added or removed at any time via the new 'peak.util.signal_stack'  
    module.  
   
  - 'peak.running.commands.AbstractCommand' now offers a '_run()' method that   - 'peak.running.commands.AbstractCommand' now offers a '_run()' method that
    can be overridden in subclasses, instead of 'run()'.  If you override the     can be overridden in subclasses, instead of 'run()'.  If you override the
    new '_run()' method instead, you get the advantage of automatic handling     new '_run()' method instead, you get the advantage of automatic handling
Line 218 
Line 560 
    means you should change 'return foo, None' statements to just 'return foo'.     means you should change 'return foo, None' statements to just 'return foo'.
   
  - Property definition rules in an .ini file can now refer to 'rulePrefix' and   - Property definition rules in an .ini file can now refer to 'rulePrefix' and
    'ruleSuffix' variables.  'rulePrefix' is a '.'-terminated string,     'ruleSuffix' variables.  'rulePrefix' is a "."-terminated string,
    representing the name the rule was defined with.  For example, if the     representing the name the rule was defined with.  For example, if the
    rule was defined for '"foo.bar.*"', then 'rulePrefix' will be '"foo.bar."'.     rule was defined for '"foo.bar.*"', then 'rulePrefix' will be '"foo.bar."'
   
    The 'ruleSuffix' will be the portion of the 'propertyName' that follows     The 'ruleSuffix' will be the portion of the 'propertyName' that follows
    'rulePrefix'.  So, if looking up property '"foo.bar.baz"', then the     'rulePrefix'.  So, if looking up property '"foo.bar.baz"', then the
    '"foo.bar.*"' rule will execute with a 'ruleSuffix' of '"baz"'.  This should     '"foo.bar.*"' rule will execute with a 'ruleSuffix' of '"baz"'.  This should
Line 294 
Line 637 
   
  Corrected Problems   Corrected Problems
   
     - 'peak.running.commands.CGICommand' could become confused on certain BSD
       variants (such as Mac OS/X), and assume it was running under FastCGI, even
       if it wasn't.  (Because the operating systems in question use socket pairs
       to implement pipes.)
   
     - Fixed some problems with the test suite when running under Python 2.3.
       PEAK itself worked fine, but the test suite was bitten by two minor
       semantic changes that took effect in 2.3, resulting in lots of error
       messages about ModuleType needing a parameter, and a test failure for
       'checkClassInfo' in the 'FrameInfoTest' test class.
   
   - Transaction participants that raised an error in their 'abortTransaction()'    - Transaction participants that raised an error in their 'abortTransaction()'
     method, would not receive a 'finishTransaction()' call, the error was      method, would not receive a 'finishTransaction()' call, the error was
     passed through to the transaction service's caller, and later participants      passed through to the transaction service's caller, and later participants


Generate output suitable for use with a patch program
Legend:
Removed from v.1431  
changed lines
  Added in v.1606

cvs-admin@eby-sarna.com

Powered by ViewCVS 1.0-dev

ViewCVS and CVS Help