Mike Bayer avatar Mike Bayer committed 63b9201

- added serializer docs to plugins.txt
- CHANGES formatting

Comments (0)

Files changed (2)

 ========
 - features
 - orm
-    - Added two new hooks to SessionExtension: after_bulk_delete and
-      after_bulk_update. after_bulk_delete is called after a bulk delete()
-      operation on a query. after_bulk_update is called after a bulk update()
-      operation on a query.
+    - Added two new hooks to SessionExtension:
+      after_bulk_delete() and after_bulk_update().
+      after_bulk_delete() is called after a bulk delete()
+      operation on a query. after_bulk_update() is called 
+      after a bulk update() operation on a query.
 
 - sql
-    - SQL compiler optimizations.  The call count for compiling a
-      typical select() construct is 20% less versus 0.5.0rc2.
-
-    - Dialects can now generate label names of adjustable length.
-      Pass in the argument "label_length=<value>" to create_engine()
-      to adjust how many characters max will be present in dynamically
-      generated column labels, i.e. "somecolumn AS somelabel".  Any 
-      value less than 6 will result in a label of minimal size,
-      consiting of an underscore and a numeric counter.
-      The compiler uses the value of dialect.max_identifier_length
-      as a default. [ticket:1211]
+    - SQL compiler optimizations and complexity
+      reduction. The call count for compiling a
+      typical select() construct is 20% less versus
+      0.5.0rc2.
+
+    - Dialects can now generate label names of adjustable
+      length. Pass in the argument "label_length=<value>" to
+      create_engine() to adjust how many characters max will
+      be present in dynamically generated column labels, i.e.
+      "somecolumn AS somelabel". Any value less than 6 will
+      result in a label of minimal size, consiting of an
+      underscore and a numeric counter. The compiler uses the
+      value of dialect.max_identifier_length as a default.
+      [ticket:1211]
 
 - ext
-    - Added a new extension sqlalchemy.ext.serializer.  Provides
-      Serializer/Deserializer "classes" which mirror Pickle/Unpickle,
-      as well as dumps() and loads().  This serializer implements
-      an "external object" pickler which keeps key context-sensitive
-      objects, including engines, sessions, metadata, Tables/Columns,
-      and mappers, outside of the pickle stream, and can later 
-      restore the pickle using any engine/metadata/session provider.   
-      This is used not for pickling regular object instances, which are 
-      pickleable without any special logic, but for pickling expression
-      objects and full Query objects, such that all mapper/engine/session
+    - Added a new extension sqlalchemy.ext.serializer.
+      Provides Serializer/Deserializer "classes" which mirror
+      Pickle/Unpickle, as well as dumps() and loads(). This
+      serializer implements an "external object" pickler
+      which keeps key context-sensitive objects, including
+      engines, sessions, metadata, Tables/Columns, and
+      mappers, outside of the pickle stream, and can later
+      restore the pickle using any engine/metadata/session
+      provider. This is used not for pickling regular object
+      instances, which are pickleable without any special
+      logic, but for pickling expression objects and full
+      Query objects, such that all mapper/engine/session
       dependencies can be restored at unpickle time.
 
 - oracle
-    - Wrote a docstring for Oracle dialect.  Apparently that Ohloh
-      "few source code comments" label is starting to sting :).
-
-    - Removed FIRST_ROWS() optimize flag when using LIMIT/OFFSET,
-      can be reenabled with optimize_limits=True create_engine()
-      flag.  [ticket:536]
+    - Wrote a docstring for Oracle dialect. Apparently
+      that Ohloh "few source code comments" label is
+      starting to sting :).
+
+    - Removed FIRST_ROWS() optimize flag when using
+      LIMIT/OFFSET, can be reenabled with
+      optimize_limits=True create_engine() flag.
+      [ticket:536]
 
 - bugfixes and behavioral changes
 - orm
-    - "not equals" comparisons of simple many-to-one relation to an
-      instance will not drop into an EXISTS clause and will compare
-      foreign key columns instead.
-
-    - Removed not-really-working use cases of comparing a collection
-      to an iterable.  Use contains() to test for collection
-      membership.
-
-    - Improved the behavior of aliased() objects such that they more
-      accurately adapt the expressions generated, which helps 
-      particularly with self-referential comparisons. [ticket:1171]
+    - "not equals" comparisons of simple many-to-one
+      relation to an instance will not drop into an
+      EXISTS clause and will compare foreign key
+      columns instead.
+
+    - Removed not-really-working use cases of
+      comparing a collection to an iterable. Use
+      contains() to test for collection membership.
+
+    - Improved the behavior of aliased() objects such
+      that they more accurately adapt the expressions
+      generated, which helps particularly with
+      self-referential comparisons. [ticket:1171]
       
