Completed
Push — develop ( 06a9d5...28049f )
by Kale
01:02
created

Field.in_dump()   A

Complexity

Conditions 1

Size

Total Lines 3

Duplication

Lines 0
Ratio 0 %

Importance

Changes 3
Bugs 0 Features 1
Metric Value
cc 1
c 3
b 0
f 1
dl 0
loc 3
rs 10
1
# -*- coding: utf-8 -*-
2
"""
3
========
4
Tutorial
5
========
6
7
Chapter 1: Entity and Field Basics
8
----------------------------------
9
10
    >>> class Color(Enum):
11
    ...     blue = 0
12
    ...     black = 1
13
    ...     red = 2
14
    >>> class Car(Entity):
15
    ...     weight = NumberField(required=False)
16
    ...     wheels = IntField(default=4, validation=lambda x: 3 <= x <= 4)
17
    ...     color = EnumField(Color)
18
19
    >>> # create a new car object
20
    >>> car = Car(color=Color.blue, weight=4242.46)
21
    >>> car
22
    Car(weight=4242.46, color=0)
23
24
    >>> # it has 4 wheels, all by default
25
    >>> car.wheels
26
    4
27
28
    >>> # but a car can't have 5 wheels!
29
    >>> #  the `validation=` field is a simple callable that returns a
30
    >>> #  boolean based on validity
31
    >>> car.wheels = 5
32
    Traceback (most recent call last):
33
    ValidationError: Invalid value 5 for wheels
34
35
    >>> # we can call .dump() on car, and just get back a standard
36
    >>> #  python dict actually, it's an ordereddict to match attribute
37
    >>> #  declaration order
38
    >>> type(car.dump())
39
    <class '...OrderedDict'>
40
    >>> car.dump()
41
    OrderedDict([('weight', 4242.46), ('wheels', 4), ('color', 0)])
42
43
    >>> # and json too (note the order!)
44
    >>> car.json()
45
    '{"weight": 4242.46, "wheels": 4, "color": 0}'
46
47
    >>> # green cars aren't allowed
48
    >>> car.color = "green"
49
    Traceback (most recent call last):
50
    ValidationError: 'green' is not a valid Color
51
52
    >>> # but black cars are!
53
    >>> car.color = "black"
54
    >>> car.color
55
    <Color.black: 1>
56
57
    >>> # car.color really is an enum, promise
58
    >>> type(car.color)
59
    <enum 'Color'>
60
61
    >>> # enum assignment can be with any of (and preferentially)
62
    >>> #   (1) an enum literal,
63
    >>> #   (2) a valid enum value, or
64
    >>> #   (3) a valid enum name
65
    >>> car.color = Color.blue; car.color.value
66
    0
67
    >>> car.color = 1; car.color.name
68
    'black'
69
70
    >>> # let's do a round-trip marshalling of this thing
71
    >>> same_car = Car.from_json(car.json())  # or equally Car.from_json(json.dumps(car.dump()))
72
    >>> same_car == car
73
    True
74
75
    >>> # actually, they're two different instances
76
    >>> same_car is not car
77
    True
78
79
    >>> # this works too
80
    >>> cloned_car = Car(**car.dump())
81
    >>> cloned_car == car
82
    True
83
84
    >>> # while we're at it, these are all equivalent too
85
    >>> car == Car.from_objects(car)
86
    True
87
    >>> car == Car.from_objects({"weight": 4242.46, "wheels": 4, "color": 1})
88
    True
89
    >>> car == Car.from_json('{"weight": 4242.46, "color": 1}')
90
    True
91
92
    >>> # .from_objects() even lets you stack and combine objects
93
    >>> class DumbClass:
94
    ...     color = 0
95
    ...     wheels = 3
96
    >>> Car.from_objects(DumbClass(), dict(weight=2222, color=1))
97
    Car(weight=2222, wheels=3, color=0)
98
    >>> # and also pass kwargs that override properties pulled
99
    >>> #  off any objects
100
    >>> Car.from_objects(DumbClass(), {'weight': 2222, 'color': 1}, color=2, weight=33)
101
    Car(weight=33, wheels=3, color=2)
102
103
104
Chapter 2: Entity and Field Composition
105
---------------------------------------
106
107
    >>> # now let's get fancy
108
    >>> # a ComposableField "nests" another valid Entity
109
    >>> # a ListField's first argument is a "generic" type,
110
    >>> #   which can be a valid Entity, any python primitive
111
    >>> #   type, or a list of Entities/types
112
    >>> class Fleet(Entity):
113
    ...     boss_car = ComposableField(Car)
114
    ...     cars = ListField(Car)
115
116
    >>> # here's our fleet of company cars
117
    >>> company_fleet = Fleet(boss_car=Car(color='red'), cars=[car, same_car, cloned_car])
118
    >>> company_fleet.pretty_json()  #doctest: +SKIP
119
    {
120
      "boss_car": {
121
        "wheels": 4
122
        "color": 2,
123
      },
124
      "cars": [
125
        {
126
          "weight": 4242.46,
127
          "wheels": 4
128
          "color": 1,
129
        },
130
        {
131
          "weight": 4242.46,
132
          "wheels": 4
133
          "color": 1,
134
        },
135
        {
136
          "weight": 4242.46,
137
          "wheels": 4
138
          "color": 1,
139
        }
140
      ]
141
    }
142
143
    >>> # the boss' car is red of course (and it's still an Enum)
144
    >>> company_fleet.boss_car.color.name
145
    'red'
146
147
    >>> # and there are three cars left for the employees
148
    >>> len(company_fleet.cars)
149
    3
150
151
152
Chapter 3: Immutability
153
-----------------------
154
155
    >>> class ImmutableCar(ImmutableEntity):
156
    ...     wheels = IntField(default=4, validation=lambda x: 3 <= x <= 4)
157
    ...     color = EnumField(Color)
158
    >>> icar = ImmutableCar.from_objects({'wheels': 3, 'color': 'blue'})
159
    >>> icar
160
    ImmutableCar(wheels=3, color=0)
161
162
    >>> icar.wheels = 4
163
    Traceback (most recent call last):
164
    AttributeError: Assignment not allowed. ImmutableCar is immutable.
165
166
    >>> class FixedWheelCar(Entity):
167
    ...     wheels = IntField(default=4, immutable=True)
168
    ...     color = EnumField(Color)
169
    >>> fwcar = FixedWheelCar.from_objects(icar)
170
    >>> fwcar.json()
171
    '{"wheels": 3, "color": 0}'
172
173
    >>> # repainting the car is easy
174
    >>> fwcar.color = Color.red
175
    >>> fwcar.color.name
176
    'red'
177
178
    >>> # can't really change the number of wheels though
179
    >>> fwcar.wheels = 18
180
    Traceback (most recent call last):
181
    AttributeError: The wheels field is immutable.
182
183
184
Chapter X: The del and null Weeds
185
---------------------------------
186
187
    >>> old_date = lambda: dateparse('1982-02-17')
188
    >>> class CarBattery(Entity):
189
    ...     # NOTE: default value can be a callable!
190
    ...     first_charge = DateField(required=False)  # default=None, nullable=False
191
    ...     latest_charge = DateField(default=old_date, nullable=True)  # required=True
192
    ...     expiration = DateField(default=old_date, required=False, nullable=False)
193
194
    >>> # starting point
195
    >>> battery = CarBattery()
196
    >>> battery
197
    CarBattery()
198
    >>> battery.json()
199
    '{"latest_charge": "1982-02-17T00:00:00", "expiration": "1982-02-17T00:00:00"}'
200
201
    >>> # first_charge is not assigned a default value. Once one is assigned, it can be deleted,
202
    >>> #   but it can't be made null.
203
    >>> battery.first_charge = dateparse('2016-03-23')
204
    >>> battery
205
    CarBattery(first_charge=datetime.datetime(2016, 3, 23, 0, 0))
206
    >>> battery.first_charge = None
207
    Traceback (most recent call last):
208
    ValidationError: Value for first_charge not given or invalid.
209
    >>> del battery.first_charge
210
    >>> battery
211
    CarBattery()
212
213
    >>> # latest_charge can be null, but it can't be deleted. The default value is a callable.
214
    >>> del battery.latest_charge
215
    Traceback (most recent call last):
216
    AttributeError: The latest_charge field is required and cannot be deleted.
217
    >>> battery.latest_charge = None
218
    >>> battery.json()
219
    '{"latest_charge": null, "expiration": "1982-02-17T00:00:00"}'
220
221
    >>> # expiration is assigned by default, can't be made null, but can be deleted.
222
    >>> battery.expiration
223
    datetime.datetime(1982, 2, 17, 0, 0)
224
    >>> battery.expiration = None
225
    Traceback (most recent call last):
226
    ValidationError: Value for expiration not given or invalid.
227
    >>> del battery.expiration
228
    >>> battery.json()
229
    '{"latest_charge": null}'
230
231
232
"""
233
from __future__ import absolute_import, division, print_function
234
235
from functools import reduce
236
237
from collections import Iterable
238
from datetime import datetime
239
from enum import Enum
240
from json import loads as json_loads, dumps as json_dumps
241
from logging import getLogger
242
243
from ._vendor.dateutil.parser import parse as dateparse
244
from .compat import (with_metaclass, string_types, text_type, integer_types, iteritems,
245
                     itervalues, odict)
