Typed, immutable, multi-field object w/sequence and mapping interfaces
Usage:
class myRecord(struct):
__fields__ = 'first', 'second', 'third'
# the following will now all produce identical objects
# and they'll all compare equal to the tuple (1,2,3):
r = myRecord([1,2,3])
r = myRecord(first=1, second=2, third=3)
r = myRecord({'first':1, 'second':2, 'third':3})
r = myRecord.fromMapping({'first':1, 'second':2, 'third':3})
r = myRecord.extractFromMapping(
{'first':1, 'second':2, 'third':3, 'blue':'lagoon'}
)
r = myRecord.fromMapping( myRecord([1,2,3]) )
# the following will all print the same thing for any 'r' above:
print r
print (r.first, r.second, r.third)
print (r[0], r[1], r[2])
print (r['first'], r['second'], r['third'])
If you want to define your own properties in place of the automagically
generated ones, just include them in your class. Your defined properties
will be inherited by subclasses, as long as the field of that name is at
the same position in the record. If a subclass changes the field order,
the inherited property will be overridden by a generated one, unless the
subclass supplies a replacement as part of the class dictionary.
Note: if you define custom properties, they only determine the attributes
of the instance. All other behaviors including string representation,
iteration, item retrieval, etc., will be unaffected. It's probably best
to redefine the fromArgs classmethod to manage the initial construction
of the fields instead.
|
Methods
|
|
|
|
|
|
__contains__
|
__contains__ ( self, key )
|
|
|
__getitem__
|
__getitem__ ( self, key )
|
|
|
__new__
|
__new__ (
klass,
*__args,
*__kw,
)
|
|
|
__reduce__
|
__reduce__ ( self )
|
|
|
copy
|
copy ( self )
|
|
|
extractFromMapping
|
extractFromMapping ( klass, arg )
Fast extraction from a mapping; ignores undefined fields
|
|
|
fromArgs
|
fromArgs (
klass,
*__args,
*__kw,
)
Create from arguments
By default, this classmethod is where all the other creation
methods "call down" to, so that you can do any validation or
conversions. The default implementation just calls
tuple.__new__ on the *__args tuple. You should override
this with a classmethod that takes the arguments you want, in
the same order as your __fields__ definition, supplying
defaults if desired.
The default version of this method will accept input sequences
with more items than there are fields to fill. The extra data
isn't lost, it's just unavailable except via sequence methods.
If you want different behavior, such as truncating the sequence
or raising an exception, you'll need to override this method.
|
Exceptions
|
|
TypeError( "Invalid keyword arguments for " + klass.__name__ )
|
|
|
|
fromMapping
|
fromMapping ( klass, arg )
Create a struct from a mapping
This method checks that the mapping doesn't contain any field names
the struct won't accept. This prevents silent unintentional loss
of information during conversions. If you want extra data in the
mapping to be ignored, you should use extractFromMapping instead.
Note that although this method will raise ValueError for fields
that would be dropped, it uses a default value of None for any
fields which are missing from the mapping. If you want a stricter
policy, you'll need to override this.
|
Exceptions
|
|
ValueError(( "Mapping contains keys which are not fields of %s" % klass.__name__ ), arg )
|
|
|
|
fromOther
|
fromOther ( klass, arg )
Create from a single argument
You can define a classmethod here, to be used in place of
tuple.__new__ when the struct is being created from a single
argument that is not a dictionary, keywords, or a string.
The default simply hands the argument through to the
fromArgs() method, where it will be treated as being the
first field of the struct.
|
|
|
fromString
|
fromString ( klass, arg )
Override this classmethod to enable parsing from a string
|
|
|
get
|
get (
self,
key,
default=None,
)
|
|
|
items
|
items ( self )
|
|
|
iteritems
|
iteritems ( self )
|
|
|
iterkeys
|
iterkeys ( self )
|
|
|
itervalues
|
itervalues ( self )
|
|
|
keys
|
keys ( self )
|
|
|
values
|
values ( self )
|
|