-    - Fixed bug involving primaryjoin/secondaryjoin conditions
-      constructed from class-bound attributes (as often occurs 
-      when using declarative), which later would be inappropriately 
-      aliased by Query, particularly with the various EXISTS
-      based comparators.
+    - Fixed bug involving primaryjoin/secondaryjoin
+      conditions constructed from class-bound
+      attributes (as often occurs when using
+      declarative), which later would be
+      inappropriately aliased by Query, particularly
+      with the various EXISTS based comparators.
     
-    - Fixed bug when using multiple query.join() with an aliased-bound
-      descriptor which would lose the left alias.
+    - Fixed bug when using multiple query.join() with
+      an aliased-bound descriptor which would lose the
+      left alias.
       
-    - Improved weakref identity map memory management to no longer
-      require mutexing, resurrects garbage collected instance on a
-      lazy basis for an InstanceState with pending changes.
-
-    - relation() won't hide unrelated ForeignKey errors inside of
-      the "please specify primaryjoin" message when determining join
+    - Improved weakref identity map memory management
+      to no longer require mutexing, resurrects
+      garbage collected instance on a lazy basis for
+      an InstanceState with pending changes.
+
+    - InstanceState object now removes circular
+      references to itself upon disposal to keep it
+      outside of cyclic garbage collection.
+
+    - relation() won't hide unrelated ForeignKey
+      errors inside of the "please specify
+      primaryjoin" message when determining join
       condition.
 
-    - Fixed bug in Query involving order_by() in conjunction with 
-      multiple aliases of the same class (will add tests in 
-      [ticket:1218])
+    - Fixed bug in Query involving order_by() in
+      conjunction with multiple aliases of the same
+      class (will add tests in [ticket:1218])
       
-    - When using Query.join() with an explicit clause for the ON
-      clause, the clause will be aliased in terms of the left side
-      of the join, allowing scenarios like query(Source).
-      from_self().join((Dest, Source.id==Dest.source_id)) to work
-      properly.
-
-    - polymorphic_union() function respects the "key" of each Column
-      if they differ from the column's name.
-
-    - Repaired support for "passive-deletes" on a many-to-one
-      relation() with "delete" cascade. [ticket:1183]
-
-    - Fixed bug in composite types which prevented a primary-key
-      composite type from being mutated [ticket:1213].
+    - When using Query.join() with an explicit clause
+      for the ON clause, the clause will be aliased in
+      terms of the left side of the join, allowing
+      scenarios like query(Source).
+      from_self().join((Dest,
+      Source.id==Dest.source_id)) to work properly.
+
+    - polymorphic_union() function respects the "key"
+      of each Column if they differ from the column's
+      name.
+
+    - Repaired support for "passive-deletes" on a
+      many-to-one relation() with "delete" cascade.
+      [ticket:1183]
+
+    - Fixed bug in composite types which prevented a
+      primary-key composite type from being mutated
+      [ticket:1213].
       
-    - Added more granularity to internal attribute access, such that
-      cascade and flush operations will not initialize unloaded
-      attributes and collections, leaving them intact for a
-      lazy-load later on.  Backref events still initialize attrbutes
-      and collections for pending instances.  [ticket:1202]
-
-    - InstanceState object now removes circular references to itself
-      upon disposal to keep it outside of cyclic garbage collection.
+    - Added more granularity to internal attribute
+      access, such that cascade and flush operations
+      will not initialize unloaded attributes and
+      collections, leaving them intact for a lazy-load
+      later on. Backref events still initialize
+      attrbutes and collections for pending instances.
+      [ticket:1202]
 
 - sql
-    - Simplified the check for ResultProxy "autoclose without results"
-      to be based solely on presence of cursor.description.   
-      All the regexp-based guessing about statements returning rows 
-      has been removed [ticket:1212].
+    - Simplified the check for ResultProxy "autoclose
+      without results" to be based solely on presence
+      of cursor.description. All the regexp-based
+      guessing about statements returning rows has
+      been removed [ticket:1212].
     