246
from .collection import AttrDict
247
from .exceptions import ValidationError, Raise
248
from .ish import find_or_none
249
from .logz import DumpEncoder
250
from .type_coercion import maybecall
251
252
log = getLogger(__name__)
253
254
__all__ = [
255
    "Entity", "ImmutableEntity", "Field",
256
    "BooleanField", "BoolField", "IntegerField", "IntField",
257
    "NumberField", "StringField", "DateField",
258
    "EnumField", "ListField", "MapField", "ComposableField",
259
]
260
261
KEY_OVERRIDES_MAP = "__key_overrides__"
262
263
264
NOTES = """
265
This module provides facilities for serializable, validatable, and type-enforcing
266
domain objects.
267
268
This module has many of the same motivations as the python Marshmallow package.
269
<http://marshmallow.readthedocs.org/en/latest/why.html>
270
271
Also need to be explicit in explaining what Marshmallow doesn't do, and why this module is needed.
272
  - Provides type safety like an ORM. And like an ORM, all classes subclass Entity.
273
  - Provides BUILT IN serialization and deserialization.  Marhmallow requires a lot of code
274
    duplication.
275
276
This module gives us:
277
  - type safety
278
  - custom field validation
279
  - serialization and deserialization
280
  - rock solid foundational domain objects
281
282
283
Current deficiencies to schematics:
284
  - no get_mock_object method
285
  - no context-dependent serialization or MultilingualStringType
286
  - name = StringType(serialized_name='person_name', alternate_names=['human_name'])
287
  - name = StringType(serialize_when_none=False)
288
  - more flexible validation error messages
289
  - field validation can depend on other fields
290
  - 'roles' containing blacklists for .dump() and .json()
291
    __roles__ = {
292
        EntityRole.registered_name: Blacklist('field1', 'field2'),
293
        EntityRole.another_registered_name: Whitelist('field3', 'field4'),
294
    }
295
296
297
TODO:
298
  - alternate field names
299
  - add dump_if_null field option
300
  - add help/description parameter to Field
301
302
303
Optional Field Properties:
304
  - validation = None
305
  - default = None
306
  - required = True
307
  - in_dump = True
308
  - nullable = False
309
310
Behaviors:
311
  - Nullable is a "hard" setting, in that the value is either always or never allowed to be None.
312
  - What happens then if required=False and nullable=False?
313
      - The object can be init'd without a value (though not with a None value).
314
        getattr throws AttributeError
315
      - Any assignment must be not None.
316
317
318
  - Setting a value to None doesn't "unset" a value.  (That's what del is for.)  And you can't
319
    del a value if required=True, nullable=False, default=None.
320
321
  - If a field is not required, del does *not* "unmask" the default value.  Instead, del
322
    removes the value from the object entirely.  To get back the default value, need to recreate
323
    the object.  Entity.from_objects(old_object)
324
325
326
  - Disabling in_dump is a "hard" setting, in that with it disabled the field will never get
327
    dumped.  With it enabled, the field may or may not be dumped depending on its value and other
328
    settings.
329
330
  - Required is a "hard" setting, in that if True, a valid value or default must be provided. None
331
    is only a valid value or default if nullable is True.
332
333
  - In general, nullable means that None is a valid value.
334
    - getattr returns None instead of raising Attribute error
335
    - If in_dump, field is given with null value.
336
    - If default is not None, assigning None clears a previous assignment. Future getattrs return
337
      the default value.
338
    - What does nullable mean with default=None and required=True? Does instantiation raise
339
      an error if assignment not made on init? Can IntField(nullable=True) be init'd?
340
341
  - If required=False and nullable=False, field will only be in dump if field!=None.
342
    Also, getattr raises AttributeError.
343
  - If required=False and nullable=True, field will be in dump if field==None.
344
345
  - If in_dump is True, does default value get dumped:
346
    - if no assignment, default exists
347
    - if nullable, and assigned None
348
  - How does optional validation work with nullable and assigning None?
349
  - When does gettattr throw AttributeError, and when does it return None?
350
351
352
353
"""
354
355
356
class Field(object):
357
    """
358
    Fields are doing something very similar to boxing and unboxing
359
    of c#/java primitives.  __set__ should take a "primitive" or "raw" value and create a "boxed"
360
    or "programatically useable" value of it.  While __get__ should return the boxed value,
361
    dump in turn should unbox the value into a primitive or raw value.
362
363
    Arguments:
364
        types_ (primitive literal or type or sequence of types):
365
        default (any, callable, optional):  If default is callable, it's guaranteed to return a
366
            valid value at the time of Entity creation.
367
        required (boolean, optional):
368
        validation (callable, optional):
369
        dump (boolean, optional):
370
    """
