About sPickle
=============

sPickle is an advanced (and experimental) Pickler for Python. The code
was developed as part of a commercial project and released as free
software under the Apache 2.0 License by science + computing ag. The 
software is copyrighted by science + computing ag.

Why did we decide to make sPickle free software? We utilise Python and 
other open source products a lot. Therefore we think it is just fair
to release enhancements back to the public. 


Requirements
------------

* Python 2.7
* RPyC is used in the unit tests; the test is skipped, if 
  import rpyc fails.

(Sorry, Python 3 support is still in its beginnings. 
See https://github.com/akruis/sPickle/tree/py3port. I'll happily accept 
patches.)  
 

Installation
------------

Get easy_install and do "easy_install sPickle".
Or get the latest source code from github.
git clone git://github.com/akruis/sPickle.git

Using sPickle
-------------

The sPickle module provides a class sPickle.Pickler. This class is very 
similar to the conventional pickle.Pickler class and can be used as a 
drop in replacement. Instead of:

  from pickle import Pickler

  file = open(filename, "wb")
  pickler = Pickler(file, -1)
  pickler.dump(object_to_be_serialised)
  file.close()
  
you write:

  from sPickle import Pickler

  file = open(filename, "wb")
  pickler = Pickler(file, -1)
  pickler.dump(object_to_be_serialised)
  file.close()

You see, just 2 characters difference. Of course, there are more 
differences under the hood. 

* sPickle supports serialisation of more types than the conventional Pickler.
  In fact, most types can be pickled now, if serialisation makes any sense 
  for the particular type at all. But be warned: unpickling of some types
  requires the same Python version.
 
* A sPickle Pickler has a list-typed attribute "serializeableModules". You can
  use this attribute to determine which modules are to be pickled. For 
  details, read the comments in the source code and look at the examples.  

Support
=======
There is currently no support available, but you can drop me a mail.
a [dot] kruis [at] science-computing [dot] de
or use the facilities provided by https://github.com/akruis/sPickle

Plan
====
No further plans currently

Changes
=======

Version 0.1.8
-------------

2015-03-26
- Added support for pickling empty cell objects.
- PEP 8 fixes.

Version 0.1.7
-------------

2014-07-12
- Added the optional argument "logger" to class sPickle.Pickler. Can be used to
  customize or suppress logging.

Version 0.1.6
-------------

2014-05-09
- Added limited support for pickling objects returned by io.open(). 

Version 0.1.5
-------------

2014-04-16
- Cleanups, reformatted source (PEP-8).
- More robust test suite.
- Python 3 compatible syntax.
- I switched the SSH implementation used by the examples back to paramiko.
- No functional changes in package sPickle.

Version 0.1.4
-------------
2014-02-07
New class FailSavePickler. It is a subclass of Pickler, that can replace
otherwise unpickleable objects by surrogates.

Added support for pickling bound and unbound instance methods.

sPickle no longer requires "ssh" and "rpyc". Both modules are
are required to run the examples.

Version 0.1.3
-------------
2013-11-05
Improved pickling of abstract base classes. Every abstract base class
contains two WeakSet attributes _abs_cache and _abc_negative_cache. These 
sets cache the result of subclass tests. It is advisable not to pickle the 
content of those caches, because it could contain unpickleable objects.
This commit changes sPickle to replace _abs_cache and _abc_negative_cache
by new empty WeakSet instances.

Version 0.1.2
-------------
2013-05-22
Fixed two problems concerning module renaming.
Adapted to Python 2.7.4 and 2.7.5.

Note: Python 2.7.5 broke unpickling of named tuples pickled by Python 2.7.3 or 2.7.4.
This is Python bug http://bugs.python.org/issue18015. You can place the file
http://bugs.python.org/file30338/fix_python_275_issue18015.pth into your 
site-packages directory to monkey patch this bug.

Version 0.1.1
-------------
2012-11-06
Support pickling of classes with a custom meta class.
Improved sPickle.Pickler. It no longer modifies sys.modules or modules.

Version 0.1.0
-------------
2012-10-28
Support for plain Python

sPickle no longer requires Stackless Python for most of its work. Of course, 
if you want to pickle tasklets you need Stackless, but for functions, classes
and most other objects, the normal CPython 2.7 is good enough.

Version 0.0.9
-------------
2012-10-28
Support pickling of cStringIO objects.
Fixed pickling of recursive collections.OrderedDict objects
Support pickling of <type 'cell'> type objects.
Support pickling of weakref.ReferenceType objects without callback function.
Fixed pickling of modules with a modified __name__ attribute.
Support pickling of super objects.
Fixed classes with unusual __dict__ attribute.

Replaced REDUCE __import__ ... with GLOBAL. Now GLOBAL is used for all imports.
This change makes it possible to get all imported modules
using SPickleTools.getImportList().

Enhancements: 
- The new utility method SPickleTools.reducer() simplifies
  the implementation of complex __reduce__ methods.
- I Added an option to rename the module name of pickled objects.
- The methods dumps, dumps_with_external_ids and 
  remotemethod of class SPickleTools got new parameters.
- The class Pickler got a new method analysePicklerStack. It can
  be used to extract information about the Pickler state from 
  the stack or from a traceback.

Version 0.0.8
-------------
2012-07-17
Important bug fix: previous versions failed to pickle some classes.
Added support for member descriptors, getset descriptors and some
dictproxy objects.
    
Added a debugging aid for "id(obj) not in self.memo" assertions.
Set the environment variable SPICKLE_TRACE_MEMO_ENTRIES to a list of
space separated memo keys (integer numbers). sPickle will log information 
about the object hierarchy, when it adds a traced memo entry.

Version 0.0.7
-------------
Minor fixes. Changed the logging to delay log messages while holding the 
import lock. Otherwise you might get a dead-lock.
Upgrade the Python extensions used by the examples and switched from 
Paramiko to ssh.

Version 0.0.6
-------------
Improved the documentation and improved the method SPickleTools.remotemethod.

Version 0.0.5
-------------
Finally I found a few hours to add a nice documentation using Sphinx.
Besides the documentation, there are a few cleanups.

Version 0.0.4
-------------
Minor improvements, but unfortunately the documentation is still
incomplete. I release this version, because I'm going to present this
version in my talk at EuroPython 2011.

Version 0.0.3
-------------
Renamed example1 to example2 and added a new example1. Example1 now demonstrates
checkpointing of programs, example2 demonstrates RPyC.  
Fixed a few problems.
Use sPickle in flowGuide instead of the original flowGuide pickle code.


Version 0.0.2
-------------
Reorganised the directory layout, added this README.txt and fixed a few 
problems. Currently we still use a private source code repository as 
science + computing, but I plan to switch to github soon. 


Version 0.0.1
-------------
Initial version, released by science + computing ag. This version is more or 
less a copy of two modules from the flowGuide2 source code. The code works
for the specific requirements of flowGuide2, but has not been tested outside
of the flowGuide2 environment. 
