3 d @sdZddlZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddlm Z ddl m ZddlmZddlmZmZddlmZmZdd lmZdd lmZdd lmZmZmZm Z dd l!m"Z"m#Z#m$Z$m%Z%m&Z&m'Z'dd l(m)Z)m*Z*m+Z+m,Z,m-Z-m.Z.m/Z/ddl0m1Z1m2Z2m3Z3m4Z4m5Z5m6Z6ddl7m8Z8ddl9m:Z:ddl;mZ>m?Z?m@Z@dZAGdddejBZCe,e-fZDdZEdZFdZGdZHdZIdZJdZKdZLdqZMdrZNejOd!ZPe"jQZRejSe/d"ZTdsd#d$ZUd%d&ZVd'd(ZWd)d*ZXd+d,ZYd-d.ZZd/d0Z[Gd1d2d2Z\d3d4Z]d5d6Z^d7d8Z_d9d:Z`d;d<ZadZbGd=d>d>ecZdd?d@ZedAdBZfdCdDdEdFdGZgdtdHdIZhdJdKZidudLdMZjdNdOZkGdPdQdQeeddRZlelZbGdSdTdTelZmGdUdVdVemZnGdWdXdXelZoGdYdZdZejpedZqGd[d\d\eleqdRZrGd]d^d^erZsGd_d`d`elZtGdadbdbemZuGdcddddeoZvGdedfdfemZwe%ewZxGdgdhdheqZyGdidjdjeleydRZzdkdlZ{dmdnZ|GdodpdpezZ}dS)vzc Defines the HasTraits class, along with several useful subclasses and associated metaclasses. N) FunctionType) __version__)AdaptationError) DefaultValue TraitKind)CTrait __newobj__) CHasTraits)api)ForwardPropertyPropertyTrait generic_trait)AnyBoolDisallowEventPythonStr) ExtendedTraitChangeNotifyWrapperFastUITraitChangeNotifyWrapperNewTraitChangeNotifyWrapper!StaticAnytraitChangeNotifyWrapperStaticTraitChangeNotifyWrapperTraitChangeNotifyWrapper ui_dispatch) SequenceTypes TraitsCache Undefinedis_none not_event not_false) TraitError) deprecated)check_traitsui_major_version) check_traitmapped_trait_for trait_forc@s eZdZdS)AbstractViewElementN)__name__ __module__ __qualname__r-r-3/tmp/pip-build-7vycvbft/traits/traits/has_traits.pyr)Usr)__base_traits____class_traits____prefix_traits____listener_traits____observer_traits__Z__view_traits____instance_traits__Z traits_vieweventdelegateconstantpropertyz.*[ :\+\-,\.\*\?\[\]])sameuicCsBttj}|j||jdk r*|jj|_|dk r>|jj||S)z+ Creates a clone of a specified trait. N)rrtraitclone__dict__copyupdate)r<metadatar;r-r-r. _clone_traits     rAcCs$t||d}|dk r t|r |SdS)z4 Get the definition of a specified method (if any). N)getattris_unbound_method_type)clsmethodresultr-r-r. _get_methods rGcCs|dddkr"d|jd|f}|j|}|dk r`t|r`t|dddkr`t|dddkr`|SxL|D]D}t||d}|dk rft|rft|dddkrft|dddkrf|SqfWdS) z9 Gets the definition of a specified method (if any). r__z_%s%s_Non_trait_change_observe_inputs)lstripgetrCrB) class_name class_dictbasesrErFbaser-r-r._get_defs    rScCstj|ptj|S)z Check for something that looks like an unbound class method. This is used in practice to identify magic-named _name_changed and _name_fired methods. )inspect isfunctionismethoddescriptor)rEr-r-r.rCs rCcCs~t|ttfr,x|D]}t|sdSqWdSt|trhx,|jD] \}}t| s\t| r@dSq@WdSt|t p||jtS)z? Returns whether or not a specified value is serializable. FT) isinstancelisttuple_is_serializabledictitems HasTraitshas_traits_interface ISerializable)valueitemnamer-r-r.rZs  rZc Csi}xn|D]f}x`|jjtjD]L\}}|j|}|dkrL|dd||<q x|D]}||krR|j|qRWq Wq Wx|jD]\}}|dddkot|r~d} |jd} | dkrd} |jd} | dkr~|| | d} | d kr~||d| f}|j| g}||kr~|j|q~W|S) zX Returns a dictionary of potential 'Instance' or 'List(Instance)' handlers. NrrJ Z _changed_for_rH Z _fired_for_)r=rNInstanceTraitsr\appendrCfind setdefault) rPrQinstance_traitsrRrbZbase_arg_lists arg_listsarg_listr`ncolkeyr-r-r._get_instance_handlerss0      rpcCsJ|j}|dkr|}n(t|dkr<|ddkr<|dd|}d|j|fS)zb Returns the correct 'delegate' listener pattern for a specified name and delegate trait. rer*Nz %s:%srr)_prefixlenZ _delegate)rbr;prefixr-r-r.get_delegate_patterns rvc@seZdZddZddZdS) _SimpleTestcCs ||_dS)N)r`)selfr`r-r-r.__init__ sz_SimpleTest.__init__cCs ||jkS)N)r`)rxtestr-r-r.__call__sz_SimpleTest.__call__N)r*r+r,ryr{r-r-r-r.rw srwcCs.x(|D] }t|tst|}|j|qWdS)z< Adds a list of handlers to a specified notifiers list. N)rW WrapperTypesrrg) notifiershandlershandlerr-r-r._add_notifierss  rcCsX|j}|dk rTt|tr|g}x4|D],}|jt|d||jt|d|q$WdS)zG Adds any specified event handlers defined for a trait by a class. Nz _%s_changedz _%s_fired)r5rWstrrgrG)r;rDr~eventsr5r-r-r._add_event_handlerss  rcCs |j|S)zW Returns the method associated with a particular class property getter/setter. )rN)rPrbr-r-r._property_method*srcs2fddfdd}t|}t|d|ddS)a Create the metadata for setting up an observer for Property. Parameters ---------- observe : str or list or Expression As is accepted by HasTraits.observe expression argument This is the value provided in Property(observe=...) property_name : str The name of the property trait. cached : boolean Whether the property is cached or not. Returns ------- state : dict State to be used by _init_traits_observers cs0rt}|jj|t}nt}|j|dS)N)rr=poprtrait_property_changed)instancer5Z cache_nameold)cached property_namer-r.rDs z/_create_property_observe_state..handlercs tj|S)N)types MethodType)rrb)rr-r.handler_getterLsz6_create_property_observe_state..handler_getterr9F)graphsdispatchr post_init)_compile_expressionr[)observerrrrr-)rrrr._create_property_observe_state1s rcCsPt|tr|}n|g}g}x0|D](}|jt|trd|f|| <t| dd}|dk r|| | <qHt| trtt|| <qHt| tr| || <|| =qHxR| D]J}| |kr|| }|jt krt!d|j| f|| || <|| =PqWqHWi}x| D]}|j}x8|j"t#jD]&\} } | |kr| |kr| || <qWx6|t$jD]&\} }| |krH| |krH|| | <qHWx\|j"t%jD]J\} } | |kr| j&}|dk rt'| }t(| | ||||<} | || <qWxj|j"t)jD]X\} } | |kr| j&}|dk r.|j"t'| } | dk r | } nt(| | ||} | || <qW|j"t*}!x2|!dD]&} | |krP|j| |!| || <qPWqW|j"ddkr|jdt+j,|d<||d<|j-t.ddt/|| }"t0|||d}#|#dk rt1|#}#|#|d<t2}$x*t|j3D]} || }%|#t0|||d| t0|||d| g}&|%j}'|'dk rT| |"ks|'dkr| d)ddkr| dd*|"kr|&jtt|'|%j4}(|(dk rt|(tr|(g}(x>|(D]6})|&jt0|||d|)|&jt0|||d|)qWd d|&D}&t0||gd!| }*t.|&d"ks,|*dk r| |$krP|$j5| t|%|| <}%t.|&d"krnt6|%j7d|&|*dk r|%j8t9j:|*|%jd#kr|%j;dk r|%j<}+|+dkrt=| }+|%j;},t|,t>rd$j?|,},nd%|,},d#|+|,f|| <|%jd#kr|%j@dk rtA|%j@| |%jsz,update_traits_class_dict..cSsg|]}|jjtqSr-)r=rNr)rrRr-r-r.rsT_get__set_NsettableF flushable _validate_rrJr;_list_changed_handler_list_items_changed_handler_itemsr6r5rKrErLziCannot specify a default value for the %s trait '%s'. You must override the the trait definition instead.rqre)roreverseZ_anytrait_changed@z _%s_changedz _%s_firedcSsg|]}|dk r|qS)Nr-)rhr-r-r.rsz _%s_defaultrr8, )rrrrrrrii)DrXr\r&rWrr rrBr]_set_traits_cache_flush_traits_cachevalidater rr@r has_itemsrA items_eventr=instance_handler is_mappedr'Z _listenablervrKrrgrCr8rr)CantHaveDefaultValuer#rNListenerTraitsObserverTraits BaseTraitsZproperty_fieldsidmigrate_propertyr PrefixTraitsr as_ctraitsortrtrprSrsetkeysr5addr _notifiersZset_default_valuercallable depends_onrrrjoinrrrf ViewTraits).rOrQrPZ base_traits class_traits prefix_traits listeners prefix_list view_elementsZ observershastraits_basesZinherited_class_traitsrbr`rcgettersetterrZ value_typerZ items_traitrKpatternZobserver_statesctZictraitZmigrated_propertiesrRZ base_dictstates property_inforoZ new_valueZbase_prefix_traitsrjanytraitZclonedr;r~rrr5defaultrrZobserver_stater-r-r.rs^                                                     rc Cspt|d|}t|d|}t|d|}|dk sB|dk sB|dk rl|\}}} t|pT||pZ||p`| df|jS|S)zc Migrates an existing property to the class being defined (allowing for method overrides). rrrNT)rr r=) rbr8rrPrNrvalZold_getZold_setZold_valr-r-r.rs rFr9)rrcst|fdd}|S)a Marks the wrapped method as being a handler to be called when the specified traits change. This decorator can be stacked, e.g.:: @observe("attr1") @observe("attr2", post_init=True) def updated(self, event): ... The decorated function must accept one argument which is the event object representing the change. See :mod:`traits.observation.events` for details. Parameters ---------- expression : str or list or ObserverExpression A description of what traits are being observed. If this is a list, each item must be a string or Expression. See :py:func:`HasTraits.observe` for details on the semantics when passing a string. post_init : boolean, optional Whether the change handler should be attached after the state is set when instantiating an object. Default is false, and values provided to the instance constructor will trigger the change handler to fire if the value is different from the default. Set to true to avoid this change event. dispatch : str, optional A string indicating how the handler should be run. Default is to run it on the same thread where the change occurs. Possible values are: =========== ======================================================= value dispatch =========== ======================================================= ``same`` Run notifications on the same thread where the change occurs. The notifications are executed immediately. ``ui`` Run notifications on the UI thread. If the current thread is the UI thread, the notifications are executed immediately; otherwise, they are placed on the UI event queue. =========== ======================================================= See Also -------- HasTraits.observe cstj|}y|jddWn$tk r>tjdtddYnXy |j}Wntk rhg}||_YnXt t d}|j ||S)a Create input arguments for HasTraits.observe and attach the input to the callable. The metaclass will then collect this information for calling HasTraits.observe with the decorated function. Parameters ---------- handler : callable Method of a subclass of HasTraits, with signature of the form ``my_method(self, event)``. rxr5zDubious signature for observe-decorated method. The decorated method should be callable with a single positional argument in addition to 'self'. Did you forget to add an 'event' parameter?rH)r)rrrr) rT signaturebind TypeErrorrr UserWarningrLAttributeErrorr[rBrg)rZhandler_signatureZobserve_inputsZ observe_input)rrrr-r.observe_decoratorAs(    z"observe..observe_decorator)r)rrrrr-)rrrr.rs0.rcsfdd}|S)a0 Marks the following method definition as being a handler for the extended trait change specified by *name(s)*. Refer to the documentation for the on_trait_change() method of the **HasTraits** class for information on the correct syntax for the *name* argument and the semantics of the *dispatch* keyword argument. A handler defined using this decorator is normally effective immediately. However, if *post_init* is **True**, then the handler only becomes effective after all object constructor arguments have been processed. That is, trait values assigned as part of object construction will not cause the handler to be invoked. See Also -------- observe : A newer API for defining traits notifications. csd|_|S)N)rrr)rK)function)rrbrr-r. decorators z"on_trait_change..decoratorr-)rbrrrr-)rrbrr.rKrs rKcs*tjddfdd}d|_|S)a Marks the following method definition as being a "cached property". That is, it is a property getter which, for performance reasons, caches its most recently computed result in an attribute whose name is of the form: *_traits_cache_name*, where *name* is the name of the property. A method marked as being a cached property needs only to compute and return its result. The @cached_property decorator automatically wraps the decorated method in cache management code, eliminating the need to write boilerplate cache management code explicitly. For example:: file_name = File file_contents = Property(observe='file_name') @cached_property def _get_file_contents(self): with open(self.file_name, 'rb') as fh: return fh.read() In this example, accessing the *file_contents* trait calls the _get_file_contents() method only once each time after the **file_name** trait is modified. In all other cases, the cached value **_file_contents**, which maintained by the @cached_property wrapper code, is returned. Note the use, in the example, of the **observe** metadata attribute to specify that the value of **file_contents** depends on **file_name**, so that _get_file_contents() is called only when **file_name** changes. For details, see the traits.traits.Property() function. Ncs,|jjt}|tkr(||j<}|S)N)r=rNr)rxrF)rrbr-r.rsz"cached_property..decoratorT)rr*cached_property)rrr-)rrbr.rsrcsfdd}|S)at Marks the following method definition as being a "cached property" that depends on the specified extended trait names. That is, it is a property getter which, for performance reasons, caches its most recently computed result in an attribute whose name is of the form: *_traits_cache_name*, where *name* is the name of the property. A method marked as being a cached property needs only to compute and return its result. The @property_depends_on decorator automatically wraps the decorated method in cache management code that will cache the most recently computed value and flush the cache when any of the specified dependencies are modified, thus eliminating the need to write boilerplate cache management code explicitly. For example:: file_name = File file_contents = Property @property_depends_on( 'file_name' ) def _get_file_contents(self): with open(self.file_name, 'rb') as fh: return fh.read() In this example, accessing the *file_contents* trait calls the _get_file_contents() method only once each time after the **file_name** trait is modified. In all other cases, the cached value **_file_contents**, which is maintained by the @cached_property wrapper code, is returned. cs<tjddfdd}d|_|_|_|_|S)Nrcs,|jjt}|tkr(||j<}|S)N)r=rNr)rxrF)rrbr-r.wrappersz7property_depends_on..decorator..wrapperT)rr*rrrr)rr) dependencyrr)rrbr.rsz&property_depends_on..decoratorr-)rrrrr-)rrrr.property_depends_onsrcstj|fdd}|S)z Create a weak reference to arg and wrap the function so that the dereferenced weakref is passed as the first argument. If arg has been deleted then the function is not called. csfdd}fdd}fdd}fdd}fd d }fd d }jjd }|dkrl|S|d krx|S|dkr|S|dkr|S|dkr|S|SdS)Ncs}|dk r|SdS)Nr-)arg)rweak_argr-r.wrapper0sz-weak_arg..decorator..wrapper0cs}|dk r||SdS)Nr-)arg1r)rrr-r.wrapper1sz-weak_arg..decorator..wrapper1cs}|dk r|||SdS)Nr-)rarg2r)rrr-r.wrapper2sz-weak_arg..decorator..wrapper2cs }|dk r||||SdS)Nr-)rrarg3r)rrr-r.wrapper3 sz-weak_arg..decorator..wrapper3cs"}|dk r|||||SdS)Nr-)rrrZarg4r)rrr-r.wrapper4sz-weak_arg..decorator..wrapper4cs }|dk r|f|dS)Nr-)argsr)rrr-r.wrappernsz-weak_arg..decorator..wrappernrrrH)__code__ co_argcount)rrrrrrrr)r)rr.rs$ zweak_arg..decorator)weakrefref)rrr-)rr.rs  1rcs8eZdZdZedddZeeee e dZ e e Z e ZddZeddZed d Zedd d ZedddZeddZddZddZddZdddZddZedddZeje_ddd Zed!dd"d#Zeje_d$d%Zdd'd(Z d)d*Z!d+d,Z"fd-d.Z#dd/d0Z$dd1d2Z%d3d4Z&dd6d7Z'd8d9Z(dd:d;Z)eddd?Z+d@dAZ,edBdCZ-ddDdEZ.dFdGZ/edHdIZ0edJdKZ1ddLdMZ2dNdOZ3edPdQZ4dRdSZ5edTdUZ6ddVdWZ7ddYdZZ8d dXd[d\d]Z9dd^d_Z:e:Z;dd`daZdfdgZ?dhdiZ@djdkZAdldmZBddndoZCdpdqZDdrdsZEdtduZFedvdwZGdxdyZHedzd{ZId|d}ZJd~dZKddZLdddZMdddZNddZOddZPddZQddZRddZSddZTddZUddZVddZWddZXddZYddZZddZ[ddZ\ddZ]ddZ^Z_S)r]a Enables any Python class derived from it to have trait attributes. Most of the methods of HasTraits operated by default only on the trait attributes explicitly defined in the class definition. They do not operate on trait attributes defined by way of wildcards or by calling **add_trait()**. For example:: >>> class Person(HasTraits): ... name = Str ... age = Int ... temp_ = Any >>> bob = Person() >>> bob.temp_lunch = 'sandwich' >>> bob.add_trait('favorite_sport', Str('football')) >>> print(bob.trait_names()) ['trait_added', 'age', 'name'] In this example, the trait_names() method returns only the *age* and *name* attributes defined on the Person class. (The **trait_added** attribute is an explicit trait event defined on the HasTraits class.) The wildcard attribute *temp_lunch* and the dynamically-added trait attribute *favorite_sport* are not listed. Subclass should avoid defining new traits and/or methods with names starting with "trait" or "_trait" to avoid overshadowing existing methods, unless it has been documented as being safe to do so. T)private transient)r9extendednewZfast_uir:cCs<|j|}|jdkr8|dddkr8|j|dt||dS)z4 Handles a 'trait_added' event being fired. r6rNri)r;r_init_trait_delegate_listenerrv)rxrbr;r-r-r._trait_added_changedcs zHasTraits._trait_added_changedcGsnt|dkrtdt|dkr*t|}n t|d}|j||ddx"|jdD]}|j||ddqRWdS)a Adds a named trait attribute to this class. Also adds the same attribute to all subclasses. Parameters ---------- name : str Name of the attribute to add. *trait : A trait or a value that can be converted to a trait using Trait() Trait definition of the attribute. It can be a single value or a list equivalent to an argument list for the Trait() function. rz"No trait definition was specified.rF) is_subclassTN)rt ValueErrorrr(_add_class_traittrait_subclasses)rDrbr;subclassr-r-r.add_class_traitps    zHasTraits.add_class_traitc Csx|j}|t}|dddkrr|dd}||krF|r:dStd||||<|d}|j||jtdddS|t}|j|dk r|rdStd||j}|dk r|j r|j |d |j |d |j r|j |dt |||d |jd k r||t|<t|d |t|d |g} t||| | j|jddd| D} t| dkrlt|}t|jd| |||<dS)aB Add a named trait attribute to this class. Does not affect subclasses. Parameters ---------- name : str Name of the attribute to add. trait : CTrait The trait to be added. is_subclass : bool True if we're adding the trait to a strict subclass of the original class that add_class_trait was called for. This is used to decide how to behave if ``cls`` already has a trait named ``name``: in that circumstance, if ``is_subclass`` is False, an error will be raised, while if ``is_subclass`` is True, no trait will be added. Raises ------ TraitError If a trait with the given name already exists, and is_subclass is ``False``. rNrJz#The '%s_' trait is already defined.rqT)rorz"The '%s' trait is already defined.r)rFz _%s_changedz _%s_firedrcSsg|]}|dk r|qS)Nr-)rrr-r-r.rsz.HasTraits._add_class_trait..rrrrr)r=rr#rgrrtrrNrrrrrr'is_baserrGrrArr) rDrbr;rrPrrrrr~r-r-r.rsR        zHasTraits._add_class_traitFc Cs^y8t|tr6| r(||jkr(td|||j|<dSWntk rLYnXtd|dS)z5 Sets a trait notification dispatch handler. z8A dispatch handler called '%s' has already been defined.Nz1%s is not a subclass of TraitChangeNotifyWrapper.) issubclassrwrappersr#r)rDrbroverrider-r-r.set_trait_dispatch_handlers  z$HasTraits.set_trait_dispatch_handlercCs|s |jS|jgS)a  Returns a list of the immediate (or all) subclasses of this class. Parameters ---------- all : bool Indicates whether to return all subclasses of this class. If False, only immediate subclasses are returned. )__subclasses___trait_subclasses)rDallr-r-r.r  s zHasTraits.trait_subclassescCs2x,|jD] }||kr |j||j|q W|S)N)rrgr)rDZ subclassesr r-r-r.rs  zHasTraits._trait_subclassescGs t||S)akReturns whether the object implements a specified traits interface. Tests whether the object implements one or more of the interfaces specified by *interfaces*. Return **True** if it does, and **False** otherwise. Parameters ---------- *interfaces : One or more traits Interface (sub)classes. )rW)rxZ interfacesr-r-r.r^ s zHasTraits.has_traits_interfacecs|jtd}|j|jtfdd|jdddD|jtrvx2|jD]&\}}t |sLt d||j j |fqLW|j dt|S) ao Returns a dictionary of traits to pickle. In general, avoid overriding __getstate__ in subclasses. Instead, mark traits that should not be pickled with 'transient = True' metadata. In cases where this strategy is not sufficient, override __getstate__ in subclasses using the following pattern to remove items that should not be persisted:: def __getstate__(self): state = super().__getstate__() for key in ['foo', 'bar']: if key in state: del state[key] return state )rcs g|]}|kr||fqSr-r-)rrb)dicr-r.rHsz*HasTraits.__getstate__..r6F)rrzGThe '%s' trait of a '%s' instance contains the unserializable value: %s__traits_version__) trait_getr r=r?r[ trait_namesr^r_r\rZr# __class__r*ri TraitsVersion)rxrFrbr`r-)rr. __getstate__.s    zHasTraits.__getstate__cCst|jf|jfS)N)r rr)rxprotocolr-r-r. __reduce_ex__cszHasTraits.__reduce_ex__cs|jdddkrRfdddgD}|jj||jfd|it|n<|j|j|jfd|i||j|j|j |j dS)z= Restores the previously pickled state of an object. rNcsg|]}||fqSr-r-)rrb)rr-r.rnsz*HasTraits.__setstate__..Z__HasTraits_restore__trait_change_notify) rr=r? trait_setr[_init_trait_listeners_init_trait_observers_post_init_trait_listeners_post_init_trait_observers traits_init_trait_set_inited)rxstatervaluesr-)rr. __setstate__fs zHasTraits.__setstate__cOsvi}t|}|dkr.t|dtkr.|d}n|dkrB|jf|}t}x(|D] }t|||}||k rN|||<qNW|S)aV Retrieve trait values for one or more traits. This function can be called in one of three ways. In the first form, the user passes the names of one or more traits to be retrieved:: my_object.trait_get("trait_name1", "trait_name2") In the second form, the user passes a list of zero or more names of traits:: my_object.trait_get(["trait_name1", "trait_name2"]) In the final form, no trait names are passed, and all trait names and trait values are returned, subject to the given metadata filters:: my_object.trait_get(transient=True, frombicated=False) In all cases, a dictionary mapping trait names to trait values is returned. For the first two forms, if any name does not correspond to a defined trait, it is not included in the result. Parameters ---------- *names Names of the traits to look up, or a single positional argument providing a sequence of trait names. **metadata Metadata information used to filter the traits to return. This information is used only when no names are provided. Returns ------- result : dict A dictionary mapping the selected trait names to their corresponding values. rr)rtrrrobjectrB)rxnamesr@rFrmmissingrbr`r-r-r.rs(     zHasTraits.trait_getz!use "HasTraits.trait_get" insteadcOs |j||S)N)r)rxr)r@r-r-r.rNsz HasTraits.getc Ksj|sD|jdz&x |jD]\}}t|||qWWd|jdXn"x |jD]\}}t|||qNW|S)a7 Shortcut for setting object trait attributes. Treats each keyword argument to the method as the name of a trait attribute and sets the corresponding trait attribute to the value specified. This is a useful shorthand when a number of trait attributes need to be set on an object, or a trait attribute value needs to be set in a lambda function. For example, you can write:: person.trait_set(name='Bill', age=27) instead of:: person.name = 'Bill' person.age = 27 Parameters ---------- trait_change_notify : bool If **True** (the default), then each value assigned may generate a trait change notification. If **False**, then no trait change notifications will be generated. (see also: trait_setq) **traits : Key/value pairs, the trait attributes and their values to be set Returns ------- self : The method returns this object, after setting attributes. FNT)Z_trait_change_notifyr\setattr)rxrtraitsrbr`r-r-r.rs zHasTraits.trait_setz!use "HasTraits.trait_set" insteadcKs|jfd|i|S)Nr)r)rxrr,r-r-r.rsz HasTraits.setcKs|jfddi|S)a Shortcut for setting object trait attributes. Treats each keyword argument to the method as the name of a trait attribute and sets the corresponding trait attribute to the value specified. This is a useful shorthand when a number of trait attributes need to be set on an object, or a trait attribute value needs to be set in a lambda function. For example, you can write:: person.trait_setq(name='Bill', age=27) instead of:: person.name = 'Bill' person.age = 27 Parameters ---------- **traits : Key/value pairs, the trait attributes and their values to be set. No trait change notifications will be generated for any values assigned (see also: trait_set). Returns ------- self : The method returns this object, after setting attributes. rF)r)rxr,r-r-r. trait_setqszHasTraits.trait_setqNc Ks\g}|dkr|jf|}x>|D]6}yt||Wqttfk rR|j|YqXqW|S)aK Resets some or all of an object's trait attributes to their default values. Resets each of the traits whose names are specified in the *traits* list to their default values. If *traits* is None or omitted, the method resets all explicitly-defined object trait attributes to their default values. Note that this does not affect wildcard trait attributes or trait attributes added via add_trait(), unless they are explicitly named in *traits*. Parameters ---------- traits : list of strings Names of trait attributes to reset. Returns ------- unresetable : list of strings A list of attributes that the method was unable to reset, which is empty if all the attributes were successfully reset. N)rdelattrrr#rg)rxr,r@Z unresetablerbr-r-r. reset_traitss  zHasTraits.reset_traitscKs|jddd|jf|S)zF Returns the list of trait names to copy or clone by default. rcSs|dk S)NTr-)tr-r-r.8sz0HasTraits.copyable_trait_names..)rir)rxr@r-r-r.copyable_trait_names4szHasTraits.copyable_trait_namescCst|jjS)z_ Returns the list of all trait names, including implicitly defined traits. )rXr0r)rxr-r-r.all_trait_names;szHasTraits.all_trait_namescstj|jS)z Returns the list of trait names when calling the dir() builtin on the object. This enables tab-completion in IPython. )super__dir__r)rx)rr-r.r5AszHasTraits.__dir__c Ks|dkr|jf|}n,|dks*t|dkrB|j}|dk rBd|d<g}g}|dk}|dk} x|D]} y|j| } | jtkr|j| w`|j| } | jdkrw`t|| } | j }|dkrt j | } nH|dkrn>|dks|r|dkrt j | } n t j | |} n| rt j | } t || | Wq`|j| Yq`Xq`Wx|D]} yt|| } |j| j }|dkrjt j | } nP|dkrvnD|dks|r|dkrt j | } n t j | |} n| rt j | } t || | Wn|j| YnXq8W|S) a Copies another object's trait attributes into this one. Parameters ---------- other : object The object whose trait attribute values should be copied. traits : list of strings A list of names of trait attributes to copy. If None or unspecified, the set of names returned by trait_names() is used. If 'all' or an empty list, the set of names returned by all_trait_names() is used. memo : dict A dictionary of objects that have already been copied. copy : None | 'deep' | 'shallow' The type of copy to perform on any trait that does not have explicit 'copy' metadata. A value of None means 'copy reference'. Returns ------- unassignable : list of strings A list of attributes that the method was unable to copy, which is empty if all the attributes were successfully copied. Nrrtraits_to_copydeepZshallowr5r) r2rtr3r;r DeferredCopyrg base_traitrBr> copy_moduledeepcopyr+)rxotherr,memor>r@Z unassignabledeferredZ deep_copyZ shallow_copyrbr;r9r`Z copy_typer-r-r. copy_traitsGsh                    zHasTraits.copy_traitscKs|dkr i}|dkr"|jf|}n$|dks6t|dkrF|j}d|d<||d<|j|j}||t|<|j|j|j||||f||j |j |j |j |S)a Clones a new object from this one, optionally copying only a specified set of traits. Creates a new object that is a clone of the current object. If *traits* is None (the default), then all explicit trait attributes defined for this object are cloned. If *traits* is 'all' or an empty list, the list of traits returned by all_trait_names() is used; otherwise, *traits* must be a list of the names of the trait attributes to be cloned. Parameters ---------- traits : list of strings The list of names of the trait attributes to copy. memo : dict A dictionary of objects that have already been copied. copy : str The type of copy ``deep`` or ``shallow`` to perform on any trait that does not have explicit 'copy' metadata. A value of None means 'copy reference'. Returns ------- new : The newly cloned object. Nrrr6traits_copy_mode) r2rtr3rrrrr r?r!r"r#r$)rxr,r=r>r@rr-r-r. clone_traitss$  zHasTraits.clone_traitscCs|j||jd|jddS)z, Creates a deep copy of the object. r6r@)r=r,r>)rArN)rxr=r-r-r. __deepcopy__szHasTraits.__deepcopy__rec Ks2|dkr |}|j|}|j||||j||||S)aM Displays a user interface window for editing trait attribute values. Parameters ---------- view : View or string A View object (or its name) that defines a user interface for editing trait attribute values of the current object. If the view is defined as an attribute on this class, use the name of the attribute. Otherwise, use a reference to the view object. If this attribute is not specified, the View object returned by trait_view() is used. parent : toolkit control The reference to a user interface component to use as the parent window for the object's UI window. kind : str The type of user interface window to create. See the **traitsui.view.kind_trait** trait for values and their meanings. If *kind* is unspecified or None, the **kind** attribute of the View object is used. context : object or dictionary A single object or a dictionary of string/object pairs, whose trait attributes are to be edited. If not specified, the current object is used. handler : Handler A handler object used for event handling in the dialog box. If None, the default handler for Traits UI is used. id : str A unique ID for persisting preferences about this user interface, such as size and position. If not specified, no user preferences are saved. scrollable : bool Indicates whether the dialog box should be scrollable. When set to True, scroll bars appear on the dialog box if it is not large enough to display all of the items in the view at one time. Returns ------- A UI object. N) trait_viewr:trait_view_elements) rxviewparentkindcontextrr scrollablerr-r-r. edit_traitss3 zHasTraits.edit_traitscCsd|iS)z[ Returns the default context to use for editing or configuring traits. r(r-)rxr-r-r. trait_contextszHasTraits.trait_contextcCs|jj|||j|j|j|S)a Gets or sets a ViewElement associated with an object's class. If both *name* and *view_element* are specified, the view element is associated with *name* for the current object's class. (That is, *view_element* is added to the ViewElements object associated with the current object's class, indexed by *name*.) If only *name* is specified, the function returns the view element object associated with *name*, or None if *name* has no associated view element. View elements retrieved by this function are those that are bound to a class attribute in the class definition, or that are associated with a name by a previous call to this method. If neither *name* nor *view_element* is specified, the method returns a View object, based on the following order of preference: 1. If there is a View object named ``traits_view`` associated with the current object, it is returned. 2. If there is exactly one View object associated the current object, it is returned. 3. Otherwise, it returns a View object containing items for all the non-event trait attributes on the current object. Parameters ---------- name : str Name of a view element view_element : ViewElement View element to associate Returns ------- A view element. )r _trait_viewdefault_traits_viewrDvisible_traits)rxrb view_elementr-r-r.rC%s#zHasTraits.trait_viewcCs|j|||j|j|jdS)N)rLclass_default_traits_viewclass_trait_view_elementsclass_visible_traits)rDrbrOr-r-r.class_trait_viewQszHasTraits.class_trait_viewc Cst|tr|S|}|dkr dStd|rz|dkrl|j|}|dkrh|dk rht||d}t|rh|}|S||j|<dS|}t|tr|S|j} || kr|j|S|dk rt||d}t|r|}t|tr|St| dkr|j| dSddl m } | |ddgdS) zG Gets or sets a ViewElement associated with an object's class. Nrr)ViewOKZCancel)Zbuttons) rWr)r%rhrBrcontent filter_byrt traitsui.apirU) rDrbrO default_namerZtrait_selector_frrFrEr)rUr-r-r.rL\s@          zHasTraits._trait_viewcCs |jjS)zM Returns the name of the default traits view for the object's class. )rrP)rxr-r-r.rMszHasTraits.default_traits_viewcCstS)zD Returns the name of the default traits view for the class. )DefaultTraitsView)rDr-r-r.rPsz#HasTraits.class_default_traits_viewcCs(|jjt}t|tr|j}|j|S)a7 Returns a list of the names of all view elements associated with the current object's class. If *klass* is specified, the list of names is filtered such that only objects that are instances of the specified class are returned. Parameters ---------- klass : class A class, such that all returned names must correspond to instances of this class. Possible values include: * Group * Item * View * ViewElement * ViewSubElement )rr=rrWr[_init_trait_view_elementsrX)rxrrr-r-r. trait_viewss  zHasTraits.trait_viewscCs |jjS)z Returns the ViewElements object associated with the object's class. The returned object can be used to access all the view elements associated with the class. )rrQ)rxr-r-r.rDszHasTraits.trait_view_elementscCs |jt}t|tr|j}|S)z Returns the ViewElements object associated with the class. The returned object can be used to access all the view elements associated with the class. )r=rrWr[r\)rDrr-r-r.rQs  z#HasTraits.class_trait_view_elementsc Csddlm}dd|jD}|}|jt}x>|jD]2\}}||jkrTtd|||j|<|j|q6Wx(|D] }|j }|dk rr|j j |qrWt |t||S)z> Lazily Initialize the ViewElements object from a dictionary. r) ViewElementscSsg|]}t|jkr|qSr-)rr=)rrRr-r-r.rsz7HasTraits._init_trait_view_elements..z*Duplicate definition for view element '%s'N) Ztraitsui.view_elementsr^ __bases__r=rr\rWr#Zreplace_includerQparentsrgr+) rDr^rrZ elements_dictrbelementrRZparent_view_elementsr-r-r.r\s        z#HasTraits._init_trait_view_elementsc Ks|dk rNd} tj| ttjj|rNt|d} |jtj | j WdQRX|dkr\d}nd} tj| t|rddl m } |dkr|}| j ||j|||||| } | r|dk rt|d} tj| d d j|WdQRX| SdS) asCreates and displays a dialog box for editing values of trait attributes, as if it were a complete, self-contained GUI application. This method is intended for use in applications that do not normally have a GUI. Control does not resume in the calling application until the user closes the dialog box. The method attempts to open and unpickle the contents of *filename* before displaying the dialog box. When editing is complete, the method attempts to pickle the updated contents of the object back to *filename*. If the file referenced by *filename* does not exist, the object is not modified before displaying the dialog box. If *filename* is unspecified or None, no pickling or unpickling occurs. If *edit* is True (the default), a dialog box for editing the current object is displayed. If *edit* is False or None, no dialog box is displayed. You can use ``edit=False`` if you want the object to be restored from the contents of *filename*, without being modified by the user. Parameters ---------- filename : str The name (including path) of a file that contains a pickled representation of the current object. When this parameter is specified, the method reads the corresponding file (if it exists) to restore the saved values of the object's traits before displaying them. If the user confirms the dialog box (by clicking **OK**), the new values are written to the file. If this parameter is not specified, the values are loaded from the in-memory object, and are not persisted when the dialog box is closed. .. deprecated:: 6.0.0 view : View or str A View object (or its name) that defines a user interface for editing trait attribute values of the current object. If the view is defined as an attribute on this class, use the name of the attribute. Otherwise, use a reference to the view object. If this attribute is not specified, the View object returned by trait_view() is used. kind : str The type of user interface window to create. See the **traitsui.view.kind_trait** trait for values and their meanings. If *kind* is unspecified or None, the **kind** attribute of the View object is used. edit : bool Indicates whether to display a user interface. If *filename* specifies an existing file, setting *edit* to False loads the saved values from that file into the object without requiring user interaction. .. deprecated:: 6.2.0 context : object or dictionary A single object or a dictionary of string/object pairs, whose trait attributes are to be edited. If not specified, the current object is used handler : Handler A handler object used for event handling in the dialog box. If None, the default handler for Traits UI is used. id : str A unique ID for persisting preferences about this user interface, such as size and position. If not specified, no user preferences are saved. scrollable : bool Indicates whether the dialog box should be scrollable. When set to True, scroll bars appear on the dialog box if it is not large enough to display all of the items in the view at one time. Returns ------- True on success. NzFRestoring from pickle will not be supported starting with traits 7.0.0rbTzXThe edit argument to configure_traits is deprecated, and will be removed in Traits 7.0.0r)toolkitwbr)r)rrrospathexistsopenr?pickle UnpicklerloadrYrcZview_applicationrCPicklerdump)rxfilenamerErGZeditrHrrrIrmessagefdrcrr-r-r.configure_traitss6X       zHasTraits.configure_traitscCs|jttd}|j|S)zReturns an alphabetically sorted list of the names of non-event trait attributes associated with the current object. )reditable)rr!r"r)rxr)r-r-r.editable_traitsszHasTraits.editable_traitscCs|jttd}|j|S)zReturns an alphabetically sorted list of the names of non-event trait attributes associated with the current class. )rrr)class_trait_namesr!r"r)rDr)r-r-r.class_editable_traitsszHasTraits.class_editable_traitscCs|jttdS)zReturns an alphabetically sorted list of the names of non-event trait attributes associated with the current object, that should be GUI visible )rvisible)rr!r")rxr-r-r.rNszHasTraits.visible_traitscCs|jttdS)zReturns an alphabetically sorted list of the names of non-event trait attributes associated with the current class, that should be GUI visible )rrv)rtr!r")rDr-r-r.rRszHasTraits.class_visible_traitsc Ks6t|dkr|jf|}n |jtd}t|dkr>tddSg}tdd|Dd}d|}|jx|D]}yTtt||jd d }t||krd |d|d d ||d d  df}Wnd}YnX|dj |} |r|j d| ||j |j j fqn|j d| |fqnWtd j|dS)aPrints the values of all explicitly-defined, non-event trait attributes on the current object, in an easily readable format. Parameters ---------- show_help : bool Indicates whether to display additional descriptive information. r)rreNcSsg|] }t|qSr-)rt)rxr-r-r.rsz*HasTraits.print_traits..rN z\nz%s...%srHrz :z%s %s The value must be %s.z%s %s)rtrr!printmaxrreprrBreplaceljustrgr9rinfor) rxZ show_helpr@r)rFpadmaxvalrbr`lnamer-r-r. print_traitss4      zHasTraits.print_traitsr9c Cs$t|tkr2x |D]}|j||||||qWdS|p8d}|r|dkrR|jd}n"|j|d} | dkrjdS| jd}|dk rx.t|D]"\} } | j|r|| =| jPqWdS|dkr|jd}n|j|djd}xH|D]} | j|rPqW|j||||} |r|j d| n |j | dS)aHCauses the object to invoke a handler whenever a trait attribute is modified, or removes the association. Multiple handlers can be defined for the same object, or even for the same trait attribute on the same object. If *name* is not specified or is None, *handler* is invoked when any trait attribute on the object is changed. Parameters ---------- handler : function A trait notification function for the attribute specified by *name*. name : str Specifies the trait attribute whose value changes trigger the notification. remove : bool If True, removes the previously-set association between *handler* and *name*; if False (the default), creates the association. NrFrTrHr) rrX_on_trait_changer_trait enumerateequalsdisposerinsertrg) rxrrbrrprioritytargetname_ir}r;iZnotifierrr-r-r.rs<         zHasTraits._on_trait_change)rrcCs$t|}tj|||t||ddS)a Causes the object to invoke a handler whenever a trait attribute matching a specified pattern is modified, or removes the association. The *expression* parameter can be a single string or an Expression object. A list of expressions is also accepted. When *expression* is a string, its content should follow Traits Mini Language semantics: ============================== ====================================== Expression Meaning ============================== ====================================== ``item1.item2`` Observes trait *item2* on the object under trait *item1*. Changes to either *item1* or *item2* cause a notification to be fired. ``item1:item2`` Similar to the above, except changes to *item1* will not fire events (the ':' indicates no notifications). ``[item1, item2, ..., itemN]`` A list which matches any of the specified items. Each item can itself be an expression. ``items`` Special keyword for observing a trait named *items* or items inside a list / dict / set. ``+metadata_name`` Matches any trait on the object having *metadata_name* metadata. ============================== ====================================== All spaces will be ignored. The :py:class:`ObserverExpression` object supports the above features and more. Parameters ---------- handler : callable(event) A callable that will be invoked when the observed trait changes. It must accept one argument, which is an event object providing information about the change. See :py:mod:`traits.observation.events` for details. expression : str or list or ObserverExpression A description of what traits are being observed. If this is a list, each item must be a string or an Expression. remove : boolean, optional Whether to remove the event handler. Default is to add the event handler. dispatch : str, optional A string indicating how the handler should be run. Default is to run on the same thread where the change occurs. Possible values are: =========== ======================================================= value dispatch =========== ======================================================= ``same`` Run notifications on the same thread where the change occurs. The notifications are executed immediately. ``ui`` Run notifications on the UI thread. If the current thread is the UI thread, the notifications are executed immediately; otherwise, they are placed on the UI event queue. =========== ======================================================= Raises ------ NotifierNotFound When attempting to remove a handler that doesn't exist. )r(rr dispatcherrN)rrapply_observers_ObserverDispatchers)rxrrrrrr-r-r.r sFzHasTraits.observec Cst|trtj|dks |dkr8|j||||||dSddlm}m} m} m } t|t rx$|D]} |j || |||||dq`WdS|pdj }|r(|j j|} | dk r| j|}|dk rxt|D]X\}}|j|r||=t|dkr | |=t| dkr |j |=|jj||jPqWn|j j|i} | j|g}xj|D]}|j|rHPqHW| |||d|}| || |tj|||||jdj}||_|j||j|dS)a4-Causes the object to invoke a handler whenever a trait attribute matching a specified pattern is modified, or removes the association. Multiple handlers can be defined for the same object, or even for the same trait attribute on the same object. If *name* is not specified or is None, *handler* is invoked when any trait attribute on the object is changed. The *name* parameter is a single *xname* or a list of *xname* names, where an *xname* is an extended name of the form:: xname2[('.'|':') xname2]* An *xname2* is of the form:: ( xname3 | '['xname3[','xname3]*']' ) ['*'] An *xname3* is of the form:: xname | ['+'|'-'][name] | name['?' | ('+'|'-')[name]] A *name* is any valid Python attribute name. The semantic meaning of this notation is as follows: ================================ ====================================== expression meaning ================================ ====================================== ``item1.item2`` means *item1* is a trait containing an object (or objects if *item1* is a list or dict) with a trait called *item2*. Changes to either *item1* or *item2* cause a notification to be generated. ``item1:item2`` means *item1* is a trait containing an object (or objects if *item1* is a list or dict) with a trait called *item2*. Changes to *item2* cause a notification to be generated, while changes to *item1* do not (i.e., the ':' indicates that changes to the *link* object should not be reported). ``[ item1, item2, ..., itemN ]`` A list which matches any of the specified items. Note that at the topmost level, the surrounding square brackets are optional. ``name?`` If the current object does not have an attribute called *name*, the reference can be ignored. If the '?' character is omitted, the current object must have a trait called *name*, otherwise an exception will be raised. ``prefix+`` Matches any trait on the object whose name begins with *prefix*. ``+metadata_name`` Matches any trait on the object having *metadata_name* metadata. ``-metadata_name`` Matches any trait on the object which does not have *metadata_name* metadata. ``prefix+metadata_name`` Matches any trait on the object whose name begins with *prefix* and which has *metadata_name* metadata. ``prefix-metadata_name`` Matches any trait on the object whose name begins with *prefix* and which does not have *metadata_name* metadata. ``+`` Matches all traits on the object. ``pattern*`` Matches object graphs where *pattern* occurs one or more times (useful for setting up listeners on recursive data structures like trees or linked lists). ================================ ====================================== Some examples of valid names and their meaning are as follows: ======================= =============================================== example meaning ======================= =============================================== ``foo,bar,baz`` Listen for trait changes to *object.foo*, *object.bar*, and *object.baz*. ``['foo','bar','baz']`` Equivalent to 'foo,bar,baz', but may be more useful in cases where the individual items are computed. ``foo.bar.baz`` Listen for trait changes to *object.foo.bar.baz* and report changes to *object.foo*, *object.foo.bar* or *object.foo.bar.baz*. ``foo:bar:baz`` Listen for changes to *object.foo.bar.baz*, and only report changes to *object.foo.bar.baz*. ``foo.[bar,baz]`` Listen for trait changes to *object.foo.bar* and *object.foo.baz*. ``[left,right]*.name`` Listen for trait changes to the *name* trait of each node of a tree having *left* and *right* links to other tree nodes, and where *object* the method is applied to the root node of the tree. ``+dirty`` Listen for trait changes on any trait in the *object* which has the 'dirty' metadata set. ``foo.+dirty`` Listen for trait changes on any trait in *object.foo* which has the 'dirty' metadata set. ``foo.[bar,-dirty]`` Listen for trait changes on *object.foo.bar* or any trait on *object.foo* which does not have 'dirty' metadata set. ======================= =============================================== Note that any of the intermediate (i.e., non-final) links in a pattern can be traits of type Instance, List or Dict. In the case of List and Dict traits, the subsequent portion of the pattern is applied to each item in the list, or value in the dictionary. For example, if the self.children is a list, 'children.name' listens for trait changes to the *name* trait for each item in the self.children list. Note that items added to or removed from a list or dictionary in the pattern will cause the *handler* routine to be invoked as well, since this is treated as an *implied* change to the item's trait being monitored. The signature of the *handler* supplied also has an effect on how changes to intermediate traits are processed. The five valid handler signatures are: 1. handler() 2. handler(new) 3. handler(name,new) 4. handler(object,name,new) 5. handler(object,name,old,new) For signatures 1, 4 and 5, any change to any element of a path being listened to invokes the handler with information about the particular element that was modified (e.g., if the item being monitored is 'foo.bar.baz', a change to 'bar' will call *handler* with the following information: - object: object.foo - name: bar - old: old value for object.foo.bar - new: new value for object.foo.bar If one of the intermediate links is a List or Dict, the call to *handler* may report an *_items* changed event. If in the previous example, *bar* is a List, and a new item is added to *bar*, then the information passed to *handler* would be: - object: object.foo - name: bar_items - old: Undefined - new: TraitListEvent whose *added* trait contains the new item added to *bar*. For signatures 2 and 3, the *handler* does not receive enough information to discern between a change to the final trait being listened to and a change to an intermediate link. In this case, the event dispatcher will attempt to map a change to an intermediate link to its effective change on the final trait. This only works if all of the intermediate links are single values (such as an Instance or Any trait) and not Lists or Dicts. If the modified intermediate trait or any subsequent intermediate trait preceding the final trait is a List or Dict, then a TraitError is raised, since the effective value for the final trait cannot in general be resolved unambiguously. To prevent TraitErrors in this case, use the ':' separator to suppress notifications for changes to any of the intermediate links. Handler signature 1 also has the special characteristic that if a final trait is a List or Dict, it will automatically handle '_items' changed events for the final trait as well. This can be useful in cases where the *handler* only needs to know that some aspect of the final trait has been changed. For all other *handler* signatures, you must explicitly specify the 'xxx_items' trait if you want to be notified of changes to any of the items of the 'xxx' trait. Parameters ---------- handler : function A trait notification function for the *name* trait attribute, with one of the signatures described below. name : str The name of the trait attribute whose value changes trigger the notification. The *name* can specify complex patterns of trait changes using an extended *name* syntax, which is described below. remove : bool If True, removes the previously-set association between *handler* and *name*; if False (the default), creates the association. dispatch : str A string indicating the thread on which notifications must be run. Possible values are: =========== ======================================================= value dispatch =========== ======================================================= ``same`` Run notifications on the same thread as this one. ``ui`` Run notifications on the UI thread. If the current thread is the UI thread, the notifications are executed immediately; otherwise, they are placed on the UI event queue. ``fast_ui`` Alias for ``ui``. ``new`` Run notifications in a new thread. =========== ======================================================= See Also -------- HasTraits.observe : A newer API for defining traits notifications. Nr)TraitsListenerListenerParserListenerHandlerListenerNotifyWrapper)rbrrrr>rrr)rZwrapped_handler_refrrr>Z handler_type)rWrextended_trait_patmatchrZtraits_listenerrrrrrXrKstripr=rNrrrtr unregisterrrirrrregisterrg)rxrrbrrrr>rrrrrrr[rrrZlnwrr-r-r.rKl sh^                zHasTraits.on_trait_changec sh|dkr |}|j|o|j|}|r|jj|}|dk rt||f}||kr||=t|dkr|=|j|j|dd|r|j|j|ddd|r|j|||dddSdd|jj |i}t||f}fd d } t j || |f} ||krNt|dkr4|j|j||r4|j|j|d| ||<t ||t |||rd|j|||ddS) aSynchronizes the value of a trait attribute on this object with a trait attribute on another object. In mutual synchronization, any change to the value of the specified trait attribute of either object results in the same value being assigned to the corresponding trait attribute of the other object. In one-way synchronization, any change to the value of the attribute on this object causes the corresponding trait attribute of *object* to be updated, but not vice versa. For ``List`` traits, the list's items are also synchronized, so that mutations to this trait's list will be reflected in the synchronized list (and vice versa in the case of mutual synchronization). For ``Dict`` and ``Set`` traits, items are not synchronized. Parameters ---------- name : str Name of the trait attribute on this object. object : object The object with which to synchronize. alias : str Name of the trait attribute on *other*; if None or omitted, same as *name*. mutual : bool or int Indicates whether synchronization is mutual (True or non-zero) or one-way (False or zero) remove : bool or int Indicates whether synchronization is being added (False or zero) or removed (True or non-zero) NrT)rrFcSsdx^t|jD]N\}}|dkrx*t|jD]\}}||dkr,||=q,Wt|dkr||=qWdS)Nrer)rXr\rt)rrrorrbr`r-r-r._sync_trait_listener_deleted s   z:HasTraits.sync_trait.._sync_trait_listener_deletedcs |S)Nr-)r)rrr-r.r1 sz&HasTraits.sync_trait..)_is_list_trait_get_sync_trait_inforNrrtr_sync_trait_modified_sync_trait_items_modified sync_traitrirrr+rB) rx trait_namer(aliasZmutualrZis_listrrocallbackr`r-)rrr.r sN"       zHasTraits.sync_traitcCs.t|dd}|dkr*i|jd<}i|d<|S)N__sync_trait__re)rBr=)rxrr-r-r.r s  zHasTraits._get_sync_trait_infoc Csz|j}||krdS|d}d||<xL||jD]<\}}|}||jdkr0yt|||Wq0Yq0Xq0W||=dS)Nre)rr&rr+)rxr(rbrrrlocked object_namer-r-r.r s zHasTraits._sync_trait_modifiedc Cs|j}|t|j}|dd}|j}|d}d||<xT||jD]D\}} |}| |jdkrDy|jt|| ||<WqDYqDXqDW||=dS)Nrrei)indexrtremovedrr&raddedrB) rxr(rbrr5Zn0Zn1rrrr-r-r.r s  z$HasTraits._sync_trait_items_modifiedcCs |j|j}|dk o|jtjkS)N)r9rZdefault_value_typerZtrait_list_object)rxrrr-r-r.r# s zHasTraits._is_list_traitc GsJt|dkrtdt|dkr*t|}n t|d}|j}|dk rz|jr^|j|d|j|jrz|j|dt |||j |d}|j }t |||<}|dk r|j d}|dk r|j dj|nl|j}t|d |t|d |g}t||||j|jjd d d |D}t|dkr6t|j d||dkrF||_dS)aAdds a trait attribute to this object. Parameters ---------- name : str Name of the attribute to add. *trait : Trait or a value that can be converted to a trait by Trait(). Trait definition for *name*. If more than one value is specified, it is equivalent to passing the entire list of values to Trait(). rz"No trait definition was specified.rNrrJFTz _%s_changedz _%s_firedrcSsg|]}|dk r|qS)Nr-)rrr-r-r.ri sz'HasTraits.add_trait..)rtrrr(rr add_traitrrr'r_instance_traitsrArrrrGrrgr1rNr trait_added) rxrbr;rZ old_trait itrait_dictZ old_notifiersrDr~r-r-r.r* s8         zHasTraits.add_traitcCsz|j|d}|dk rv|j}|dk rJ|jr6|j|d|jrJ|j|d||jkr\|j|=|j}||krv||=dSdS)a Removes a trait attribute from this object. Parameters ---------- name : str Name of the attribute to remove. Returns ------- result : bool True if the trait was successfully removed. rNrrJTF)rrr remove_traitrr=r)rxrbr;rrr-r-r.rs s  zHasTraits.remove_traitcCs2d}|r d}|j||}| s&|dkr*|St|S)aReturns the trait definition for the *name* trait attribute. If *force* is False (the default) and *name* is the name of an implicitly defined trait attribute that has never been referenced explicitly (i.e., has not yet been defined), the result is None. In all other cases, the result is the trait definition object associated with *name*. If *copy* is True, and a valid trait definition is found for *name*, a copy of the trait found is returned. In all other cases, the trait definition found is returned unmodified (the default). Parameters ---------- name : str Name of the attribute whose trait definition is to be returned. force : bool Indicates whether to return a trait definition if *name* is not explicitly defined. copy : bool Indicates whether to return the original trait definition or a copy. rrNrr)rrA)rxrbforcer>moderFr-r-r.r; s zHasTraits.traitcCs |j|dS)a<Returns the base trait definition for a trait attribute. This method is similar to the trait() method, and returns a different result only in the case where the trait attribute defined by *name* is a delegate. In this case, the base_trait() method follows the delegation chain until a non-delegated trait attribute is reached, and returns the definition of that attribute's trait as the result. Parameters ---------- name : str Name of the attribute whose trait definition is returned. rH)r)rxrbr-r-r.r9 szHasTraits.base_traitcCs|j|j|||S)zn Validates whether a value is legal for a trait. Returns the validated value if it is valid. )r9r)rxrbr`r-r-r.validate_trait szHasTraits.validate_traitc Ks|jj}x0|jjD] \}}|dddkr|||<qWx4|jjD]&}||krH|j|}|dk rH|||<qHWt|dkr|Sx0t|jD] \}}t |t k rt |||<qWi}xD|jD]8\}}x.|jD]\}}|t ||dsPqW|||<qW|S)a1Returns a dictionary containing the definitions of all of the trait attributes of this object that match the set of *metadata* criteria. Note that any traits with a name containing the suffix "_items" are always excluded. The keys of the returned dictionary are the trait attribute names, and the values are their corresponding trait definition objects. If no *metadata* information is specified, then all explicitly defined trait attributes defined for the object are returned. Otherwise, the *metadata* keyword dictionary is assumed to define a set of search criteria for selecting trait attributes of interest. The *metadata* dictionary keys correspond to the names of trait metadata attributes to examine, and the values correspond to the values the metadata attribute must have in order to be included in the search results. The *metadata* values either may be simple Python values like strings or integers, or may be lambda expressions or functions that return True if the trait attribute is to be included in the result. A lambda expression or function must receive a single argument, which is the value of the trait metadata attribute being tested. If more than one metadata keyword is specified, a trait attribute must match the metadata values of all keywords to be included in the result. Parameters ---------- **metadata : Criteria for selecting trait attributes. rNrri) r/r>rr\r=rr;rtrXrrrwrB) rxr@r,rbZtrtr; meta_name meta_evalrFr-r-r.r, s*       zHasTraits.traitscKst|dkr|jjSi}x0t|jD] \}}t|tk r(t|||<q(WxF|jjD]8\}}x.|jD]\}}|t||dsjPqjW|||<qXW|S)aReturns a dictionary containing the definitions of all of the trait attributes of the class that match the set of *metadata* criteria. The keys of the returned dictionary are the trait attribute names, and the values are their corresponding trait definition objects. If no *metadata* information is specified, then all explicitly defined trait attributes defined for the class are returned. Otherwise, the *metadata* keyword dictionary is assumed to define a set of search criteria for selecting trait attributes of interest. The *metadata* dictionary keys correspond to the names of trait metadata attributes to examine, and the values correspond to the values the metadata attribute must have in order to be included in the search results. The *metadata* values either may be simple Python values like strings or integers, or may be lambda expressions or functions that return **True** if the trait attribute is to be included in the result. A lambda expression or function must receive a single argument, which is the value of the trait metadata attribute being tested. If more than one metadata keyword is specified, a trait attribute must match the metadata values of all keywords to be included in the result. Parameters ---------- **metadata : Criteria for selecting trait attributes. rN) rtr/r>rXr\rrrwrB)rDr@rFrrrbr;r-r-r.r s    zHasTraits.class_traitscKst|jf|jS)aReturns a list of the names of all trait attributes whose definitions match the set of *metadata* criteria specified. This method is similar to the traits() method, but returns only the names of the matching trait attributes, not the trait definitions. Parameters ---------- **metadata : Criteria for selecting trait attributes. )rXr,r)rxr@r-r-r.rA s zHasTraits.trait_namescKst|jf|jS)aReturns a list of the names of all trait attributes whose definitions match the set of *metadata* criteria specified. This method is similar to the traits() method, but returns only the names of the matching trait attributes, not the trait definitions. Parameters ---------- **metadata : Criteria for selecting trait attributes. )rXrr)rDr@r-r-r.rtO s zHasTraits.class_trait_namescCs:t|}|jj|t}||j|<||kr6|j|||dS)z9 Explicitly sets the value of a cached property. N)rr=rNrr)rxrbr`r old_valuer-r-r.r^ s  zHasTraits._set_traits_cachecCs|j||jjt|tdS)z< Explicitly flushes the value of a cached property. N)rr=rrr)rxrbr`r-r-r.rg szHasTraits._flush_traits_cachecCsH|dddkrH|dddkrH|dkr,tS|r4tStd|jj|f|dddkr|j|ddd}|dk r|jd krt|S|j}x|d D]}||dt |kr||}|j}t |d |t |d |g}t ||||j |j d dd|D}t |dkr(t|}t|jd||SqWtd||jjfdS)zu Return the trait definition for a specified name when there is no explicit definition in the class. NrHrIrz!'%s' object has no attribute '%s'rrJrr6rqz _%s_changedz _%s_firedrcSsg|]}|dk r|qS)Nr-)rrr-r-r.r sz.HasTraits.__prefix_trait__..TzHTrait class look-up failed for attribute '%s' for an object of type '%s'rrrrr)r any_traitrrr*rrrAr1rtrGrrgrNrr SystemError)rxrbis_setr;rrurDr~r-r-r.__prefix_trait__n s:   zHasTraits.__prefix_trait__cCs|j||ddS)z/ Add (Java-style) event listener to an object. FN)_trait_listener)rxr(rur-r-r.add_trait_listener szHasTraits.add_trait_listenercCs|j||ddS)z2 Remove (Java-style) event listener to an object. TN)r)rxr(rur-r-r.remove_trait_listener szHasTraits.remove_trait_listenercCs|d ddkr|d7}t|}|j}x|j|D]}|d||kr2|d ddkr||d }||kr|jt||||dn|dkr|jt|||dq2|dd dkr2||d }||kr|jt||||dq2|dkr2|jt|||dq2WdS)NrrJZ_changed)rrrZ_firedrriiii)rtr/_each_trait_methodrrB)rxr(rurrmr,rbZ short_namer-r-r.r s,  zHasTraits._trait_listenerccsPi}xF|jjD]:}x4|jjD]&\}}t|r||krd||<|VqWqWdS)zD Generates each (name, method) pair for a specified object. TN)r__mro__r=r\rC)rxr(rrrbrEr-r-r.r s zHasTraits._each_trait_methodcCsT|j|}|dk r0x|D]}|j|ddiqW|dk rPx|D]}|j|q>WdS)zK Handles adding/removing listeners for a generic 'Instance' trait. NrT)rprK)rxrbrrrkrr-r-r._instance_changed_handler s   z#HasTraits._instance_changed_handlercCs`|j|}x*|D]"}x|D]}|j|ddiqWqWx$|D]}x|D]}|j|qFWq.)rr4)rxrbr-)rxr.rp s z HasTraits._get_instance_handlerscCsZxT|jjjD]D\}}|ddkr|d}|dr|jt|||dd|ddqWd S) z Initializes the object's statically parsed, but dynamically registered, traits listeners (called at object creation and unpickling times). rrErrrTr)r>rN)rr2r\rKrB)rxrbdataconfigr-r-r.r! s z$HasTraits._post_init_trait_listenerscCs:x4|jjjD]$\}}t|d|d|f|qWdS)z Initializes the object's statically parsed, but dynamically registered, traits listeners (called at object creation and unpickling times). z_init_trait_%s_listenerrN)rr2r\rB)rxrbrr-r-r.r! szHasTraits._init_trait_listenerscCs,|ds(|jt|||dd|dddS)z\ Sets up the listener for a method with the @on_trait_change decorator. rrTr)r>rN)rKrB)rxrbrGrr-r-r._init_trait_method_listener) s z%HasTraits._init_trait_method_listenercs(t|fdd}|j|||ddS)zJ Sets up the listener for an event with on_trait_change metadata. cst|ddS)NT)r+)rx)rbr-r.notify9 sz4HasTraits._init_trait_event_listener..notify)rN)rrK)rxrbrGrrr-)rbr._init_trait_event_listener5 sz$HasTraits._init_trait_event_listenercsxdkrt|fdd}nFdt|fdd}|j||d|dt|fd d}|j|||d dS) zI Sets up the listener for a property with 'depends_on' metadata. Ncs|jddS)N)r)rx)rbr-r.rD sz7HasTraits._init_trait_property_listener..notifyz:oldcs.|j}|jt}|tkr*|jd|<dS)N)r=rNrr)rxr[r)r cached_oldr-r. pre_notifyK s z;HasTraits._init_trait_property_listener..pre_notifyT)rrcs&|jjt}|tk r"|j|dS)N)r=rrr)rxr)rrbr-r.rV s)r)rrK)rxrbrGrrrrr-)rrrbr._init_trait_property_listener? sz'HasTraits._init_trait_property_listenercsZ|j|}t|jddt|fdd}|j|||d||jjti<dS)z4 Sets up the listener for a delegate trait. rzrcs|j|d||dS)N)r)rxr(Z notify_namerr)rbtarget_name_lenr-r.rd sz7HasTraits._init_trait_delegate_listener..notify)rNrr)_trait_delegate_namertsplitrrKr=rir)rxrbrGrZ name_patternrr-)rbrr.r^ s  z'HasTraits._init_trait_delegate_listenercCs|jjti}|r`||kr\|j|||j||jj|ddd||=t|dkr\|jt=dS||kr|j|d|jj|ddS)zK Removes a delegate listener when the local delegate value is set. rT)rrN) r=rirrKrrr2rtr)rxrbrr[r-r-r._remove_trait_delegate_listenerm s z)HasTraits._remove_trait_delegate_listenerc Cs\xV|jjjD]F\}}x<|D]4}|dstj||d|||dt|ddqWqWdS)z= Initialize observers prior to setting object state. rrrr)r(rrrN)rr3r\rrr)rxrbrr%r-r-r.r  s  zHasTraits._init_trait_observersc Cs\xV|jjjD]F\}}x<|D]4}|drtj||d|||dt|ddqWqWdS)z: Initialize observers after setting object state. rrrr)r(rrrN)rr3r\rrr)rxrbrr%r-r-r.r" s  z$HasTraits._post_init_trait_observerscCs*|ddkr&d|dd|jj|f}|S)z_ Returns the fully-formed 'on_trait_change' name for a specified delegate. rrqz%s%s%sNrrrr)rZ __prefix__)rxrbrr-r-r.r s   zHasTraits._trait_delegate_name)F)F)T)T)T)N)NNN)NNN)NNNNNreN)NN)NN)N)NNNNNNreN)F)NFr9FN)NFr9FFN)NTF)FF)re)re)`r*r+r,rrZ_traits_cache__rrrrrrrrZtrait_modifiedrrr rrr rr^rrr'rr$rNrrr-r/r2r3r5r?rArBrJrKrCrSrLrMrPr]rDrQr\rqrsrurNrRrrrrKZon_trait_eventrrrrrrrr;r9rr,rrrtrrrrrrrrrrrpr!rrrrrrr r"r __classcell__r-r-)rr.r]+s   " d   5 9 -  #  Z 1  ; , M   ' u   0 DS # bI' !> 1  A         r]) metaclassc@seZdZdZeZdS)HasStrictTraitsa This class guarantees that any object attribute that does not have an explicit or wildcard trait definition results in an exception. This feature can be useful in cases where a more rigorous software engineering approach is being used than is typical for Python programs. It also helps prevent typos and spelling mistakes in attribute names from going unnoticed; a misspelled attribute name typically causes an exception. N)r*r+r,rrrJr-r-r-r.r srcs eZdZdZfddZZS)HasRequiredTraitsa This class builds on the functionality of HasStrictTraits and ensures that any object attribute with `required=True` in its metadata must be passed as an argument on object initialization. This can be useful in cases where an object has traits which are required for it to function correctly. Raises ------ TraitError If a required trait is not passed as an argument. Examples -------- A class with required traits: >>> class RequiredTest(HasRequiredTraits): ... required_trait = Any(required=True) ... non_required_trait = Any() Creating an instance of a HasRequiredTraits subclass: >>> test_instance = RequiredTest(required_trait=13, non_required_trait=11) >>> test_instance2 = RequiredTest(required_trait=13) Forgetting to specify a required trait: >>> test_instance = RequiredTest(non_required_trait=11) traits.trait_errors.TraitError: The following required traits were not provided: required_trait. c sHfdd|jddD}|r6tdjdjt|tjfdS)Ncsg|]}|kr|qSr-r-)rrb)r,r-r.r sz.HasRequiredTraits.__init__..T)requiredz4The following required traits were not provided: {}.z, )rr#formatrsortedr4ry)rxr,Zmissing_required_traits)r)r,r.ry s zHasRequiredTraits.__init__)r*r+r,rryrr-r-)rr.r src@s eZdZdZedddZeZdS)HasPrivateTraitsaN This class ensures that any public object attribute that does not have an explicit or wildcard trait definition results in an exception, but "private" attributes (whose names start with '_') have an initial value of **None**, and are not type-checked. This feature is useful in cases where a class needs private attributes to keep track of its internal object state, which are not part of the class's public API. Such attributes do not need to be type-checked, because they are manipulated only by the (presumably correct) methods of the class itself. T)rrN)r*r+r,rrrIrrJr-r-r-r.r s  rc@seZdZdZdS)ABCMetaHasTraitsz A MetaHasTraits subclass which also inherits from abc.ABCMeta. .. note:: The ABCMeta class is cooperative and behaves nicely with MetaHasTraits, provided it is inherited first. N)r*r+r,rr-r-r-r.r src@seZdZdZdS) ABCHasTraitsz A HasTraits subclass which enables the features of Abstract Base Classes (ABC). See the 'abc' module in the standard library for more information. N)r*r+r,rr-r-r-r.rsrc@seZdZdZeZdS)ABCHasStrictTraitsz A HasTraits subclass which behaves like HasStrictTraits but also enables the features of Abstract Base Classes (ABC). See the 'abc' module in the standard library for more information. N)r*r+r,rrrJr-r-r-r.rsrc@s eZdZdZedddZdS)SingletonHasTraitsz4 Singleton class that support trait attributes. zXSingletonHasTraits has been deprecated and will be removed in the future. Avoid using itcOs$d|jkrtj|f|||_|jS)N _the_instance)r=r]rr)rDrr,r-r-r.r2s zSingletonHasTraits.__new__N)r*r+r,rr$rr-r-r-r.r.src@s eZdZdZedddZdS)SingletonHasStrictTraitszq Singleton class that supports strict trait attributes. Non-trait attributes generate an exception. z^SingletonHasStrictTraits has been deprecated and will be removed in the future. Avoid using itcOstj|f||S)N)rr)rDrr,r-r-r.r@sz SingletonHasStrictTraits.__new__N)r*r+r,rr$rr-r-r-r.r:src@s eZdZdZedddZdS)SingletonHasPrivateTraitszf Singleton class that supports trait attributes, with private attributes being unchecked. z_SingletonHasPrivateTraits has been deprecated and will be removed in the future. Avoid using itcOstj|f||S)N)rr)rDrr,r-r-r.rKsz!SingletonHasPrivateTraits.__new__N)r*r+r,rr$rr-r-r-r.rFsrc@s eZdZdZedZddZdS)VetoablezB Defines a 'vetoable' request object and an associated event. FcCs|j|dS)N)Z_trait_veto_notify)rxr%r-r-r. _veto_changedXszVetoable._veto_changedN)r*r+r,rrZvetorr-r-r-r.rQsrc@s$eZdZdZedefddZdS) MetaInterfacez Meta class for interfaces. Interfaces are simple ABCs with the following features:- 1) They cannot be instantiated (they are interfaces, not implementations!). 2) Calling them is equivalent to calling 'adapt'. z'use "adapt(adaptee, protocol)" instead.cCsddlm}||||dS)z Attempt to adapt the adaptee to this interface. Note that this means that (intentionally ;^) that interfaces cannot be instantiated! r)adapt)r)Ztraits.adaptation.apir)rxZadapteerrr-r-r.r{is zMetaInterface.__call__N)r*r+r,rr$rr{r-r-r-r.r_src@seZdZdZdS) Interfacez( The base class for all interfaces. N)r*r+r,rr-r-r-r.rwsrcsTddlm}tdkr ddSx"D]}tt||s&tdq&Wfdd}|S)z Class decorator to declare the protocols that a class provides. Parameters ---------- *protocols : A list of protocols (Interface classes or Python ABCs) that the decorated class provides. r)ABCMetacSs|S)Nr-)rr-r-r.r1szprovides..zOAll arguments to 'provides' must be subclasses of Interface or be a Python ABC.csNxD]}t|j||qWtrJddlm}tjdtdd||t|S)Nr)check_implementszIn the future, the @provides decorator will not perform interface checks. Set has_traits.CHECK_INTERFACES to 0 to suppress this warning.rH)r)rrCHECK_INTERFACESZinterface_checkerrrrr)rrr) protocolsr-r. wrapped_classs   zprovides..wrapped_class)abcrrtr rr#)rrrrr-)rr.provides|s     rcCs t|tS)z+ Return True if the class is an Interface. )rWr)rr-r-r. isinterfacesrc@seZdZdZdS)r_z A class that implemented ISerializable requires that all HasTraits objects saved as part of its state also implement ISerializable. N)r*r+r,rr-r-r-r.r_sr_)r5r6r7)r6r8)N)Fr9)FF)~rrr>r:rTrerirerrrrrerrZadaptation.adaptation_errorr constantsrrZctraitrr Zctraitsr Z observationr rr,r r rrZ trait_typesrrrrrrZtrait_notifiersrrrrrrrZ trait_baserrrr r!r"Z trait_errorsr#Zutil.deprecatedr$Zutil._traitsui_helpersr%Ztrait_convertersr&r'r(rABCr)r|rrrrrrrfr[rr8compilerrrZ dispatch_samerrArGrSrCrZrprvrwrrrrrZ _HasTraitsrrrrrrKrrrr]rrrrrrrrrrrZ VetoableEventrrrrr_r-r-r-r. s      $         &   (#=?c !, 0< 1     3