371
372
    # Used to track order of field declarations. Supporting python 2.7, so can't rely
373
    #   on __prepare__.  Strategy lifted from http://stackoverflow.com/a/4460034/2127762
374
    _order_helper = 0
375
376
    def __init__(self, default=None, required=True, validation=None,
377
                 in_dump=True, nullable=False, immutable=False):
378
        self._default = default if callable(default) else self.box(None, default)
379
        self._required = required
380
        self._validation = validation
381
        self._in_dump = in_dump
382
        self._nullable = nullable
383
        self._immutable = immutable
384
        if default is not None:
385
            self.validate(None, self.box(None, maybecall(default)))
386
387
        self._order_helper = Field._order_helper
388
        Field._order_helper += 1
389
390
    @property
391
    def name(self):
392
        try:
393
            return self._name
394
        except AttributeError:
395
            log.error("The name attribute has not been set for this field. "
396
                      "Call set_name at class creation time.")
397
            raise
398
399
    def set_name(self, name):
400
        self._name = name
401
        return self
402
403
    def __get__(self, instance, instance_type):
404
        try:
405
            if instance is None:  # if calling from the class object
406
                val = getattr(instance_type, KEY_OVERRIDES_MAP)[self.name]
407
            else:
408
                val = instance.__dict__[self.name]
