U b,@sPdZddlmZmZmZzddlmZmZWn$ek rPddl mZmZYnXddl m Z ddl m Z ddl mZmZmZddlmZddlmZd d lmZd d lmZd d lmZd dlmZmZd dl m!Z!m"Z"m#Z#d dl$m%Z%m&Z&d dl'm(Z(d dl)m*Z*d dl+m,Z,ee-Z.ddddddddddddd d!gZ/d"Z0d#Z1Gd$dde2Z3Gd%dde3Z4e4Z5Gd&dde3Z6e6Z7Gd'dde3Z8Gd(dde3Z9Gd)dde3Z:Gd*dde3Z;Gd+dde3ZGd/d!d!e3Z?Gd0d1d1e@ZAGd2ddeAd3ZBGd4ddeBZCGd5d6d6e2ZDGd7d8d8eZEd9S):a This module provides serializable, validatable, type-enforcing domain objects and data transfer objects. It has many of the same motivations as the python `Marshmallow `_ package. It is most similar to `Schematics `_. ======== Tutorial ======== Chapter 1: Entity and Field Basics ---------------------------------- >>> class Color(Enum): ... blue = 0 ... black = 1 ... red = 2 >>> class Car(Entity): ... weight = NumberField(required=False) ... wheels = IntField(default=4, validation=lambda x: 3 <= x <= 4) ... color = EnumField(Color) >>> # create a new car object >>> car = Car(color=Color.blue, weight=4242.46) >>> car Car(weight=4242.46, color=0) >>> # it has 4 wheels, all by default >>> car.wheels 4 >>> # but a car can't have 5 wheels! >>> # the `validation=` field is a simple callable that returns a >>> # boolean based on validity >>> car.wheels = 5 Traceback (most recent call last): ValidationError: Invalid value 5 for wheels >>> # we can call .dump() on car, and just get back a standard >>> # python dict actually, it's an ordereddict to match attribute >>> # declaration order >>> type(car.dump()) >>> car.dump() OrderedDict([('weight', 4242.46), ('wheels', 4), ('color', 0)]) >>> # and json too (note the order!) >>> car.json() '{"weight": 4242.46, "wheels": 4, "color": 0}' >>> # green cars aren't allowed >>> car.color = "green" Traceback (most recent call last): ValidationError: 'green' is not a valid Color >>> # but black cars are! >>> car.color = "black" >>> car.color >>> # car.color really is an enum, promise >>> type(car.color) >>> # enum assignment can be with any of (and preferentially) >>> # (1) an enum literal, >>> # (2) a valid enum value, or >>> # (3) a valid enum name >>> car.color = Color.blue; car.color.value 0 >>> car.color = 1; car.color.name 'black' >>> # let's do a round-trip marshalling of this thing >>> same_car = Car.from_json(car.json()) # or equally Car.from_json(json.dumps(car.dump())) >>> same_car == car True >>> # actually, they're two different instances >>> same_car is not car True >>> # this works too >>> cloned_car = Car(**car.dump()) >>> cloned_car == car True >>> # while we're at it, these are all equivalent too >>> car == Car.from_objects(car) True >>> car == Car.from_objects({"weight": 4242.46, "wheels": 4, "color": 1}) True >>> car == Car.from_json('{"weight": 4242.46, "color": 1}') True >>> # .from_objects() even lets you stack and combine objects >>> class DumbClass: ... color = 0 ... wheels = 3 >>> Car.from_objects(DumbClass(), dict(weight=2222, color=1)) Car(weight=2222, wheels=3, color=0) >>> # and also pass kwargs that override properties pulled >>> # off any objects >>> Car.from_objects(DumbClass(), {'weight': 2222, 'color': 1}, color=2, weight=33) Car(weight=33, wheels=3, color=2) Chapter 2: Entity and Field Composition --------------------------------------- >>> # now let's get fancy >>> # a ComposableField "nests" another valid Entity >>> # a ListField's first argument is a "generic" type, >>> # which can be a valid Entity, any python primitive >>> # type, or a list of Entities/types >>> class Fleet(Entity): ... boss_car = ComposableField(Car) ... cars = ListField(Car) >>> # here's our fleet of company cars >>> company_fleet = Fleet(boss_car=Car(color='red'), cars=[car, same_car, cloned_car]) >>> company_fleet.pretty_json() #doctest: +SKIP { "boss_car": { "wheels": 4 "color": 2, }, "cars": [ { "weight": 4242.46, "wheels": 4 "color": 1, }, { "weight": 4242.46, "wheels": 4 "color": 1, }, { "weight": 4242.46, "wheels": 4 "color": 1, } ] } >>> # the boss' car is red of course (and it's still an Enum) >>> company_fleet.boss_car.color.name 'red' >>> # and there are three cars left for the employees >>> len(company_fleet.cars) 3 Chapter 3: Immutability ----------------------- >>> class ImmutableCar(ImmutableEntity): ... wheels = IntField(default=4, validation=lambda x: 3 <= x <= 4) ... color = EnumField(Color) >>> icar = ImmutableCar.from_objects({'wheels': 3, 'color': 'blue'}) >>> icar ImmutableCar(wheels=3, color=0) >>> icar.wheels = 4 Traceback (most recent call last): AttributeError: Assignment not allowed. ImmutableCar is immutable. >>> class FixedWheelCar(Entity): ... wheels = IntField(default=4, immutable=True) ... color = EnumField(Color) >>> fwcar = FixedWheelCar.from_objects(icar) >>> fwcar.json() '{"wheels": 3, "color": 0}' >>> # repainting the car is easy >>> fwcar.color = Color.red >>> fwcar.color.name 'red' >>> # can't really change the number of wheels though >>> fwcar.wheels = 18 Traceback (most recent call last): AttributeError: The wheels field is immutable. Chapter X: The del and null Weeds --------------------------------- >>> old_date = lambda: isoparse('1982-02-17') >>> class CarBattery(Entity): ... # NOTE: default value can be a callable! ... first_charge = DateField(required=False) # default=None, nullable=False ... latest_charge = DateField(default=old_date, nullable=True) # required=True ... expiration = DateField(default=old_date, required=False, nullable=False) >>> # starting point >>> battery = CarBattery() >>> battery CarBattery() >>> battery.json() '{"latest_charge": "1982-02-17T00:00:00", "expiration": "1982-02-17T00:00:00"}' >>> # first_charge is not assigned a default value. Once one is assigned, it can be deleted, >>> # but it can't be made null. >>> battery.first_charge = isoparse('2016-03-23') >>> battery CarBattery(first_charge=datetime.datetime(2016, 3, 23, 0, 0)) >>> battery.first_charge = None Traceback (most recent call last): ValidationError: Value for first_charge not given or invalid. >>> del battery.first_charge >>> battery CarBattery() >>> # latest_charge can be null, but it can't be deleted. The default value is a callable. >>> del battery.latest_charge Traceback (most recent call last): AttributeError: The latest_charge field is required and cannot be deleted. >>> battery.latest_charge = None >>> battery.json() '{"latest_charge": null, "expiration": "1982-02-17T00:00:00"}' >>> # expiration is assigned by default, can't be made null, but can be deleted. >>> battery.expiration datetime.datetime(1982, 2, 17, 0, 0) >>> battery.expiration = None Traceback (most recent call last): ValidationError: Value for expiration not given or invalid. >>> del battery.expiration >>> battery.json() '{"latest_charge": null}' )absolute_importdivisionprint_function)MappingSequence)datetime)reduce) JSONEncoderdumpsloads) getLogger)Enum)NULL)isoparse) frozendict)AttrDictmake_immutable) integer_types isiterableodict)RaiseValidationError) find_or_raise) DumpEncoder) maybecallEntityImmutableEntityField BooleanField BoolField IntegerFieldIntField NumberField StringField DateField EnumField ListFieldMapFieldComposableFieldZ__key_overrides__a Current deficiencies to schematics: - no get_mock_object method - no context-dependent serialization or MultilingualStringType - name = StringType(serialized_name='person_name', alternate_names=['human_name']) - name = StringType(serialize_when_none=False) - more flexible validation error messages - field validation can depend on other fields - 'roles' containing denylists for .dump() and .json() __roles__ = { EntityRole.registered_name: Denylist('field1', 'field2'), EntityRole.another_registered_name: Allowlist('field3', 'field4'), } TODO: - alternate field names - add dump_if_null field option - add help/description parameter to Field - consider leveraging slots - collect all validation errors before raising - Allow returning string error message for validation instead of False - profile and optimize - use boltons instead of dateutil - correctly implement copy and deepcopy on fields and Entity, DictSafeMixin http://stackoverflow.com/questions/1500718/what-is-the-right-way-to-override-the-copy-deepcopy-operations-on-an-object-in-p Optional Field Properties: - validation = None - default = None - required = True - in_dump = True - nullable = False Behaviors: - Nullable is a "hard" setting, in that the value is either always or never allowed to be None. - What happens then if required=False and nullable=False? - The object can be init'd without a value (though not with a None value). getattr throws AttributeError - Any assignment must be not None. - Setting a value to None doesn't "unset" a value. (That's what del is for.) And you can't del a value if required=True, nullable=False, default=None. - If a field is not required, del does *not* "unmask" the default value. Instead, del removes the value from the object entirely. To get back the default value, need to recreate the object. Entity.from_objects(old_object) - Disabling in_dump is a "hard" setting, in that with it disabled the field will never get dumped. With it enabled, the field may or may not be dumped depending on its value and other settings. - Required is a "hard" setting, in that if True, a valid value or default must be provided. None is only a valid value or default if nullable is True. - In general, nullable means that None is a valid value. - getattr returns None instead of raising Attribute error - If in_dump, field is given with null value. - If default is not None, assigning None clears a previous assignment. Future getattrs return the default value. - What does nullable mean with default=None and required=True? Does instantiation raise an error if assignment not made on init? Can IntField(nullable=True) be init'd? - If required=False and nullable=False, field will only be in dump if field!=None. Also, getattr raises AttributeError. - If required=False and nullable=True, field will be in dump if field==None. - If in_dump is True, does default value get dumped: - if no assignment, default exists - if nullable, and assigned None - How does optional validation work with nullable and assigning None? - When does gettattr throw AttributeError, and when does it return None? c@seZdZdZdZedddddddfddZed d Zd d Z d dZ ddZ ddZ ddZ ddZddZddZeddZeddZedd Zed!d"Zed#d$Zed%d&Zed'd(Zed)d*ZdS)+ra Fields are doing something very similar to boxing and unboxing of c#/java primitives. __set__ should take a "primitive" or "raw" value and create a "boxed" or "programmatically usable" value of it. While __get__ should return the boxed value, dump in turn should unbox the value into a primitive or raw value. Arguments: types_ (primitive literal or type or sequence of types): default (any, callable, optional): If default is callable, it's guaranteed to return a valid value at the time of Entity creation. required (boolean, optional): validation (callable, optional): dump (boolean, optional): rTNFc Cs||_||_||_||_||_||_||_|tkr:t|_n6t |rF|n | dd||_| d| ddt |t j|_t jd7_dSNr) _required _validation_in_dump_default_in_dump _nullable _immutable_aliasesr_defaultcallableboxvalidaterr _order_helper selfdefaultrequired validationin_dumpdefault_in_dumpnullable immutablealiasesr+r+2lib/python3.8/site-packages/conda/auxlib/entity.py__init__wszField.__init__cCs.z|jWStk r(tdYnXdS)NzYThe name attribute has not been set for this field. Call set_name at class creation time.)_nameAttributeErrorlogerrorr:r+r+rCnames  z Field.namecCs ||_|SN)rE)r:rJr+r+rCset_nameszField.set_namecCsz*|dkrt|t|j}n |j|j}Wn^tk rPtdtdYn:tk r|jt krztd |jn t |j}YnX|dkr|j std |j| |||S)Nz3The name attribute has not been set for this field.z A value for {0} has not been setzThe {0} field has been deleted.)getattrKEY_OVERRIDES_MAPrJ__dict__rFrGrHKeyErrorr;rformatrr@unboxr:instance instance_typevalr+r+rC__get__s   z Field.__get__cCs@|jr|jrtd|j|||||j||j|j<dS)NThe {0} field is immutable.) rA_initdrFrQrJr7r6 __class__rOr:rTrVr+r+rC__set__s  z Field.__set__cCs^|jr|jrtd|jn<|jr6td|jn$|jsJd|j|j<n|j|jddS)NrXz0The {0} field is required and cannot be deleted.) rArYrFrQrJr<r@rOpop)r:rTr+r+rC __delete__s zField.__delete__cCs|SrKr+rSr+r+rCr6sz Field.boxcCs|SrKr+rSr+r+rCrRsz Field.unboxcCs|SrKr+rSr+r+rCdumpsz Field.dumpcCs^t||jr$|jdks ||r$|S|tkr6|js6|S|dkrH|jrH|Stt|dd|dS)zj Returns: True: if val is valid Raises: ValidationError NrJzundefined name) isinstance_typer.rr<r@rrMr[r+r+rCr7s zField.validatecCs|jSrK)r-rIr+r+rCr<szField.requiredcCs|jSrK)rarIr+r+rCtypesz Field.typecCs|jSrK)r4rIr+r+rCr;sz Field.defaultcCs|jSrK)r/rIr+r+rCr>sz Field.in_dumpcCs|jSrK)r0rIr+r+rCr?szField.default_in_dumpcCs|jSrK) is_nullablerIr+r+rCr@szField.nullablecCs|jSrK)r1rIr+r+rCrcszField.is_nullablecCs|jSrK)r2rIr+r+rCrAszField.immutable)__name__ __module__ __qualname____doc__r8rrDpropertyrJrLrWr\r^r6rRr_r7r<rbr;r>r?r@rcrAr+r+r+rCrcsF          c@seZdZeZddZdS)r cCs|dkr dSt|SrK)boolrSr+r+rCr6szBooleanField.boxN)rdrerfrirar6r+r+r+rCr sc@seZdZeZdS)r"N)rdrerfrrar+r+r+rCr" sc@seZdZeeefZdS)r$N)rdrerfrfloatcomplexrar+r+r+rCr$sc@seZdZeZddZdS)r%cCst|tjrt|S|SrK)r`r$rastrrSr+r+rCr6szStringField.boxN)rdrerfrlrar6r+r+r+rCr%sc@s eZdZeZddZddZdS)r&c CsLzt|trt|n|WStk rF}zt||dW5d}~XYnXdSNmsg)r`rlr ValueErrorr)r:rTrUrVer+r+rCr6sz DateField.boxcCs|dkr dS|SrK)Z isoformatrSr+r+rCr_$szDateField.dumpN)rdrerfrrar6r_r+r+r+rCr&scs>eZdZedddddddffdd ZddZd d ZZS) r'TNFr+c s>t|tstddd||_tt||||||||| dS)Nz&enum_class must be an instance of Enumrn) issubclassr rrasuperr'rD) r: enum_classr;r<r=r>r?r@rArBrZr+rCrD*s  zEnumField.__init__c Csv|dkr dSz ||WStk rp}z:z|j|WWY&Stk r^t||dYnXW5d}~XYnXdSrm)rarprPr)r:rTrUrVZe1r+r+rCr62s z EnumField.boxcCs|dtfkrdS|jSrK)rvaluerSr+r+rCr_@szEnumField.dumprdrerfrrDr6r_ __classcell__r+r+rurCr'(scsVeZdZeZedddddddffdd ZddZd d Zd d Z fd dZ Z S)r(TNFr+c s(||_tt||||||||| dSrK) _element_typersr(rD) r:Z element_typer;r<r=r>r?r@rArBrur+rCrDGszListField.__init__cs|dkr dSt|tr(td|jnht|r||jttrbtt rb| fdd|DS|j rpt |S| |Snt|d|jddS)Nz-Attempted to assign a string to ListField {0}c3s&|]}t|r|nf|VqdSrK)r`.0vetr+rC Vsz ListField.box..)Cannot assign a non-iterable value to {0}rn) r`rlrrQrJrryrbrrrrarArrSr+r}rCr6Ms z ListField.boxcCs|dkr|js|S|SrK)r@rarSr+r+rCrR]szListField.unboxcCs4t|jtr,t|jtr,|dd|DS|SdS)Ncss|]}|VqdSrKr_rzr+r+rCrbsz!ListField.dump..)r`ryrbrrrrarSr+r+rCr_`szListField.dumpcs:tt||}|r6jfdd|D|S)Nc3s*|]"}t|sttj|VqdSrK)r`rrrJ)r{Zelr~r:r+rCrjs z%ListField.validate..)rsr(r7ryrar[rurrCr7fs zListField.validate) rdrerftuplerarrDr6rRr_r7rxr+r+rurCr(Dsc@seZdZeZdS)MutableListFieldN)rdrerflistrar+r+r+rCrosrcs:eZdZeZedddddddffdd ZddZZS) r)TNFr+c s"tt|||||||||dSrK)rsr)rDr9rur+rCrDvs zMapField.__init__cCsZ|dkr|St|rBt|}t|ts>t|d|jd|St|d|jddS)Nrrn)rarrr`rrrQrJrSr+r+rCr6{s z MapField.box) rdrerfrrarrDr6rxr+r+rurCr)sscs>eZdZedddddddffdd ZddZd d ZZS) r*TNFr+c s(||_tt||||||||| dSrK)rarsr*rD) r:Z field_classr;r<r=r>r?r@rArBrur+rCrDszComposableField.__init__cCs|dkr dSt||jr|Szt|dr6|d|d<Wntk rLYnXt||jrvt||jrj|S|jf|St|tr|jf|St|trt|ts|j|S||SdS)Nr]r:Zslf)r`rahasattrr]rPrrrlrSr+r+rCr6s       zComposableField.boxcCs|dkr dS|SrKrrSr+r+rCr_szComposableField.dumprwr+r+rurCr*scsLeZdZeddZfddZfddZfddZed d Z Z S) EntityTypecCs,zdd|DWStk r&YdSXdS)NcSs"g|]}t|tr|tk r|qSr+)rrrr{baser+r+rC s z6EntityType.__get_entity_subclasses..r+) NameError)basesr+r+rCZ__get_entity_subclassessz"EntityType.__get_entity_subclassescsnddD}t|rNfdd|D}tfdd|Dt<n tt<tt||||S)Ncss*|]"\}}t|ts|ds|VqdS)__N)r`r startswith)r{keyrvr+r+rCrs z%EntityType.__new__..cs&g|]tfddDrqS)c3s |]}t|jtVqdSrK)r`rOgetrrrr+rCrsz0EntityType.__new__...)any)r{)entity_subclassesrrCrs  z&EntityType.__new__..c3s|]}||fVqdSrK)r]r{r)dctr+rCrs)itemsr"_EntityType__get_entity_subclassesdictrNrs__new__)ZmcsrJrrZnon_field_keysZkeys_to_overrideru)rrrCrs  zEntityType.__new__cs|tt||||t}dd}tt|D]*}dd|jD}| t ||dq0t ||_ t |drx|dS)NcSs |djSr,)r8)xr+r+rCz%EntityType.__init__..css*|]"\}}t|tr|||fVqdSrK)r`rrLr{rJfieldr+r+rCrs z&EntityType.__init__..r __register__)rsrrDrreversedrbmrorOrupdatesortedr __fields__rr)clsrJrattrfieldsZ_field_sort_keyZclzZ clz_fieldsrur+rCrDs  zEntityType.__init__cs*tt|j||}t|d|jd|S)N _{0}__initdT)rsr__call__setattrrQrd)rargskwargsrTrur+rCrszEntityType.__call__cCs |jSrK)rkeysrr+r+rCrszEntityType.fields) rdrerf staticmethodrrrDrrhrrxr+r+rurCrs    rc@seZdZeZdZddZeddZeddZ edd Z d d Z d d Z eddZ d!ddZd"ddZddZeddZddZddZedd ZdS)#rFc s|jD]\}}zt|||Wq tk rtfdd|jDd}|dk rjt|||nP|t|tkrt||t|t|n*|jr|j t krt |d |j j|dYq t k r|dk s|jrYq Xq |js|dS)Nc3s|]}|kr|VqdSrKr+)r{Zlsrr+rCrsz"Entity.__init__..z/{0} requires a {1} field. Instantiated with {2}rn)rrrrPnextr3rMrNr<r;rrrQrZrd_lazy_validater7)r:rrraliasr+rrCrDs(  zEntity.__init__c Osht}tdd|f|D}|jD]4\}}zt|||j||<Wq(tk rZYq(Xq(|f|S)Ncss$|]}t|trt|n|VqdSrK)r`rr)r{or+r+rCrsz&Entity.from_objects..)rrrrrr3rF)rZobjectsZoverride_fieldsZ init_varsZ search_mapsrrr+r+rC from_objectsszEntity.from_objectscCs|ft|SrK) json_loads)rZjson_strr+r+rC from_json szEntity.from_jsoncCs |f|SrKr+)rZ data_dictr+r+rCloadsz Entity.loadc sz&tfddddjDWnZtk rT}zt|dkrDW5d}~XYn.tk r}ztd|dW5d}~XYnXdS)Ncs t|SrKrM)_rJrIr+rCrrz!Entity.validate..css|]\}}|jr|VqdSrK)r<rr+r+rCrsz"Entity.validate..z0reduce() of empty sequence with no initial valuern)rrr TypeErrorrlrFr)r:rqr+rIrCr7s  zEntity.validatecsXfddfddfdd}dfdd tj|d D}d jj|S) Ncs8d|kr dSzt|WdStk r2YdSXdS)NrFT)rMrFrrIr+rC_valid!s zEntity.__repr__.._validcs&t|}t|trt|jSt|SrK)rMr`r reprrv)rrVrIr+rC_val-s zEntity.__repr__.._valcsj|}|dk r|jSdS)N)rrr8)rrrIr+rC _sort_helper1s z%Entity.__repr__.._sort_helperz, c3s&|]}|rd||VqdS)z{0}={1}N)rQr)rrr+rCr5sz"Entity.__repr__..rz{0}({1}))joinrrOrQrZrd)r:rZ kwarg_strr+)rrr:rC__repr__ s   zEntity.__repr__cCsdSrKr+rr+r+rCr:szEntity.__register__NcKst|f||td|S)N)indent separatorsr) json_dumpsrr:rrrr+r+rCjson>sz Entity.jsonr,z: cKs|jf||d|S)N)rr)rrr+r+rC pretty_jsonAszEntity.pretty_jsoncs(tfddfddDDS)Nc3s@|]8\}}|tk r||jkr"|jr|j|j|fVqdSrK)rr;r?rJr_rZ)r{rrvrIr+rCrEs  zEntity.dump..c3s |]}|t|jtfVqdSrK)rMrJrr{rrIr+rCrFs)r_Entity__dump_fieldsrIr+rIrCr_Ds   z Entity.dumpcCs*d|jkr$tdd|jD|_|jS)NZ__dump_fields_cachecss|]}|jr|VqdSrK)r>rr+r+rCrNsz'Entity.__dump_fields..)rOrrvaluesZ_Entity__dump_fields_cacherr+r+rCZ __dump_fieldsKs   zEntity.__dump_fieldscs0jjkrdSdtfddjDS)NFl"jyc3s&|]}t|t|kVqdSrKrrotherZ rando_defaultr:r+rCrWsz Entity.__eq__..)rZallr)r:rr+rrC__eq__Ss  z Entity.__eq__cstfddjDS)Nc3s|]}tt|dVqdSrK)hashrMrrIr+rCr[sz"Entity.__hash__..)sumrrIr+rIrC__hash__ZszEntity.__hash__cCst|d|jjdS)Nr)rMrQrZrdrIr+r+rCrY]sz Entity._initd)NN)rr)rdrerfrrrrD classmethodrrrr7rrrrr_rrrrhrYr+r+r+rCrs,        ) metaclasscs(eZdZfddZfddZZS)rcs.|jrtd|jjtt|||dS)Nz)Assignment not allowed. {0} is immutable.)rYrFrQrZrdrsr __setattr__)r:Z attributervrur+rCrds zImmutableEntity.__setattr__cs,|jrtd|jjtt||dS)Nz'Deletion not allowed. {0} is immutable.)rYrFrQrZrdrsr __delattr__r:itemrur+rCrjs zImmutableEntity.__delattr__)rdrerfrrrxr+r+rurCrbs c@s`eZdZddZddZddZddd Zd d Zd d ZddZ ddZ ddZ dddZ dS) DictSafeMixincCs t||SrKrrr+r+rC __getitem__sszDictSafeMixin.__getitem__cCst|||dSrKr)r:rrvr+r+rC __setitem__vszDictSafeMixin.__setitem__cCst||dSrK)delattrr:rr+r+rC __delitem__yszDictSafeMixin.__delitem__NcCs t|||SrKr)r:rr;r+r+rCr|szDictSafeMixin.getcCs@t||d}|dkrdS|j|}t|ttfrsrm          R +#8}8