pli/serialize/serialize.py

   1 #=======================================================================
   2 #-----------------------------------------------------------------------
   3
   4 __version__ = '''0.0.00'''
   5 __sub_version__ = '''20031106031445'''
   6 __copyright__ = '''(c) Alex A. Naanou 2003'''
   7
   8
   9
  10 #-----------------------------------------------------------------------
  11 __doc__ = '''
  12 '''
  13
  14 #-----------------------------------------------------------------------
  15 # System Concepts:
  16 #       Stream
  17 #               a recursive data format (container) that supports the stream
  18 #               read and write interfaces/protocols.
  19 #       StreamWriter
  20 #               Stream -> Data
  21 #               an entity that reads data from a stream and writes it out.
  22 #       StreamReader
  23 #               Data -> Stream
  24 #               an entity that read data and writes it to a stream.
  25 #
  26 #
  27 # Basic Operation:
  28 #
  29 #                       StreamReader
  30 #                 ---------------->
  31 #       Data                                    Stream
  32 #                 <----------------
  33 #                        StreamWriter
  34 #
  35 #
  36 #
  37 #                 -------------------- Serialize ------------------->
  38 #
  39 #                                StreamReader                      StreamWriter
  40 #                          ---------------->             ---------------->
  41 #       PythonData                                       Stream                                          Data
  42 #                          <----------------             <----------------
  43 #                                 StreamWriter                          StreamReader
  44 #
  45 #                 <------------------ Deserialize -------------------
  46 #
  47 #
  48 # Data Format:
  49 #       all data is a stream.
  50 #
  51 #       any stream can either be mutable or immutable (defined in
  52 #       constructor), this is only used for read write operations as on the
  53 #       inside, a stream may be all mutable (for optimization.)
  54 #
  55 #       a stream is not editable!.
  56 #
  57 #       a chained stream can be a receiver, a transmitter or a channeler
  58 #       (receive and transmit).
  59 #
  60 #       Stream Data Processors:
  61 #               ReferenceStream: (???)
  62 #                       this is a reference to another stream in the registry.
  63 #
  64 #               NumberStream:
  65 #                       this is a stream that can contain one or more basic values.
  66 #                       corresponds to pythons:
  67 #                               int
  68 #                               float
  69 #                               complex
  70 #
  71 #               StringStream:
  72 #                       this is a stream that can contain one or more basic values.
  73 #                       corresponds to pythons:
  74 #                               string
  75 #                               unicode
  76 #                               code
  77 #
  78 #               SequenceStream:
  79 #                       this can contain zero or more streams (e.g. "stream of streams").
  80 #                       corresponds to pythons:
  81 #                               tuple
  82 #                               list
  83 #
  84 #               MappingStream:
  85 #                       this contains zero or more pairs of the form:
  86 #                               <ElementStream> : <any>
  87 #                       corresponds to pythons:
  88 #                               dict
  89 #
  90 #               ObjectStream:
  91 #                       this is a Stream with additional stores/attributes (e.g. all data
  92 #                       is stored in named streams)
  93 #                       essential attributes:
  94 #                               type
  95 #                               module
  96 #                               namespace
  97 #                               ...
  98 #                       optional attributes:
  99 #                               name
 100 #                               ...
 101 #                       corresponds to pythons:
 102 #                               type
 103 #                               classobj
 104 #                               object
 105 #                               class
 106 #                               instance
 107 #                               function
 108 #
 109 #               FunctionStream:
 110 #
 111 # Usage Patterns:
 112 #       Stream chaining
 113 #               StreamReader -> StreamWriter
 114 #               StreamReader -> GenericStream
 115 #               GenericStream -> StreamWriter
 116 #
 117 #
 118 # Stream Interface:
 119 #       open                    -- will open a sub-stream.
 120 #       close                   -- will close a sub-stream.
 121 #       insert                  -- will insert an element into the current stream.
 122 #       set                             -- will set a stream attribute (__setattr__).
 123 #
 124 #
 125 #
 126
 127 #=======================================================================
 128
 129 import stream
 130
 131
 132 #---------------------------------------------------------StreamError---
 133 class StreamError(Exception):
 134         '''
 135         '''
 136         pass
 137
 138
 139
 140 #-----------------------------------------------------------------------
 141 #------------------------------------------------------StreamRegistry---
 142 class StreamRegistry(object):
 143         '''
 144         this will keep track of objects in a stream.
 145         '''
 146         pass
 147
 148
 149 #--------------------------------------------------------------Stream---
 150 # TODO add support for stream object registry... (???)
 151 class Stream(stream.Stream):
 152         '''
 153         this is an abstract stream object.
 154         '''
 155         ##!! revise the dispatcher interface in the following !!##
 156         # Stream Magic Methods...
 157         # NOTE: in the folowing methods the dispatch attribute must resolve
 158         #       to the stream managers dispatcher object...
 159         #       this will permit nested stream managers (e.g. serialize all
 160         #       objects using the Pickle format but the objects of type X
 161         #       which are to be serialized into XML, or use diferent xml
 162         #       formats for diferent object types... etc.)
 163         #       NOTE: for the above to work properlyit may be good to pass
 164         #             the "reference" to the serialized object or file
 165         #             upwards to the conatining stream...
 166         def __open__(self, parent_stream, *pargs, **nargs):
 167                 '''
 168                 this method is called opun stream open.
 169                 '''
 170                 # call the dispatch...
 171 ##              self.dispatch('open', type(self), parent_stream, *pargs, **nargs)
 172                 self.dispatch.open(type(self), parent_stream, *pargs, **nargs)
 173         def __close__(self):
 174                 '''
 175                 this method is called on stream close.
 176                 '''
 177                 # call the dispatch...
 178 ##              self.dispatch('close', type(self))
 179                 self.dispatch.close(type(self))
 180         def __insert__(self, *pargs, **nargs):
 181                 '''
 182                 this method is called on object insert.
 183                 '''
 184                 # call the dispatch...
 185 ##              self.dispatch('insert', type(self), *pargs, **nargs)
 186                 self.dispatch.insert(type(self), *pargs, **nargs)
 187
 188
 189
 190 #-----------------------------------------------------------------------
 191 # these objects must call the *contexts* interface functions...
 192 #--------------------------------------------------------NumberStream---
 193 class NumberStream(Stream):
 194         '''
 195         '''
 196
 197
 198 #--------------------------------------------------------StringStream---
 199 class StringStream(Stream):
 200         '''
 201         '''
 202
 203
 204 #------------------------------------------------------SequenceStream---
 205 class SequenceStream(Stream):
 206         '''
 207         '''
 208
 209
 210 #-------------------------------------------------------MappingStream---
 211 class MappingStream(Stream):
 212         '''
 213         '''
 214
 215
 216 #--------------------------------------------------------ObjectStream---
 217 class ObjectStream(Stream):
 218         '''
 219         '''
 220
 221
 222 #-----------------------------------------------------ReferenceStream---
 223 # this should hold information on the location of the stream, its type
 224 # and data needed for the stream to be properely processed...
 225 # modes:
 226 #       1. create a reference inside the current stream (needs: target id
 227 #          (from stream registry)).
 228 #       2. create a stream object using an "external" stream processor
 229 #          (needs: ...).
 230 #
 231 ##!! revise !!##
 232 class ReferenceStream(Stream):
 233         '''
 234         this is a spetial object to be used as a link to a diferent stream object.
 235         '''
 236
 237
 238
 239 #=======================================================================
 240 #---------------------------------------------StreamProcessorDispatch---
 241 # Search Order:
 242 #       1. specific type processor in/for meta-stream
 243 #       2. meta-stream processor
 244 #       3. Err: unsupported object type.
 245 #
 246 class StreamProcessorDispatch(object):
 247         '''
 248         '''
 249         def __init__(self):
 250                 '''
 251                 '''
 252                 pass
 253         # dispatch interface methods...
 254         def register_processor(self, stream_type, obj):
 255                 '''
 256                 '''
 257         # stream interface methods...
 258         def open(self, stream_type, stream_length=None, stream_id=None, *pargs, **nargs):
 259                 '''
 260                 '''
 261                 pass
 262         def close(self, stream_type):
 263                 '''
 264                 '''
 265                 pass
 266         def insert(self, stream_type, *pargs, **nargs):
 267                 '''
 268                 '''
 269                 pass
 270         # default processors...
 271         ##!!!
 272
 273
 274
 275 #-----------------------------------------------------------------------
 276 #--------------------------------------------------DataToStreamReader---
 277 class DataToStreamReader(object):
 278         '''
 279         this is a generic stream constructor class (data -> stream).
 280         '''
 281         def __call__(self, *pargs, **nargs):
 282                 '''
 283                 this will initiate the read process and start writing to the target stream.
 284
 285                 '''
 286                 if not hasattr(self, 'target_stream'):
 287                         raise StreamError, 'stream reader not chained to a reciving stream.'
 288         def chain(self, stream):
 289                 '''
 290                 '''
 291                 self.target_stream = stream
 292         def unchain(self):
 293                 '''
 294                 '''
 295                 del self.target_stream
 296
 297
 298 #--------------------------------------------------StreamToDataWriter---
 299 class StreamToDataWriter(ReferenceStream):
 300         '''
 301         this is a generic stream writer class (stream -> data).
 302         '''
 303
 304         # this is the generic stream processor...
 305         dispatch = StreamProcessorDispatch()
 306
 307         def __init__(self):
 308                 '''
 309                 '''
 310                 # TODO generate a better stream_id
 311                 super(StreamWriter, self).__init__(self, parent=None, sream_id=id(self))
 312
 313
 314
 315 #=======================================================================
 316 #                                            vim:set ts=4 sw=4 nowrap :