409
        except AttributeError:
410
            log.error("The name attribute has not been set for this field.")
411
            raise AttributeError("The name attribute has not been set for this field.")
412
        except KeyError:
413
            if self.default is not None:
414
                val = maybecall(self.default)  # default *can* be a callable
415
            elif self._nullable:
416
                return None
417
            else:
418
                raise AttributeError("A value for {0} has not been set".format(self.name))
419
        if val is None and not self.nullable:
420
            # means the "tricky edge case" was activated in __delete__
421
            raise AttributeError("The {0} field has been deleted.".format(self.name))
422
        return self.unbox(instance, instance_type, val)
423
424
    def __set__(self, instance, val):
425
        if self.immutable and instance._initd:
426
            raise AttributeError("The {0} field is immutable.".format(self.name))
427
        # validate will raise an exception if invalid
428
        # validate will return False if the value should be removed
429
        instance.__dict__[self.name] = self.validate(instance, self.box(instance, val))
430
431
    def __delete__(self, instance):
432
        if self.immutable and instance._initd:
433
            raise AttributeError("The {0} field is immutable.".format(self.name))
434
        elif self.required:
435
            raise AttributeError("The {0} field is required and cannot be deleted."
436
                                 .format(self.name))
437
        elif not self.nullable:
438
            # tricky edge case
439
            # given a field Field(default='some value', required=False, nullable=False)
