a ߙfb'G@s:dZddlmZddlZddlmZddlmZddlm Z ddl Z ddl m Z ddlmZgd ZGd d d eZGd d d e ZgZddZGdddeZGdddedZGdddeZGdddeZddZddZGdddZdd Zd!d"Zd#d$Z dd%ee fd&d'Z!Gd(d)d)Z"Gd*d+d+Z#dS),zJ This module contains helper functions and classes for handling metadata. )wrapsN) OrderedDict)Mapping)deepcopy)AstropyWarning)dtype_bytes_or_chars) MergeConflictErrorMergeConflictWarningMERGE_STRATEGIES common_dtype MergePlusMergeNpConcatenate MergeStrategyMergeStrategyMetaenable_merge_strategiesmergeMetaData MetaAttributec@s eZdZdS)rN__name__ __module__ __qualname__rr5lib/python3.9/site-packages/astropy/utils/metadata.pyrsrc@s eZdZdS)r Nrrrrrr sr csddtjtjtjtjtjftfdd|D}t|dkrnfdd|D}td|}||_ |fd d|D}t |D]8\}}|j j d vr|j j d krd nd t |j g||<qtdd|D}|j jS)a Use numpy to find the common dtype for a list of ndarrays. Only allow arrays within the following fundamental numpy data types: ``np.bool_``, ``np.object_``, ``np.number``, ``np.character``, ``np.void`` Parameters ---------- arrs : list of ndarray Arrays for which to find the common dtype Returns ------- dtype_str : str String representation of dytpe (dtype ``str`` attribute) cSst|dtdS)NdtypeO)getattrnprarrrrrr5szcommon_dtype..dtypec3s&|]tfddDVqdS)c3s|]}tj|VqdSN) issubclasstype).0Znp_type)rrrr 9z)common_dtype...N)tuple)r#rZnp_typesrrr$9szcommon_dtype..csg|]}|jqSr)namer#rrrr =r%z common_dtype..zArrays have incompatible types csg|]}tjd|dqS)r(r+)remptyr*r+rrr,Br%)SUr/00cSsg|] }|dqS)rrr*rrrr,Kr%)rZbool_Zobject_Znumber characterZvoidsetlenrZ_incompat_types enumeraterkindrZarraystr)ZarrsZ uniq_typesZincompat_typesZtmeirZ arr_commonrr'rr $s$   r cs eZdZdZfddZZS)rzc Metaclass that registers MergeStrategy subclasses into the MERGE_STRATEGIES registry. c st||||}d|vrPt|dtrP|djtfdd}t||_d|vr|d}t|trp|g}t|D]\}}t d|||fqx|S)Nrc s@z|||WSty:}zt|WYd}~n d}~00dSr ) Exceptionr)clsleftrighterrZ orig_mergerrr]sz(MergeStrategyMeta.__new__..mergetypesr) super__new__ isinstance classmethod__func__rrr&reversedr insert) mclsr)basesmembersr:rr?r;r< __class__r>rrAUs   zMergeStrategyMeta.__new__)rrr__doc__rA __classcell__rrrJrrOsrc@seZdZdZdZdS)ra^ Base class for defining a strategy for merging metadata from two sources, left and right, into a single output. The primary functionality for the class is the ``merge(cls, left, right)`` class method. This takes ``left`` and ``right`` side arguments and returns a single merged output. The first class attribute is ``types``. This is defined as a list of (left_types, right_types) tuples that indicate for which input types the merge strategy applies. In determining whether to apply this merge strategy to a pair of (left, right) objects, a test is done: ``isinstance(left, left_types) and isinstance(right, right_types)``. For example:: types = [(np.ndarray, np.ndarray), # Two ndarrays (np.ndarray, (list, tuple)), # ndarray and (list or tuple) ((list, tuple), np.ndarray)] # (list or tuple) and ndarray As a convenience, ``types`` can be defined as a single two-tuple instead of a list of two-tuples, e.g. ``types = (np.ndarray, np.ndarray)``. The other class attribute is ``enabled``, which defaults to ``False`` in the base class. By defining a subclass of ``MergeStrategy`` the new merge strategy is automatically registered to be available for use in merging. However, by default the new merge strategy is *not enabled*. This prevents inadvertently changing the behavior of unrelated code that is performing metadata merge operations. In most cases (particularly in library code that others might use) it is recommended to leave custom strategies disabled and use the `~astropy.utils.metadata.enable_merge_strategies` context manager to locally enable the desired strategies. However, if one is confident that the new strategy will not produce unexpected behavior, then one can globally enable it by setting the ``enabled`` class attribute to ``True``. Examples -------- Here we define a custom merge strategy that takes an int or float on the left and right sides and returns a list with the two values. >>> from astropy.utils.metadata import MergeStrategy >>> class MergeNumbersAsList(MergeStrategy): ... types = ((int, float), (int, float)) # (left_types, right_types) ... ... @classmethod ... def merge(cls, left, right): ... return [left, right] FN)rrrrLenabledrrrrrqs4r) metaclassc@s0eZdZdZeefeefgZdZeddZ dS)r z Merge ``left`` and ``right`` objects using the plus operator. This merge strategy is globally enabled by default. TcCs||Sr rr:r;r<rrrrszMergePlus.mergeN) rrrrLlistr&r?rNrCrrrrrr s r c@sFeZdZdZejejfejeeffeefejfgZdZ e ddZ dS)r z Merge ``left`` and ``right`` objects using np.concatenate. This merge strategy is globally enabled by default. This will upcast a list or tuple to np.ndarray and the output is always ndarray. TcCs0t|t|}}t||gt||gSr )rZ asanyarrayr Z concatenaterPrrrrs zMergeNpConcatenate.mergeN) rrrrLrZndarrayrQr&r?rNrCrrrrrr s   r cCst||ot||Sr )rB)r;r<r:rrr_both_isinstancesrRcCs(zt||kWSty"YdS0dSNT)boolr9)r;r<rrr _not_equals rUc@s$eZdZddZddZddZdS)_EnableMergeStrategiescGs<||_i|_tD]&\}}}t||r|j|j|<d|_qdSrS)merge_strategies orig_enabledr r!rN)selfrW left_type right_typemerge_strategyrrr__init__s   z_EnableMergeStrategies.__init__cCsdSr rrYrrr __enter__sz _EnableMergeStrategies.__enter__cCs|jD]\}}||_q dSr )rXitemsrN)rYr"valuetbr\rNrrr__exit__sz_EnableMergeStrategies.__exit__N)rrrr]r_rcrrrrrVsrVcGst|S)a5 Context manager to temporarily enable one or more custom metadata merge strategies. Examples -------- Here we define a custom merge strategy that takes an int or float on the left and right sides and returns a list with the two values. >>> from astropy.utils.metadata import MergeStrategy >>> class MergeNumbersAsList(MergeStrategy): ... types = ((int, float), # left side types ... (int, float)) # right side types ... @classmethod ... def merge(cls, left, right): ... return [left, right] By defining this class the merge strategy is automatically registered to be available for use in merging. However, by default new merge strategies are *not enabled*. This prevents inadvertently changing the behavior of unrelated code that is performing metadata merge operations. In order to use the new merge strategy, use this context manager as in the following example:: >>> from astropy.table import Table, vstack >>> from astropy.utils.metadata import enable_merge_strategies >>> t1 = Table([[1]], names=['a']) >>> t2 = Table([[2]], names=['a']) >>> t1.meta = {'m': 1} >>> t2.meta = {'m': 2} >>> with enable_merge_strategies(MergeNumbersAsList): ... t12 = vstack([t1, t2]) >>> t12.meta['m'] [1, 2] One can supply further merge strategies as additional arguments to the context manager. As a convenience, the enabling operation is actually done by checking whether the registered strategies are subclasses of the context manager arguments. This means one can define a related set of merge strategies and then enable them all at once by enabling the base class. As a trivial example, *all* registered merge strategies can be enabled with:: >>> with enable_merge_strategies(MergeStrategy): ... t12 = vstack([t1, t2]) Parameters ---------- *merge_strategies : `~astropy.utils.metadata.MergeStrategy` Merge strategies that will be enabled. )rV)rWrrrrs8rcCsd|t|t||}|S)NzECannot merge meta key {0!r} types {1!r} and {2!r}, choosing {0}={3!r})formatr"keyr;r<outrrr_warn_str_func#srhcCs"d|dt|dt|}|S)NzCannot merge meta key z types z and )r"rerrr_error_str_func*sriwarnc Cst||tstdt|}|D]\}}||vrDt|||<q$t||||trvt||||||d||<q$zx|durtD]J\} } } | jsqt||| rt||| r| ||||||<qqtn|||||||<Wq$ty||dur||||<n||dur6||||<nt ||||r|dkrrt ||||||t n6|dkrt||||||n|dkrt d||||<n ||||<Yq$0q$|S)z Merge the ``left`` and ``right`` metadata objects. This is a simplistic and limited implementation at this point. z%Can only merge two dict-based objects)metadata_conflictsNrjerrorZsilentzGmetadata_conflicts argument must be one of "silent", "warn", or "error")rRdictrrr`rr rNrBrUwarningsrjr ValueError) r;r<Z merge_funcrkZ warn_str_funcZerror_str_funcrgrfvalrZr[Z merge_clsrrrr/sP       rc@s*eZdZdZd ddZddZdd Zd S) ra A descriptor for classes that have a ``meta`` property. This can be set to any valid `~collections.abc.Mapping`. Parameters ---------- doc : `str`, optional Documentation for the attribute of the class. Default is ``""``. .. versionadded:: 1.2 copy : `bool`, optional If ``True`` the the value is deepcopied before setting, otherwise it is saved as reference. Default is ``True``. .. versionadded:: 1.2 TcCs||_||_dSr )rLcopy)rYdocrrrrrr]szMetaData.__init__cCs$|dur |St|dst|_|jS)N_meta)hasattrrrt)rYinstanceownerrrr__get__s  zMetaData.__get__cCsB|durt|_n,t|tr6|jr.t||_q>||_ntddS)Nz meta attribute must be dict-like)rrtrBrrrr TypeError)rYrvrarrr__set__s   zMetaData.__set__N)rqT)rrrrLr]rxrzrrrrrss rc@sBeZdZdZdddZddZddZd d Zd d Zd dZ dS)raZ Descriptor to define custom attribute which gets stored in the object ``meta`` dict and can have a defined default. This descriptor is intended to provide a convenient way to add attributes to a subclass of a complex class such as ``Table`` or ``NDData``. This requires that the object has an attribute ``meta`` which is a dict-like object. The value of the MetaAttribute will be stored in a new dict meta['__attributes__'] that is created when required. Classes that define MetaAttributes are encouraged to support initializing the attributes via the class ``__init__``. For example:: for attr in list(kwargs): descr = getattr(self.__class__, attr, None) if isinstance(descr, MetaAttribute): setattr(self, attr, kwargs.pop(attr)) The name of a ``MetaAttribute`` cannot be the same as any of the following: - Keyword argument in the owner class ``__init__`` - Method or attribute of the "parent class", where the parent class is taken to be ``owner.__mro__[1]``. :param default: default value NcCs ||_dSr )default)rYr{rrrr]szMetaAttribute.__init__cCs|dur |S|jdur.|j|jdivr.dS|jdi}z||j}Wn8ty|jdurrt|j||j<||j}Yn0|SNZ__attributes__)r{r)metaget setdefaultKeyErrorr)rYrvrw attributesrarrrrxs   zMetaAttribute.__get__cCs|jdi}|||j<dSr|)r}rr))rYrvrarrrrrzszMetaAttribute.__set__cCs6d|jvr2|jd}|j|vr&||j=|s2|jd=dSr|)r}r))rYrvattrsrrr __delete__s    zMetaAttribute.__delete__cs^ddlfdd|jD}||vs>t|jd|rTt|d|jj||_ dS)Nrcs(g|] }|jjjjjfvr|jqSr)r6Z ParameterZ VAR_KEYWORDZVAR_POSITIONALr))r#Zparaminspectrrr,s z.MetaAttribute.__set_name__..r(z not allowed as ) rZ signature parametersvaluesru__mro__rorKrr))rYrwr)paramsrrr __set_name__s zMetaAttribute.__set_name__cCs d|jjd|jd|jdS)N)rKrr)r{r^rrr__repr__szMetaAttribute.__repr__)N) rrrrLr]rxrzrrrrrrrrs   r)$rL functoolsrrn collectionsrcollections.abcrrrrZnumpyrZastropy.utils.exceptionsrZastropy.utils.miscr__all__ryrr r r r"rrr r rRrUrVrrhrirrrrrrrs:      +": ; D.