Completed
Push — develop ( 5661c9...75e288 )
by Kale
59s
created

auxlib.Entity.validate()   A

Complexity

Conditions 4

Size

Total Lines 6

Duplication

Lines 0
Ratio 0 %
Metric Value
cc 4
dl 0
loc 6
rs 9.2
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.42)
21
    >>> car
22
    Car(weight=4242.42, 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 'collections.OrderedDict'>
40
    >>> car.dump()
41
    OrderedDict([('weight', 4242.42), ('wheels', 4), ('color', 0)])
42
43
    >>> # and json too (note the order!)
44
    >>> car.json()
45
    '{"weight": 4242.42, "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.42, "wheels": 4, "color": 1})
88
    True
89
    >>> car == Car.from_json('{"weight": 4242.42, "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.42,
127
          "wheels": 4
128
          "color": 1,
129
        },
130
        {
131
          "weight": 4242.42,
132
          "wheels": 4
133
          "color": 1,
134
        },
135
        {
136
          "weight": 4242.42,
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
    >>> # because we can
152
    >>> sum(c.weight for c in company_fleet.cars)
153
    12727.26
154
155
156
Chapter 3: Immutability
157
-----------------------
158
159
    >>> class ImmutableCar(ImmutableEntity):
160
    ...     wheels = IntField(default=4, validation=lambda x: 3 <= x <= 4)
161
    ...     color = EnumField(Color)
162
    >>> icar = ImmutableCar.from_objects({'wheels': 3, 'color': 'blue'})
163
    >>> icar
164
    ImmutableCar(wheels=3, color=0)
165
166
    >>> icar.wheels = 4
167
    Traceback (most recent call last):
168
    AttributeError: Assignment not allowed. ImmutableCar is immutable.
169
170
    >>> class FixedWheelCar(Entity):
171
    ...     wheels = IntField(default=4, immutable=True)
172
    ...     color = EnumField(Color)
173
    >>> fwcar = FixedWheelCar.from_objects(icar)
174
    >>> fwcar.json()
175
    '{"wheels": 3, "color": 0}'
176
177
    >>> # repainting the car is easy
178
    >>> fwcar.color = Color.red
179
    >>> fwcar.color.name
180
    'red'
181
182
    >>> # can't really change the number of wheels though
183
    >>> fwcar.wheels = 18
184
    Traceback (most recent call last):
185
    AttributeError: The wheels field is immutable.
186
187
188
Chapter X: The del and null Weeds
189
---------------------------------
190
191
    >>> old_date = lambda: dateparse('1982-02-17')
192
    >>> class CarBattery(Entity):
193
    ...     # NOTE: default value can be a callable!
194
    ...     first_charge = DateField(required=False)  # default=None, nullable=False
195
    ...     latest_charge = DateField(default=old_date, nullable=True)  # required=True
196
    ...     expiration = DateField(default=old_date, required=False, nullable=False)
197
198
    >>> # starting point
199
    >>> battery = CarBattery()
200
    >>> battery
201
    CarBattery()
202
    >>> battery.json()
203
    '{"latest_charge": "1982-02-17T00:00:00", "expiration": "1982-02-17T00:00:00"}'
204
205
    >>> # first_charge is not assigned a default value. Once one is assigned, it can be deleted,
206
    >>> #   but it can't be made null.
207
    >>> battery.first_charge = dateparse('2016-03-23')
208
    >>> battery
209
    CarBattery(first_charge=datetime.datetime(2016, 3, 23, 0, 0))
210
    >>> battery.first_charge = None
211
    Traceback (most recent call last):
212
    ValidationError: Value for first_charge not given or invalid.
213
    >>> del battery.first_charge
214
    >>> battery
215
    CarBattery()
216
217
    >>> # latest_charge can be null, but it can't be deleted. The default value is a callable.
218
    >>> del battery.latest_charge
219
    Traceback (most recent call last):
220
    AttributeError: The latest_charge field is required and cannot be deleted.
221
    >>> battery.latest_charge = None
222
    >>> battery.json()
223
    '{"latest_charge": null, "expiration": "1982-02-17T00:00:00"}'
224
225
    >>> # expiration is assigned by default, can't be made null, but can be deleted.
226
    >>> battery.expiration
227
    datetime.datetime(1982, 2, 17, 0, 0)
228
    >>> battery.expiration = None
229
    Traceback (most recent call last):
230
    ValidationError: Value for expiration not given or invalid.
231
    >>> del battery.expiration
232
    >>> battery.json()
233
    '{"latest_charge": null}'
234
235
236
"""
237
from __future__ import absolute_import, division, print_function
238
239
from collections import Iterable, OrderedDict as odict
240
from datetime import datetime
241
from enum import Enum
242
from json import loads as json_loads, dumps as json_dumps
243
from logging import getLogger
244
245
from ._vendor.dateutil.parser import parse as dateparse
246
from ._vendor.five import with_metaclass, items, values
247
from ._vendor.six import string_types, text_type, integer_types
248
from .collection import AttrDict
249
from .exceptions import ValidationError, Raise
250
from .ish import find_or_none
251
from .logz import DumpEncoder
252
from .type_coercion import maybecall
253
254
log = getLogger(__name__)
255
256
__all__ = [
257
    "Entity", "ImmutableEntity", "Field",
258
    "BooleanField", "BoolField", "IntegerField", "IntField",
259
    "NumberField", "StringField", "DateField",
260
    "EnumField", "ListField", "MapField", "ComposableField",
261
]
262
263
KEY_OVERRIDES_MAP = "__key_overrides__"
264
265
266
NOTES = """
267
This module provides facilities for serializable, validatable, and type-enforcing
268
domain objects.
269
270
This module has many of the same motivations as the python Marshmallow package.
271
<http://marshmallow.readthedocs.org/en/latest/why.html>
272
273
Also need to be explicit in explaining what Marshmallow doesn't do, and why this module is needed.
274
  - Provides type safety like an ORM. And like an ORM, all classes subclass Entity.
275
  - Provides BUILT IN serialization and deserialization.  Marhmallow requires a lot of code
276
    duplication.
277
278
This module gives us:
279
  - type safety
280
  - custom field validation
281
  - serialization and deserialization
282
  - rock solid foundational domain objects
283
284
285
Current deficiencies to schematics:
286
  - no get_mock_object method
287
  - no context-dependent serialization or MultilingualStringType
288
  - name = StringType(serialized_name='person_name')
289
  - name = StringType(serialize_when_none=False)
290
  - more flexible validation error messages
291
  - field validation can depend on other fields
292
  - 'roles' containing blacklists for .dump() and .json()
293
294
295
TODO:
296
  - alternate field names
297
  - add dump_if_null field option
298
  - add help/description parameter to Field
299
300
301
Optional Field Properties:
302
  - validation = None
303
  - default = None
304
  - required = True
305
  - in_dump = True
306
  - nullable = False
307
308
Behaviors:
309
  - Nullable is a "hard" setting, in that the value is either always or never allowed to be None.
310
  - What happens then if required=False and nullable=False?
311
      - The object can be init'd without a value (though not with a None value).
312
        getattr throws AttributeError
313
      - Any assignment must be not None.
314
315
316
  - Setting a value to None doesn't "unset" a value.  (That's what del is for.)  And you can't
317
    del a value if required=True, nullable=False, default=None.
318
319
  - If a field is not required, del does *not* "unmask" the default value.  Instead, del
320
    removes the value from the object entirely.  To get back the default value, need to recreate
321
    the object.  Entity.from_objects(old_object)
322
323
324
  - Disabling in_dump is a "hard" setting, in that with it disabled the field will never get
325
    dumped.  With it enabled, the field may or may not be dumped depending on its value and other
326
    settings.
327
328
  - Required is a "hard" setting, in that if True, a valid value or default must be provided. None
329
    is only a valid value or default if nullable is True.
330
331
  - In general, nullable means that None is a valid value.
332
    - getattr returns None instead of raising Attribute error
333
    - If in_dump, field is given with null value.
334
    - If default is not None, assigning None clears a previous assignment. Future getattrs return
335
      the default value.
336
    - What does nullable mean with default=None and required=True? Does instantiation raise
337
      an error if assignment not made on init? Can IntField(nullable=True) be init'd?
338
339
  - If required=False and nullable=False, field will only be in dump if field!=None.
340
    Also, getattr raises AttributeError.
341
  - If required=False and nullable=True, field will be in dump if field==None.
342
343
  - If in_dump is True, does default value get dumped:
344
    - if no assignment, default exists
345
    - if nullable, and assigned None
346
  - How does optional validation work with nullable and assigning None?
347
  - When does gettattr throw AttributeError, and when does it return None?
348
349
350
351
"""
352
353
354
class Field(object):
355
    """
356
    Fields are doing something very similar to boxing and unboxing
357
    of c#/java primitives.  __set__ should take a "primitive" or "raw" value and create a "boxed"
358
    or "programatically useable" value of it.  While __get__ should return the boxed value,
359
    dump in turn should unbox the value into a primitive or raw value.
360
361
    Arguments:
362
        types_ (primitive literal or type or sequence of types):
363
        default (any, callable, optional):  If default is callable, it's guaranteed to return a
364
            valid value at the time of Entity creation.
365
        required (boolean, optional):
366
        validation (callable, optional):
367
        dump (boolean, optional):
368
    """
369
370
    # Used to track order of field declarations. Supporting python 2.7, so can't rely
371
    #   on __prepare__.  Strategy lifted from http://stackoverflow.com/a/4460034/2127762
372
    _order_helper = 0
373
374
    def __init__(self, default=None, required=True, validation=None, post_validation=None,
375
                 in_dump=True, nullable=False, immutable=False):
376
        self._default = default if callable(default) else self.box(None, default)
377
        self._required = required
378
        self._validation = validation
379
        self._post_validation = post_validation
380
        self._in_dump = in_dump
381
        self._nullable = nullable
382
        self._immutable = immutable
383
        if default is not None:
384
            self.validate(None, self.box(None, maybecall(default)))
385
386
        self._order_helper = Field._order_helper
387
        Field._order_helper += 1
388
389
    @property
390
    def name(self):
391
        try:
392
            return self._name
393
        except AttributeError:
394
            log.error("The name attribute has not been set for this field. "
395
                      "Call set_name at class creation time.")
396
            raise
397
398
    def set_name(self, name):
399
        self._name = name
400
        return self
401
402
    def __get__(self, instance, instance_type):
403
        try:
404
            if instance is None:  # if calling from the class object
405
                val = getattr(instance_type, KEY_OVERRIDES_MAP)[self.name]
406
            else:
407
                val = instance.__dict__[self.name]
408
        except AttributeError:
409
            log.error("The name attribute has not been set for this field.")
410
            raise AttributeError("The name attribute has not been set for this field.")
411
        except KeyError:
412
            if self.default is not None:
413
                val = maybecall(self.default)  # default *can* be a callable
414
            elif self._nullable:
415
                return None
416
            else:
417
                raise AttributeError("A value for {0} has not been set".format(self.name))
418
        if val is None and not self.nullable:
419
            # means the "tricky edge case" was activated in __delete__
420
            raise AttributeError("The {0} field has been deleted.".format(self.name))
421
        return self.post_validate(instance, instance_type,
422
                                  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
    def post_validate(self, instance, instance_type, val):
473
        """
474
475
        Returns:
476
            True: if val is valid
477
478
        Raises:
479
            ValidationError
480
        """
481
        if self._post_validation is None or not instance._initd or self._post_validation(val):
482
            return val
483
        else:
484
            raise ValidationError(getattr(self, 'name', 'undefined name'), val)
485
486
    @property
487
    def required(self):
488
        return self._required
489
490
    @property
491
    def type(self):
492
        return self._type
493
494
    @property
495
    def default(self):
496
        return self._default
497
498
    @property
499
    def in_dump(self):
500
        return self._in_dump
501
502
    @property
503
    def nullable(self):
504
        return self.is_nullable
505
506
    @property
507
    def is_nullable(self):
508
        return self._nullable
509
510
    @property
511
    def immutable(self):
512
        return self._immutable
513
514
515
class BooleanField(Field):
516
    _type = bool
517
518
    def box(self, instance, val):
519
        return None if val is None else bool(val)
520
521
BoolField = BooleanField
522
523
524
class IntegerField(Field):
525
    _type = integer_types
526
527
IntField = IntegerField
528
529
530
class NumberField(Field):
531
    _type = integer_types + (float, complex)
532
533
534
class StringField(Field):
535
    _type = string_types
536
537
    def box(self, instance, val):
538
        return text_type(val) if isinstance(val, NumberField._type) else val
539
540
541
class DateField(Field):
542
    _type = datetime
543
544
    def box(self, instance, val):
545
        try:
546
            return dateparse(val) if isinstance(val, string_types) else val
547
        except ValueError as e:
548
            raise ValidationError(val, msg=e)
549
550
    def dump(self, val):
551
        return None if val is None else val.isoformat()
552
553
554
class EnumField(Field):
555
556
    def __init__(self, enum_class, default=None, required=True, validation=None,
557
                 post_validation=None, in_dump=True, nullable=False):
558
        if not issubclass(enum_class, Enum):
559
            raise ValidationError(None, msg="enum_class must be an instance of Enum")
560
        self._type = enum_class
561
        super(EnumField, self).__init__(default, required, validation, post_validation,
562
                                        in_dump, nullable)
563
564
    def box(self, instance, val):
565
        if val is None:
566
            # let the required/nullable logic handle validation for this case
567
            return None
568
        try:
569
            # try to box using val as an Enum name
570
            return val if isinstance(val, self._type) else self._type(val)
571
        except ValueError as e1:
572
            try:
573
                # try to box using val as an Enum value
574
                return self._type[val]
575
            except KeyError:
576
                raise ValidationError(val, msg=e1)
577
578
    def dump(self, val):
579
        return None if val is None else val.value
580
581
582
class ListField(Field):
583
    _type = tuple
584
585
    def __init__(self, element_type, default=None, required=True, validation=None,
586
                 post_validation=None, in_dump=True, nullable=False):
587
        self._element_type = element_type
588
        super(ListField, self).__init__(default, required, validation, post_validation,
589
                                        in_dump, nullable)
590
591
    def box(self, instance, val):
592
        if val is None:
593
            return None
594
        elif isinstance(val, string_types):
595
            raise ValidationError("Attempted to assign a string to ListField {0}"
596
                                  "".format(self.name))
597
        elif isinstance(val, Iterable):
598
            et = self._element_type
599
            if isinstance(et, type) and issubclass(et, Entity):
600
                return self._type(v if isinstance(v, et) else et(**v) for v in val)
601
            else:
602
                return self._type(val)
603
        else:
604
            raise ValidationError(val, msg="Cannot assign a non-iterable value to "
605
                                           "{0}".format(self.name))
606
607
    def unbox(self, instance, instance_type, val):
608
        return self._type() if val is None and not self.nullable else val
609
610
    def dump(self, val):
611
        if isinstance(self._element_type, type) and issubclass(self._element_type, Entity):
612
            return self._type(v.dump() for v in val)
613
        else:
614
            return val
615
616
    def validate(self, instance, val):
617
        if val is None:
618
            if not self.nullable:
619
                raise ValidationError(self.name, val)
620
            return None
621
        else:
622
            val = super(ListField, self).validate(instance, val)
623
            et = self._element_type
624
            self._type(Raise(ValidationError(self.name, el, et)) for el in val
625
                       if not isinstance(el, et))
626
            return val
627
628
629
class MutableListField(ListField):
630
    _type = list
631
632
633
class MapField(Field):
634
    _type = dict
635
    __eq__ = dict.__eq__
636
    __hash__ = dict.__hash__
637
638
639
class ComposableField(Field):
640
641
    def __init__(self, field_class, default=None, required=True, validation=None,
642
                 post_validation=None, in_dump=True, nullable=False):
643
        self._type = field_class
644
        super(ComposableField, self).__init__(default, required, validation, post_validation,
645
                                              in_dump, nullable)
646
647
    def box(self, instance, val):
648
        if val is None:
649
            return None
650
        if isinstance(val, self._type):
651
            return val
652
        else:
653
            # assuming val is a dict now
654
            try:
655
                # if there is a key named 'self', have to rename it
656
                val['slf'] = val.pop('self')
657
            except KeyError:
658
                pass  # no key of 'self', so no worries
659
            return val if isinstance(val, self._type) else self._type(**val)
660
661
    def dump(self, val):
662
        return None if val is None else val.dump()
663
664
665
class EntityType(type):
666
667
    @staticmethod
668
    def __get_entity_subclasses(bases):
669
        try:
670
            return [base for base in bases if issubclass(base, Entity) and base is not Entity]
671
        except NameError:
672
            # NameError: global name 'Entity' is not defined
673
            return ()
674
675
    def __new__(mcs, name, bases, dct):
676
        # if we're about to mask a field that's already been created with something that's
677
        #  not a field, then assign it to an alternate variable name
678
        non_field_keys = (key for key, value in items(dct)
679
                          if not isinstance(value, Field) and not key.startswith('__'))
680
        entity_subclasses = EntityType.__get_entity_subclasses(bases)
681
        if entity_subclasses:
682
            keys_to_override = [key for key in non_field_keys
683
                                if any(isinstance(base.__dict__.get(key), Field)
684
                                       for base in entity_subclasses)]
685
            dct[KEY_OVERRIDES_MAP] = {key: dct.pop(key) for key in keys_to_override}
686
        else:
687
            dct[KEY_OVERRIDES_MAP] = dict()
688
689
        return super(EntityType, mcs).__new__(mcs, name, bases, dct)
690
691
    def __init__(cls, name, bases, attr):
692
        super(EntityType, cls).__init__(name, bases, attr)
693
        cls.__fields__ = odict(cls.__fields__) if hasattr(cls, '__fields__') else odict()
694
        cls.__fields__.update(sorted(((name, field.set_name(name))
695
                                      for name, field in cls.__dict__.items()
696
                                      if isinstance(field, Field)),
697
                                     key=lambda item: item[1]._order_helper))
698
        if hasattr(cls, '__register__'):
699
            cls.__register__()
700
701
    def __call__(cls, *args, **kwargs):
702
        instance = super(EntityType, cls).__call__(*args, **kwargs)
703
        setattr(instance, '_{0}__initd'.format(cls.__name__), True)
704
        return instance
705
706
    @property
707
    def fields(cls):
708
        return cls.__fields__.keys()
709
710
711
@with_metaclass(EntityType)
712
class Entity(object):
713
    __fields__ = odict()
714
715
    def __init__(self, **kwargs):
716
        for key, field in items(self.__fields__):
717
            try:
718
                setattr(self, key, kwargs[key])
719
            except KeyError:
720
                # handle the case of fields inherited from subclass but overrode on class object
721
                if key in getattr(self, KEY_OVERRIDES_MAP):
722
                    setattr(self, key, getattr(self, KEY_OVERRIDES_MAP)[key])
723
                elif field.required and field.default is None:
724
                    raise ValidationError(key, msg="{0} requires a {1} field. Instantiated with "
725
                                                   "{2}".format(self.__class__.__name__,
726
                                                                key, kwargs))
727
            except ValidationError:
728
                if kwargs[key] is not None or field.required:
729
                    raise
730
        self.validate()
731
732
    @classmethod
733
    def from_objects(cls, *objects, **override_fields):
734
        init_vars = dict()
735
        search_maps = tuple(AttrDict(o) if isinstance(o, dict) else o
736
                            for o in ((override_fields,) + objects))
737
        for key in cls.__fields__:
738
            init_vars[key] = find_or_none(key, search_maps)
739
        return cls(**init_vars)
740
741
    create_from_objects = from_objects  # for backward compatibility; deprecated
742
743
    @classmethod
744
    def from_json(cls, json_str):
745
        return cls(**json_loads(json_str))
746
747
    @classmethod
748
    def load(cls, data_dict):
749
        return cls(**data_dict)
750
751
    def validate(self):
752
        # TODO: here, validate should only have to determine if the required keys are set
753
        try:
754
            all(getattr(self, name) for name, field in self.__fields__.items() if field.required)
755
        except AttributeError as e:
756
            raise ValidationError(None, msg=e)
757
758
    def __repr__(self):
759
        def _valid(key):
760
            if key.startswith('_'):
761
                return False
762
            try:
763
                getattr(self, key)
764
                return True
765
            except AttributeError:
766
                return False
767
768
        def _val(key):
769
            val = getattr(self, key)
770
            return repr(val.value) if isinstance(val, Enum) else repr(val)
771
772
        def _sort_helper(key):
773
            field = self.__fields__.get(key)
774
            return field._order_helper if field is not None else -1
775
776
        kwarg_str = ", ".join("{0}={1}".format(key, _val(key))
777
                              for key in sorted(self.__dict__, key=_sort_helper)
778
                              if _valid(key))
779
        return "{0}({1})".format(self.__class__.__name__, kwarg_str)
780
781
    @classmethod
782
    def __register__(cls):
783
        pass
784
785
    def json(self, indent=None, separators=None, **kwargs):
786
        return json_dumps(self, indent=indent, separators=separators, cls=DumpEncoder, **kwargs)
787
788
    def pretty_json(self, indent=2, separators=(',', ': '), **kwargs):
789
        return self.json(indent=indent, separators=separators, **kwargs)
790
791
    def dump(self):
792
        return odict((field.name, field.dump(value))
793
                     for field, value in ((field, getattr(self, field.name, None))
794
                                          for field in self.__dump_fields())
795
                     if value is not None or field.nullable)
796
797
    @classmethod
798
    def __dump_fields(cls):
799
        if '__dump_fields_cache' not in cls.__dict__:
800
            cls.__dump_fields_cache = tuple(field for field in values(cls.__fields__)
801
                                            if field.in_dump)
802
        return cls.__dump_fields_cache
803
804
    def __eq__(self, other):
805
        if self.__class__ != other.__class__:
806
            return False
807
        rando_default = 19274656290  # need an arbitrary but definite value if field does not exist
808
        return all(getattr(self, field, rando_default) == getattr(other, field, rando_default)
809
                   for field in self.__fields__)
810
811
    def __hash__(self):
812
        return sum(hash(getattr(self, field, None)) for field in self.__fields__)
813
814
    @property
815
    def _initd(self):
816
        return getattr(self, '_{0}__initd'.format(self.__class__.__name__), None)
817
818
819
class ImmutableEntity(Entity):
820
821
    def __setattr__(self, attribute, value):
822
        if self._initd:
823
            raise AttributeError("Assignment not allowed. {0} is immutable."
824
                                 .format(self.__class__.__name__))
825
        super(ImmutableEntity, self).__setattr__(attribute, value)
826
827
    def __delattr__(self, item):
828
        if self._initd:
829
            raise AttributeError("Deletion not allowed. {0} is immutable."
830
                                 .format(self.__class__.__name__))
831
        super(ImmutableEntity, self).__delattr__(item)
832