-    - Further simplified SELECT compilation and its relationship to
-      result row processing.
-
-    - Direct execution of a union() construct will properly set up
-      result-row processing. [ticket:1194]
-
-    - The internal notion of an "OID" or "ROWID" column has been
-      removed.  It's basically not used by any dialect, and the
-      possibility of its usage with psycopg2's cursor.lastrowid is
-      basically gone now that INSERT..RETURNING is available.
-
-    - Removed "default_order_by()" method on all FromClause objects.
-
-    - Repaired the table.tometadata() method so that a passed-in
-      schema argument is propigated to ForeignKey constructs.
+    - Direct execution of a union() construct will
+      properly set up result-row processing.
+      [ticket:1194]
+
+    - The internal notion of an "OID" or "ROWID"
+      column has been removed. It's basically not used
+      by any dialect, and the possibility of its usage
+      with psycopg2's cursor.lastrowid is basically
+      gone now that INSERT..RETURNING is available.
+
+    - Removed "default_order_by()" method on all
+      FromClause objects.
+
+    - Repaired the table.tometadata() method so that a
+      passed-in schema argument is propigated to
+      ForeignKey constructs.
       
-    - Slightly changed behavior of IN operator for comparing to
-      empty collections. Now results in inequality comparison
-      against self. More portable, but breaks with stored procedures
-      that aren't pure functions.
+    - Slightly changed behavior of IN operator for
+      comparing to empty collections. Now results in
+      inequality comparison against self. More
+      portable, but breaks with stored procedures that
+      aren't pure functions.
 
 - oracle
-    - Setting the auto_convert_lobs to False on create_engine() will
-      also instruct the OracleBinary type to return the cx_oracle
-      LOB object unchanged.
+    - Setting the auto_convert_lobs to False on
+      create_engine() will also instruct the
+      OracleBinary type to return the cx_oracle LOB
+      object unchanged.
 
 - mysql
-    - Fixed foreign key reflection in the edge case where a Table's
-      explicit schema= is the same as the schema (database) the
-      connection is attached to.
-
-    - No longer expects include_columns in table reflection to be
-      lower case.
+    - Fixed foreign key reflection in the edge case
+      where a Table's explicit schema= is the same as
+      the schema (database) the connection is attached
+      to.
+
+    - No longer expects include_columns in table
+      reflection to be lower case.
 
 - ext
-    - Fixed bug preventing declarative-bound "column" objects 
-      from being used in column_mapped_collection().  [ticket:1174]
+    - Fixed bug preventing declarative-bound "column"
+      objects from being used in
+      column_mapped_collection(). [ticket:1174]
 
 - misc
-    - util.flatten_iterator() func doesn't interpret strings with
-      __iter__() methods as iterators, such as in pypy [ticket:1077].
+    - util.flatten_iterator() func doesn't interpret
+      strings with __iter__() methods as iterators,
+      such as in pypy [ticket:1077].
       
 0.5.0rc2
 ========

doc/build/content/plugins.txt

 information, and also check out the unit tests for examples of stepped
 numbering, alphabetical and Fibonacci numbering.
 
+### serializer
+
+**Author:** Mike Bayer
+
+Serializer/Deserializer objects for usage with SQLAlchemy structures.
+
+Any SQLAlchemy structure, including Tables, Columns, expressions, mappers,
+Query objects etc. can be serialized in a minimally-sized format,
+and deserialized when given a Metadata and optional ScopedSession object
+to use as context on the way out.
+
+Usage is nearly the same as that of the standard Python pickle module:
+
+    {python}
+    from sqlalchemy.ext.serializer import loads, dumps
+    metadata = MetaData(bind=some_engine)
+    Session = scoped_session(sessionmaker())
+    
+    # ... define mappers
+    
+    query = Session.query(MyClass).filter(MyClass.somedata=='foo').order_by(MyClass.sortkey)
+    
+    # pickle the query
+    serialized = dumps(query)
+    
+    # unpickle.  Pass in metadata + scoped_session
+    query2 = loads(serialized, metadata, Session)
+    
+    print query2.all()
+
+Similar restrictions as when using raw pickle apply; mapped classes must be 
+themselves be pickleable, meaning they are importable from a module-level
+namespace.
+
+Note that instances of user-defined classes do not require this extension
+in order to be pickled; these contain no references to engines, sessions
+or expression constructs in the typical case and can be serialized directly.
+This module is specifically for ORM and expression constructs.
+
 ### SqlSoup
 
 **Author:** Jonathan Ellis
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.