440
            # works together with Entity.dump() logic for selecting fields to include in dump
441
            # `if value is not None or field.nullable`
442
            instance.__dict__[self.name] = None
443
        else:
444
            instance.__dict__.pop(self.name, None)
445
446
    def box(self, instance, val):
447
        return val
448
449
    def unbox(self, instance, instance_type, val):
450
        return val
451
452
    def dump(self, val):
453
        return val
454
455
    def validate(self, instance, val):
456
        """
457
458
        Returns:
459
            True: if val is valid
460
461
        Raises:
462
            ValidationError
463
        """
464
        # note here calling, but not assigning; could lead to unexpected behavior
465
        if isinstance(val, self._type) and (self._validation is None or self._validation(val)):
466
                return val
467
        elif val is None and self.nullable:
468
            return val
469
        else:
470
            raise ValidationError(getattr(self, 'name', 'undefined name'), val)
471
472
    @property
473
    def required(self):
474
        return self._required
475
476
    @property
477
    def type(self):
478
        return self._type
479
480
    @property
481
    def default(self):
482
        return self._default
483
484
    @property
485
    def in_dump(self):
486
        return self._in_dump
487
488
    @property
489
    def nullable(self):
490
        return self.is_nullable
491
492
    @property
493
    def is_nullable(self):
494
        return self._nullable
495
496
    @property
497
    def immutable(self):
498
        return self._immutable
499
500
501
class BooleanField(Field):
502
    _type = bool
503
504
    def box(self, instance, val):
505
        return None if val is None else bool(val)
506
507
BoolField = BooleanField
508
509
510
class IntegerField(Field):
511
    _type = integer_types
512
513
IntField = IntegerField
514
515
516
class NumberField(Field):
517
    _type = integer_types + (float, complex)
518
519
520
class StringField(Field):
521
    _type = string_types
522
523
    def box(self, instance, val):
524
        return text_type(val) if isinstance(val, NumberField._type) else val
525
526
527
class DateField(Field):
528
    _type = datetime
529
530
    def box(self, instance, val):
531
        try:
532
            return dateparse(val) if isinstance(val, string_types) else val
533
        except ValueError as e:
534
            raise ValidationError(val, msg=e)
535
536
    def dump(self, val):
537
        return None if val is None else val.isoformat()
538
539
540
class EnumField(Field):
541
542
    def __init__(self, enum_class, default=None, required=True, validation=None,
543
                 in_dump=True, nullable=False, immutable=False):
544
        if not issubclass(enum_class, Enum):
545
            raise ValidationError(None, msg="enum_class must be an instance of Enum")
546
        self._type = enum_class
547
        super(EnumField, self).__init__(default, required, validation,
548
                                        in_dump, nullable, immutable)
549
550
    def box(self, instance, val):
551
        if val is None:
552
            # let the required/nullable logic handle validation for this case
553
            return None
554
        try:
555
            # try to box using val as an Enum name
556
            return val if isinstance(val, self._type) else self._type(val)
557
        except ValueError as e1:
558
            try:
559
                # try to box using val as an Enum value
560
                return self._type[val]
561
            except KeyError:
562
                raise ValidationError(val, msg=e1)
563
564
    def dump(self, val):
565
        return None if val is None else val.value
566
567
568
class ListField(Field):
569
    _type = tuple
570
571
    def __init__(self, element_type, default=None, required=True, validation=None,
572
                 in_dump=True, nullable=False, immutable=False):
573
        self._element_type = element_type
574
        super(ListField, self).__init__(default, required, validation,
575
                                        in_dump, nullable, immutable)
576
577
    def box(self, instance, val):
578
        if val is None:
579
            return None
580
        elif isinstance(val, string_types):
581
            raise ValidationError("Attempted to assign a string to ListField {0}"
582
                                  "".format(self.name))
583
        elif isinstance(val, Iterable):
584
            et = self._element_type
585
            if isinstance(et, type) and issubclass(et, Entity):
586
                return self._type(v if isinstance(v, et) else et(**v) for v in val)
587
            else:
588
                return self._type(val)
589
        else:
590
            raise ValidationError(val, msg="Cannot assign a non-iterable value to "
591
                                           "{0}".format(self.name))
