a 7anQ@sdZddlmZddlZddlZddlmZmZmZm Z ddl m Z m Z m Z mZmZmZmZmZmZddlmZmZddlmZGd d d eZGd d d eZGd dde ZGdddeZGdddeZdS)z/A base class for objects that are configurable.)deepcopyN)ConfigLazyConfigValueDeferredConfig_is_section_key) Any HasTraitsInstance ContainerDictobserveobserve_compatdefaultvalidate)indentwrap_paragraphs)dedentc@s eZdZdS)ConfigurableErrorN__name__ __module__ __qualname__rr.notice_config_override) popgetrrsuperr__init__setr _load_configZ unobservesetattr)selfr#rrr$r __class__r"rr(2s       zConfigurable.__init__csfddtjDS)zreturn section names as a listcs&g|]}t|trt|r|jqSr issubclassrr).0cclsrr |sz.Configurable.section_names..)reversed__mro__r3rr3r section_namesyszConfigurable.section_namescCsX|g}|jr||j|t}|D]*}|D]}||r4|||q4q(|S)aextract my config from a global Config object will construct a Config object of only the config values that apply to me based on my mro(), as well as those of my parent(s) if they exist. If I am Bar and my parent is Foo, and their parent is Tim, this will return merge following config sections, in this order:: [Bar, Foo.Bar, Tim.Foo.Bar] With the last item being the highest priority. )rappend_find_my_configrr8Z _has_sectionmerge)r,cfgZcfgs my_configr2Zsnamerrrr:s   zConfigurable._find_my_configNc Csn|dur|jdd}|dur$|}||}| |D]\}}||vrt|trtt||}||}nt|t r|||}t ||t |qBt |sBt|t sBddlm}t|tr|jj} ndd} |||} dj||jjd } t| d kr| d j| dd 7} n(t| d kr@| d jdt| d 7} | | qBWdn1s`0YdS)z load traits from a Config objectNTrr)get_close_matchescSstj|ddS)N ) stacklevel)warningswarn)msgrrrz+Configurable._load_config..z5Config option `{option}` not recognized by `{klass}`.)optionklassrz Did you mean `{matches}`?)matchesz# Did you mean one of: `{matches}`?, )traitsr8r:Zhold_trait_notificationsitems isinstancergetattrZ get_valuerr+rrrZdifflibr?LoggingConfigurablelogZwarningformatr.rlenjoinsorted) r,r<r8rKr=rZ config_valueinitialr?rCrIrDrrrr*s8           zConfigurable._load_configrcCs*|jdd}|}|j|j||ddS)zUpdate all the class traits having ``config=True`` in metadata. For any class trait with a ``config`` metadata attribute that is ``True``, we update the trait with the value of the corresponding config entry. Tr>)rKr8N)rKr8r*new)r,r!rKr8rrr_config_changeds zConfigurable._config_changedcCs&t|j|_|||j|dS)z%Update config and load the new valuesN)rrr*r;)r,rrrr update_configs  zConfigurable.update_configcCs|dust||sJg}ddd|jD}|d|j|f|t|ddt|jdd D]\}}| ||}||qnd |S) zGet the help string for this class in ReST format. If `inst` is given, it's current trait values will be used in place of class defaults. NrJcss|] }|jVqdSN)rr1prrr rFz.Configurable.class_get_help..z%s(%s) optionsr-Tr> ) rMrS __bases__r9rrRrT class_traitsrLclass_get_trait_help)r4instZ final_helpZ base_classeskvhelprrrclass_get_helps  zConfigurable.class_get_helpc Cs|dust||sJg}d|j|jf}t|ttfr|jdd}t|trVd}nd|jj}|dkr|d||f}qd||f}nd ||jjf}| ||dur|j }|d krd t |d }| t |d |jjvr| t d||dur"| t dt||jfn`z |}WntyFd}Yn0|durt|dkrp|ddd}| t d|d |S)aGet the helptext string for a single trait. :param inst: If given, it's current trait values will be used in place of the class default. :param helptext: If not given, uses the `help` attribute of the current trait. Nz--%s.%s multiplicityr9z=z <%s-item-1>z%s=%s...z%s %s...z%s=<%s>r^LEnumz Choices: %sz Current: %r@=...z Default: %s)rMrrr r metadatar&r.lowerr9rerSrrinforNdefault_value_repr ExceptionrR) r4traitrbZhelptextlinesheaderrgZ sample_valuedvrrrrras>        z!Configurable.class_get_trait_helpcCst||dS)z4Get the help string for a single trait and print it.N)printrf)r4rbrrrclass_print_help*szConfigurable.class_print_helpcCsF|}|D]4}t|tr ||vr |jdd|jd|ur |}q |S)a7Get the class that defines a trait For reducing redundant help output in config files. Returns the current class if: - the trait is defined on this class, or - the class where it is defined would not be in the config file Parameters ---------- trait : Trait The trait to look for classes : list The list of other classes to consider for redundancy. Will return `cls` even if it is not defined on `cls` if the defining class is not in `classes`. Tr>N)mror0rZclass_own_traitsr&r)r4rsclassesZ defining_clsrrrr_defining_class/s  zConfigurable._defining_classc Csldd}d}ddd|jD}d|j|f}|||g}|d}|rR|j}|sbt|d d }|r~||||d t|jd d  D]\}} | } |r| | |} n|} | |ur| j r||| j d t | jvr|d| |d| n8| j r,||| j ddd|d| j|f|d|j|| f|d qd|S)zGet the config section for this class. Parameters ---------- classes : list, optional The list of other classes in the config file. Used to reduce redundant information. cSs dt|d}d|ddS)z"return a commented, wrapped block.z Nz## r^z # )rSrreplace)srrrr2Ssz,Configurable.class_config_section..czO#------------------------------------------------------------------------------rJcss|]}t|tr|jVqdSrYr/rZrrrr\[s z4Configurable.class_config_section..z# %s(%s) configuration description__doc__rhTr>rjz# Choices: %sz# Default: %sr^rrz# See also: %s.%sz# c.%s.%s = %s)rSr_rr`r&Z default_valuerNr9rTrLrqr{retyperpsplit) r4rzr2ZbreakerZparent_classesr~rtZdescrrsZ default_reprZdefining_classrrrclass_config_sectionIs@       z!Configurable.class_config_sectionc Csg}|j}t|jddD]\}}|jj}|d|j}d|vrV|d|7}n |d|7}||z |}Wnt yd}Yn0|durt |dkr|ddd }| d d }|t d ||d |j pd}|t t||d qd|S)zwGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. Tr>.rjz : Nrkrlrmz\nz\\nzDefault: ``%s``rhzNo descriptionr^)rrTr`rLr.rZinfo_rstr9rqrrrRr}rrerrS) r4rtZ classnamercrsZttypeZtermlinervrerrrclass_config_rst_docs.          z!Configurable.class_config_rst_doc)NN)N)NN)N)N)rrrr rrrr( classmethodr8r:r*r rrWrXrfrarxr{rr __classcell__rrr-rr-s.   G  *   3   =rc@sBeZdZdZeddZedddZedddZ d d Z d S) rOzA parent class for Configurables that log. Subclasses have a log trait, and the default behavior is to get the logger from the currently running Application. z Logger or LoggerAdapter instance)rerPcCs6t|jtjtjfs0t|jjd|jd|jS)Nz..log should be a Logger or LoggerAdapter, got r) rMvalueloggingZLogger LoggerAdapterrBrCr.r)r,Zproposalrrr _validate_logs z!LoggingConfigurable._validate_logcCs(t|jtr|jjSddlm}|S)Nr)rP)rMrrOrPZ traitletsZ get_logger)r,rPrrr _log_defaults  z LoggingConfigurable._log_defaultcCs2|j}t|tjr|j}t|dds(dS|jdS)zNReturn the default Handler Returns None if none can be found handlersNr)rPrMrrloggerrNr)r,rrrr_get_log_handlers   z$LoggingConfigurable._get_log_handlerN) rrrrrrPrrrrrrrrrrOs   rOc@sDeZdZdZdZeddZeddZeddZed d Z dS) SingletonConfigurablezA configurable that only allows one instance. This class is for classes that should only have one instance of itself or *any* subclass. To create and retrieve such a class use the :meth:`SingletonConfigurable.instance` method. Nccs4|D]&}t||rt|tr|tkr|VqdS)zfWalk the cls.mro() for parent classes that are also singletons For use in instance() N)ryr0rr4subclassrrr _walk_mros  zSingletonConfigurable._walk_mrocCs0|s dS|D]}t|j|rd|_qdS)z>unset _instance for this class and singleton parents. N) initializedrrM _instancerrrrclear_instances   z$SingletonConfigurable.clear_instancecOs\|jdur,||i|}|D] }||_q t|j|r>|jStd|jt|jjfdS)aReturns a global instance of this class. This method create a new instance if none have previously been created and returns a previously created instance is one already exists. The arguments and keyword arguments passed to this method are passed on to the :meth:`__init__` method of the class upon instantiation. Examples -------- Create a singleton class using instance, and retrieve it:: >>> from traitlets.config.configurable import SingletonConfigurable >>> class Foo(SingletonConfigurable): pass >>> foo = Foo.instance() >>> foo == Foo.instance() True Create a subclass that is retrived using the base class instance:: >>> class Bar(SingletonConfigurable): pass >>> class Bam(Bar): pass >>> bam = Bam.instance() >>> bam == Bar.instance() True NzHAn incompatible sibling of '%s' is already instanciated as singleton: %s)rrrMrrr)r4argsr#rbrrrrinstances   zSingletonConfigurable.instancecCst|do|jduS)zHas an instance been created?rN)hasattrrr3rrrr*sz!SingletonConfigurable.initialized) rrrrrrrrrrrrrrrs   +r)rcopyrrrBloaderrrrrZtraitlets.traitletsrr r r r r rrrZtraitlets.utils.textrrtextwraprrrrrrrOrrrrrs ,   (