*dl&ddlZddlZddlmZddlmZddlmZddlm Z m Z m Z m Z m Z mZejdeZGddeZGd d ZdS) N) defaultdict)MutableMapping)Enum)AnyHashableIterableOptionalTupleUnionzconda.c eZdZdZ d#dedeedeeefdeefdZ dddd deefd Z e d Z d Z d ZdZdefdZdedefdZdefdZdddededeedefdZdddededeedeeeffdZd$deefdZddddeeefdeedefdZddddededeedefdZdedeeeedfdffdZdZed%d!Zd"Z dS)& TrackedMapu Implements a dictionary-like interface with self-logging capabilities. Each item in the dictionary can be annotated with a ``reason`` of type ``str``. Since a keyword argument is needed, this is only doable via the ``.set()`` method (or any of the derivative methods that call it, like ``.update()``). With normal ``dict`` assignment (à la ``d[key] = value``), ``reason`` will be None. Reasons are kept in a dictionary of lists, so a history of reasons is kept for each key present in the dictionary. Reasons for a given ``key`` can be checked with ``.reasons_for(key)``. Regardless the value of ``reason``, assignments, updates and deletions will be logged for easy debugging. It is in principle possible to track where each key came from by reading the logs, since the stack level is matched to the originating operation. ``.set()`` and ``.update()`` also support an ``overwrite`` boolean option, set to True by default. If False, an existing key will _not_ be overwritten with the new value. Parameters ---------- name A short identifier for this tracked map. Useful for logging. data Initial data for this object. It can be a dictionary, an iterable of key-value pairs, or another ``TrackedMap`` instance. If given a ``TrackedMap`` instance, its data and reasons will be copied over, instead of wrapped, to avoid recursion. reason Optionally, a reason on why this object was initialized with such data. Ignored if no data is provided. Examples -------- >>> TrackedMap("example", data={"key": "value"}, reason="Initialization) >>> tm = TrackedMap("example") >>> tm.set("key", "value", reason="First value") >>> tm.update({"another_key": "another_value"}, reason="Second value") >>> tm["third_key"] = "third value" >>> tm[key] "value" >>> tm.reasons_for(key) ["First value"] >>> tm["third_key"] "third value" >>> tm.reasons_for("third_key") [None] Nnamedatareasonc||_|jj|_t |t rZ|j|_rfd|jD|_dS|j|_dSi|_tt|_| |pidS)Nci|]}|Sr).0krs z'TrackedMap.__init__..Ks ? ? ?qF ? ? ?r) _name __class____name___clsname isinstancer _datacopy_reasonsrlistupdate)selfrrrs `r__init__zTrackedMap.__init__?s  / dJ ' ' 3**DJ 5 ? ? ? ?DJ ? ? ? $ 2 2 4 4 DJ'--DM KK 6K 2 2 2 2 2rT)r overwrite_levelct|tsJ|d|d |j|}|j|dgd}|jd|jd|d|d|d|| }|} n<#t$r/|jd|jd|d ||}d } YnwxYw| r6|r)|d |dz }|j| |||j|<n4|jd|jd|d|d|d ||d |d }| ||dS)Nz is not str ():[] (=z , reason=z ) updated to z ] set to T (reason=z) wanted new value z-) but stayed the same due to overwrite=False. stacklevel) rstrrr!getrr _short_reprKeyErrorappend _log_debug) r$keyvaluerr'r(old old_reasonmsgwrites r_setzTrackedMap._setSs&#s##EE%E%EF%E%E%EEEE *S/C**377;J=XX4:XXXXXX%/XX>B>N>Nu>U>UXX EE   ][[TZ[[#[[$BRBRSXBYBY[[CEEE    2,6,,,, c"))&111#DJsOO=QQ4:QQQQQQ%/QQDHDTDTUZD[D[QQ!QQQ  /////sA!B 6CCc|jSN)rr$s rrzTrackedMap.nameos zrc .|jsdSdg}|jD]F\}}|j|}|rd|nd}|d|d|d|G|dd |S) Nz{}{z # reasons=z z: ,} )ritemsr!r3r6join)r$linesrvreasonss r__repr__zTrackedMap.__repr__ssz 4J$$&& 6 6DAqm''**G29A.W...rG LL4a44Q44744 5 5 5 5 Syyrc*t|jSr@)iterrrAs r__iter__zTrackedMap.__iter__~sDJrc*t|jSr@)lenrrAs r__len__zTrackedMap.__len__s4:rr8c|j|Sr@)rr$r8s r __getitem__zTrackedMap.__getitem__sz#rr9c2|||dSr@r>)r$r8r9s r __setitem__zTrackedMap.__setitem__s #urc|j|=|j|d||jd|jd|dddS)Nr,r-z ] was deletedr0)rr!popr7rrrUs r __delitem__zTrackedMap.__delitem__s] JsO #t$$$ 4=LL4:LLLLLYZ[[[[[rrdefaultreturnc |jj|g|R}|jj|g|R|jd|jd|d||d}|r |d|dz }||d|S) z Remove a key-value pair and return the value. A reason can be provided for logging purposes, but it won't be stored in the object. r,r-r. ) was deletedr/r*r[r0)rr\r!rrr4r7r$r8rr^r9r<s rr\zTrackedMap.pops  s-W--- #(((((____c__9I9I%9P9P___  ) (v((( (C *** rc |j|\}}|jj|g|R|jd|jd|d||d}|r |d|dz }||d||fS) z Remove and return a key-value pair. A reason can be provided for logging purposes, but it won't be stored in the object. r,r-r.rar/r*r[r0)rpopitemr!r\rrr4r7rbs rrdzTrackedMap.popitemsZ'',, U #(((((____c__9I9I%9P9P___  ) (v((( (C ***Ezrc|j|j|jd}|r |d|dz }||ddS)z Remove all entries in the map. A reason can be provided for logging purposes, but it won't be stored in the object. z was clearedr/r*r[r0N)rclearr!rr7)r$rr<s rrfzTrackedMap.clearsv  )))  ) (v((( (C *****rrr'r'ct|dr8|D]!}||||||"dS|D]\}}|||||dS)a Update the dictionary with a reason. Note that keyword arguments are not supported in this specific implementation, so you can only update a dictionary with another dictionary or iterable as a positional argument. This is done so `reason` and `overwrite` can be used to control options instead of silently ignoring a potential entry in a ``**kwargs`` argument. keysrgN)hasattrrir>)r$rrr'rrKs rr#zTrackedMap.updates 4  DYY[[ J J !T!WVy IIII J J D D1 !Qv CCCC D Drc8|||||dS)a Set ``key`` to ``value``, optionally providing a ``reason`` why. Parameters ---------- key Key to the passed value value Value reason A short description on why this key, value pair was added overwrite If False, do _not_ update the ``value`` for ``key`` if ``key`` was already present in the dictionary. rgNrX)r$r8r9rr's rsetzTrackedMap.sets$$ #uVy AAAAArc6|j|S)z? Return the stored reasons for a given ``key`` )r!r3rUs r reasons_forzTrackedMap.reasons_fors}  %%%rc:||j|S)N)rr)rrrAs rr zTrackedMap.copys~~4:D~999rdcjt|}t||kr|d|dz d}|S)Nz...>)reprrR)r9maxlen value_reprs rr4zTrackedMap._short_reprs?%[[ z??V # #&yqy1777Jrcttjdkr|ddtj|i|dS)N)r&r1)sys version_infor\logdebug)r$argskwargss rr7zTrackedMap._log_debugs?  f $ $ JJ|T * * * 4"6"""""r)NNr@)rp)!r __module__ __qualname____doc__r2r r rdictr%r>propertyrrMrPrSrrVrrYr]r\r rdrfboolr#rlrnr staticmethodr4r7rrrr r s0//hIM $ 333u\8H+=tCDE3 3333(;?$WX000(3-00008X       xx\x\\\\ IM   x 3  QT    EI    '* 4smDW[DDDD&EI\`BBBB$'B4>> update_modifier = UpdateModifier("update_deps") >>> update_modifier_as_bools = EnumAsBools(update_modifier) >>> update_modifier == UpdateModifier.UPDATE_DEPS # from this True >>> update_modidier_as_bools.UPDATE_DEPS # to this True >>> update_modifier_as_bools.UPDATE_ALL False enumcx||_d|jjjD|_dS)Nch|] }|j Sr)r)rrKs r z'EnumAsBools.__init__..sQQQ!qvQQQr)_enumr __members__values_names)r$rs rr%zEnumAsBools.__init__s6 QQtz';'G'N'N'P'PQQQ rrr_c|dvrt|j|S||jvr|jj|kSt d|d|jjj)N)rr9'z' is not a valid name for )getattrrrrAttributeErrorrr)r$rs r __getattr__zEnumAsBools.__getattr__sc $ $ $4:t,, , 4;  :?d* *```AUA^``aaarobjc6|j|Sr@)r__eq__)r$rs rrzEnumAsBools.__eq__ sz  %%%rc*fdjDS)Nc2i|]}|jj|kSr)rr)rrr$s rrz%EnumAsBools._dict..s$FFF$djo-FFFr)rrAs`r_dictzEnumAsBools._dictsFFFF$+FFFFrN) rr~rrrr%r2rrobjectrrrrrrrrs  RTRRRRbbbbbb&&&T&&&&GGGGGrr)loggingrx collectionsrcollections.abcrrrtypingrrrr r r getLoggerrrzr rrrrrs  ######******BBBBBBBBBBBBBBBBg+++,,d#d#d#d#d#d#d#d#NGGGGGGGGGGr