592
593
    def unbox(self, instance, instance_type, val):
594
        return self._type() if val is None and not self.nullable else val
595
596
    def dump(self, val):
597
        if isinstance(self._element_type, type) and issubclass(self._element_type, Entity):
598
            return self._type(v.dump() for v in val)
599
        else:
600
            return val
601
602
    def validate(self, instance, val):
603
        if val is None:
604
            if not self.nullable:
605
                raise ValidationError(self.name, val)
606
            return None
607
        else:
608
            val = super(ListField, self).validate(instance, val)
609
            et = self._element_type
610
            self._type(Raise(ValidationError(self.name, el, et)) for el in val
611
                       if not isinstance(el, et))
612
            return val
613
614
615
class MutableListField(ListField):
616
    _type = list
617
618
619
class MapField(Field):
620
    _type = dict
621
    __eq__ = dict.__eq__
622
    __hash__ = dict.__hash__
623
624
625
class ComposableField(Field):
626
627
    def __init__(self, field_class, default=None, required=True, validation=None,
628
                 in_dump=True, nullable=False, immutable=False):
629
        self._type = field_class
630
        super(ComposableField, self).__init__(default, required, validation,
631
                                              in_dump, nullable, immutable)
632
633
    def box(self, instance, val):
634
        if val is None:
635
            return None
636
        if isinstance(val, self._type):
637
            return val
638
        else:
639
            # assuming val is a dict now
640
            try:
641
                # if there is a key named 'self', have to rename it
642
                val['slf'] = val.pop('self')
643
            except KeyError:
644
                pass  # no key of 'self', so no worries
645
            return val if isinstance(val, self._type) else self._type(**val)
646
647
    def dump(self, val):
648
        return None if val is None else val.dump()
649
650
651
class EntityType(type):
652
653
    @staticmethod
654
    def __get_entity_subclasses(bases):
655
        try:
656
            return [base for base in bases if issubclass(base, Entity) and base is not Entity]
657
        except NameError:
658
            # NameError: global name 'Entity' is not defined
659
            return ()
660
661
    def __new__(mcs, name, bases, dct):
662
        # if we're about to mask a field that's already been created with something that's
663
        #  not a field, then assign it to an alternate variable name
664
        non_field_keys = (key for key, value in iteritems(dct)
665
                          if not isinstance(value, Field) and not key.startswith('__'))
666
        entity_subclasses = EntityType.__get_entity_subclasses(bases)
667
        if entity_subclasses:
668
            keys_to_override = [key for key in non_field_keys
669
                                if any(isinstance(base.__dict__.get(key), Field)
670
                                       for base in entity_subclasses)]
671
            dct[KEY_OVERRIDES_MAP] = dict((key, dct.pop(key)) for key in keys_to_override)
672
        else:
673
            dct[KEY_OVERRIDES_MAP] = dict()
674
675
        return super(EntityType, mcs).__new__(mcs, name, bases, dct)
676
677
    def __init__(cls, name, bases, attr):
678
        super(EntityType, cls).__init__(name, bases, attr)
679
        cls.__fields__ = odict(cls.__fields__) if hasattr(cls, '__fields__') else odict()
680
        cls.__fields__.update(sorted(((name, field.set_name(name))
681
                                      for name, field in iteritems(cls.__dict__)
682
                                      if isinstance(field, Field)),
683
                                     key=lambda item: item[1]._order_helper))
684
        if hasattr(cls, '__register__'):
685
            cls.__register__()
686
687
    def __call__(cls, *args, **kwargs):
688
        instance = super(EntityType, cls).__call__(*args, **kwargs)
689
        setattr(instance, '_{0}__initd'.format(cls.__name__), True)
690
        return instance
691
692
    @property
693
    def fields(cls):
694
        return cls.__fields__.keys()
695
696
697
@with_metaclass(EntityType)
698
class Entity(object):
699
    __fields__ = odict()
700
701
    def __init__(self, **kwargs):
702
        for key, field in iteritems(self.__fields__):
703
            try:
704
                setattr(self, key, kwargs[key])
705
            except KeyError:
706
                # handle the case of fields inherited from subclass but overrode on class object
707
                if key in getattr(self, KEY_OVERRIDES_MAP):
