B NcR@sdZddlZddlZddlmZddlmZddlmZm Z m Z m Z m Z m Z mZmZmZddlmZmZddlmZmZmZmZGd d d eZGd d d eZGd dde ZGdddeZGdddeZdS)z/A base class for objects that are configurable.N)deepcopy)dedent) Any ContainerDict HasTraitsInstancedefaultobserveobserve_compatvalidate)indentwrap_paragraphs)ConfigDeferredConfigLazyConfigValue_is_section_keyc@s eZdZdS)ConfigurableErrorN)__name__ __module__ __qualname__rr.notice_config_override) popgetrrsuper__init__setr _load_configZ unobservesetattr)selfr"rrr#r) __class__)r!r"rr'2s        zConfigurable.__init__csfddtjDS)zreturn section names as a listcs&g|]}t|trt|r|jqSr) issubclassrr).0c)clsrr ~sz.Configurable.section_names..)reversed__mro__)r0r)r0r section_nameszs zConfigurable.section_namescCs`|g}|jr||j|t}x6|D].}x(|D]}||r8|||q8Wq*W|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_configrr4Z _has_sectionmerge)r+cfgZcfgs my_configr/Zsnamerrrr6s   zConfigurable._find_my_configNc Cs^|dkr|jdd}|dkr$|}||}|x|D]\}}||krt|trxt||}||}nt|t r|||}t ||t |qFt |sFt|t sFddlm}t|tr|jj} ndd} |||} dj||jjd } t| d kr| d | dd 7} n(t| d krD| d jdt| d7} | | qFWWdQRXdS)z load traits from a Config objectNT)rr)get_close_matchescSstj|ddS)N ) stacklevel)warningswarn)msgrrrz+Configurable._load_config..z5Config option `{option}` not recognized by `{klass}`.)optionklassrz Did you mean `z`?z# Did you mean one of: `{matches}`?z, )matches)traitsr4r6Zhold_trait_notificationsitems isinstancergetattrZ get_valuerr*rrrZdifflibr:LoggingConfigurablelogZwarningformatr,rlenjoinsorted) r+r8r4rEr9rZ config_valueinitialr:r>rDr?rrrr)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. T)r)rEr4N)rEr4r)new)r+r rEr4rrr_config_changeds zConfigurable._config_changedcCs&t|j|_|||j|dS)z%Update config and load the new valuesN)rrr)r7)r+rrrr update_configs  zConfigurable.update_configcCs|dkst||stg}ddd|jD}||jd|d|t|ddx6t|jd d  D]\}}| ||}||qtWd |S) zGet the help string for this class in ReST format. If `inst` is given, its current trait values will be used in place of class defaults. Nz, css|] }|jVqdS)N)r)r.prrr sz.Configurable.class_get_help..(z ) optionsr-T)r ) rGAssertionErrorrM __bases__r5rrLrN class_traitsrFclass_get_trait_help)r0instZ final_helpZ base_classes_vhelprrrclass_get_helps zConfigurable.class_get_helpc Cs|dkst||stg}d|jd|j}t|ttfr|jdd}t|trZd}nd|jj }|dkr|d|d }q|d |d }n|d |jjd }| ||dkr|j }|d krd t |d}| t|d|jjkr | td||dk r4| tdt||jnby |}Wntk rZd}YnX|dk rt|dkr|ddd }| td|d |S)aGet the helptext string for a single trait. :param inst: If given, its 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--. multiplicityr5z=z <%s-item-1>=z... z=<>rWLEnumz Choices: %sz Current: @=z Default: %s)rGrXrrrrZmetadatar%r,lowerr5r_rMrr inforHdefault_value_repr ExceptionrL) r0traitr\ZhelptextlinesheaderrbZ sample_valuedvrrrrr[s>       z!Configurable.class_get_trait_helpcCst||dS)z4Get the help string for a single trait and print it.N)printr`)r0r\rrrclass_print_help1szConfigurable.class_print_helpcCsJ|}x@|D]4}t|tr||kr|jdd|jd|kr|}qW|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`. T)rN)mror-rZclass_own_traitsr%r)r0roclassesZ defining_clsrrrr_defining_class6s zConfigurable._defining_classc Csdd}d}ddd|jD}d|jd|d }|||g}|d }|rX|j}|sht|d d }|r||||d xt|jd d D]\}} | } |r| | |} n|} | |kr| j r||| j dt | jkr|d| |d| n<| j r6||| j ddd|d| jd||d|jd|d| |d qWd|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## rWz # )rMrreplace)srrrr/]sz,Configurable.class_config_section..czO#------------------------------------------------------------------------------z, css|]}t|tr|jVqdS)N)r-rr)r.rSrrrrTesz4Configurable.class_config_section..z# rUz) configuration description__doc__rfT)rrhz# Choices: %sz# Default: %srWrrz # See also: raz# c.z = )rMrYrrZr%Z default_valuerHr5rNrFrmrwr_typerlsplit) r0rvr/ZbreakerZparent_classesrzrpZdescrroZ default_reprZdefining_classrrrclass_config_sectionRs<     z!Configurable.class_config_sectionc Csg}|j}xt|jddD]\}}|jj}|d|j}d|krX|d|7}n |d|7}||y |}Wnt k rd}YnX|dk rt |dkr|ddd }| d d }|t d ||d |j pd}|t t||d q Wd|S)zwGenerate rST documentation for this class' config options. Excludes traits defined on parent classes. T)rrarhz : Nrirjz...z\nz\\nzDefault: ``%s``rfzNo descriptionrW)rrNrZrFr,rZinfo_rstr5rmrnrLryr r_rrM) r0rpZ classnamer]roZttypeZtermlinerrr_rrrclass_config_rst_docs.        z!Configurable.class_config_rst_doc)NN)N)NN)N)N)rrrrrrrr' classmethodr4r6r)r r rQrRr`r[rtrwrr __classcell__rr)r,rr-s&   H  .  3   ;rc@sBeZdZdZeddZedddZedddZ d d Z d S) rIzA 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)r_rJcCs6t|jtjtjfs0t|jjd|jd|jS)Nz..log should be a Logger or LoggerAdapter, got ra) rGvalueloggingZLogger LoggerAdapterr=r>r,r)r+Zproposalrrr _validate_logsz!LoggingConfigurable._validate_logcCs(t|jtr|jjSddlm}|S)Nr)rJ)rGrrIrJZ traitletsZ get_logger)r+rJrrr _log_defaults  z LoggingConfigurable._log_defaultcCs2|j}t|tjr|j}t|dds(dS|jdS)zReturn the default Handler Returns None if none can be found Deprecated, this now returns the first log handler which may or may not be the default one. handlersNr)rJrGrrloggerrHr)r+rrrr_get_log_handlers   z$LoggingConfigurable._get_log_handlerN) rrrr|rrJr rr rrrrrrrIs   rIc@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. Nccs8x2|D]&}t||r t|tr |tkr |Vq WdS)zfWalk the cls.mro() for parent classes that are also singletons For use in instance() N)rur-r)r0subclassrrr _walk_mros   zSingletonConfigurable._walk_mrocCs4|s dSx"|D]}t|j|rd|_qWdS)z5unset _instance for this class and singleton parents.N) initializedrrG _instance)r0rrrrclear_instances  z$SingletonConfigurable.clear_instancecOs\|jdkr,|||}x|D] }||_qWt|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)rrrGrrr})r0argsr"r\rrrrinstance s    zSingletonConfigurable.instancecCst|do|jdk S)zHas an instance been created?rN)hasattrr)r0rrrr5sz!SingletonConfigurable.initialized) rrrr|rrrrrrrrrrrs   ,r)r|rr=copyrtextwraprZtraitlets.traitletsrrrrrr r r r Ztraitlets.utils.textr rloaderrrrrrnrrrrIrrrrrs  ,  ,