708
                    setattr(self, key, getattr(self, KEY_OVERRIDES_MAP)[key])
709
                elif field.required and field.default is None:
710
                    raise ValidationError(key, msg="{0} requires a {1} field. Instantiated with "
711
                                                   "{2}".format(self.__class__.__name__,
712
                                                                key, kwargs))
713
            except ValidationError:
714
                if kwargs[key] is not None or field.required:
715
                    raise
716
        self.validate()
717
718
    @classmethod
719
    def from_objects(cls, *objects, **override_fields):
720
        init_vars = dict()
721
        search_maps = tuple(AttrDict(o) if isinstance(o, dict) else o
722
                            for o in ((override_fields,) + objects))
723
        for key in cls.__fields__:
724
            init_vars[key] = find_or_none(key, search_maps)
725
        return cls(**init_vars)
726
727
    @classmethod
728
    def from_json(cls, json_str):
729
        return cls(**json_loads(json_str))
730
731
    @classmethod
732
    def load(cls, data_dict):
733
        return cls(**data_dict)
734
735
    def validate(self):
736
        # TODO: here, validate should only have to determine if the required keys are set
737
        try:
738
            reduce(lambda _, name: getattr(self, name),
739
                   (name for name, field in iteritems(self.__fields__) if field.required)
740
                   )
741
        except AttributeError as e:
742
            raise ValidationError(None, msg=e)
743
744
    def __repr__(self):
745
        def _valid(key):
746
            if key.startswith('_'):
747
                return False
748
            try:
749
                getattr(self, key)
750
                return True
751
            except AttributeError:
752
                return False
753
754
        def _val(key):
755
            val = getattr(self, key)
756
            return repr(val.value) if isinstance(val, Enum) else repr(val)
757
758
        def _sort_helper(key):
759
            field = self.__fields__.get(key)
760
            return field._order_helper if field is not None else -1
761
762
        kwarg_str = ", ".join("{0}={1}".format(key, _val(key))
763
                              for key in sorted(self.__dict__, key=_sort_helper)
764
                              if _valid(key))
765
        return "{0}({1})".format(self.__class__.__name__, kwarg_str)
766
767
    @classmethod
768
    def __register__(cls):
769
        pass
770
771
    def json(self, indent=None, separators=None, **kwargs):
772
        return json_dumps(self, indent=indent, separators=separators, cls=DumpEncoder, **kwargs)
773
774
    def pretty_json(self, indent=2, separators=(',', ': '), **kwargs):
775
        return self.json(indent=indent, separators=separators, **kwargs)
776
777
    def dump(self):
778
        return odict((field.name, field.dump(value))
779
                     for field, value in ((field, getattr(self, field.name, None))
780
                                          for field in self.__dump_fields())
781
                     if value is not None or field.nullable)
782
783
    @classmethod
784
    def __dump_fields(cls):
785
        if '__dump_fields_cache' not in cls.__dict__:
786
            cls.__dump_fields_cache = tuple(field for field in itervalues(cls.__fields__)
787
                                            if field.in_dump)
788
        return cls.__dump_fields_cache
789
790
    def __eq__(self, other):
791
        if self.__class__ != other.__class__:
792
            return False
793
        rando_default = 19274656290  # need an arbitrary but definite value if field does not exist
794
        return all(getattr(self, field, rando_default) == getattr(other, field, rando_default)
795
                   for field in self.__fields__)
796
797
    def __hash__(self):
798
        return sum(hash(getattr(self, field, None)) for field in self.__fields__)
799
800
    @property
801
    def _initd(self):
802
        return getattr(self, '_{0}__initd'.format(self.__class__.__name__), None)
803
804
805
class ImmutableEntity(Entity):
806
807
    def __setattr__(self, attribute, value):
808
        if self._initd:
809
            raise AttributeError("Assignment not allowed. {0} is immutable."
810
                                 .format(self.__class__.__name__))
811
        super(ImmutableEntity, self).__setattr__(attribute, value)
812
813
    def __delattr__(self, item):
814
        if self._initd:
815
            raise AttributeError("Deletion not allowed. {0} is immutable."
816
                                 .format(self.__class__.__name__))
817
        super(ImmutableEntity, self).__delattr__(item)
818