a ߙfbv@sdZddlZddlZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZddlmZmZddlmZgdZddgZd Zd Zd d Zd@ddZGdddZejddZddZGdddZdAddZddZej dkr ddl!Z!dd Z"nd!d Z"d"d#Z#dBd%d&Z$Gd'd(d(ej%Z&d)d*Z'dCd-d.Z(d/Z)ed0e)Gd1ddej*d2Z+ed0e)Gd3dde,Z-e .Z/ed4d5Z0ed6e0Z1d7e1_d8d9Z2d:d;Z3dd?Z5dS)Ezo A "grab bag" of relatively small general-purpose utilities that don't have a clear module/package to live in. N)contextmanager) defaultdict OrderedDict) deprecated) isiterablesilenceformat_exceptionNumpyRNGContext find_api_pageis_path_hiddenwalk_skip_hiddenJsonCustomEncoderindentdtype_bytes_or_charsOrderedDescriptorOrderedDescriptorContainerrrzYFile {} already exists. If you mean to replace it then use the argument "overwrite=True".z[File .* already exists\. If you mean to replace it then use the argument "overwrite=True"\.cCs(zt|WdSty"YdS0dS)z/Returns `True` if the given object is iterable.TFN)iter TypeError)objr1lib/python3.9/site-packages/astropy/utils/misc.pyr.s  rcs6dfdd|D}|ddkr2|d7}|S)zAIndent a block of text. The indentation is applied to each line. c3s&|]}|rd|ndVqdS) Nr).0lshiftwidthrr ;szindent..)join splitlines)srr Zindentedrrrr8s  rc@seZdZdZddZdS) _DummyFilezA noop writeable object.cCsdSNr)selfr%rrrwriteFsz_DummyFile.writeN)__name__ __module__ __qualname____doc__r)rrrrr&Csr&ccs2tj}tj}tt_tt_dV|t_|t_dS)z:A context manager that silences sys.stdout and sys.stderr.N)sysstdoutstderrr&)Z old_stdoutZ old_stderrrrrrJsrcOs^tjtddd}t|dkr4|d\}}}}nd}}}}|j|||||d|S)a Given an exception message string, uses new-style formatting arguments ``{filename}``, ``{lineno}``, ``{func}`` and/or ``{text}`` to fill in information about the exception that occurred. For example: try: 1/0 except: raise ZeroDivisionError( format_except('A divide by zero occurred in {filename} at ' 'line {lineno} of function {func}.')) Any additional positional or keyword arguments passed to this function are also used to format the message. .. note:: This uses `sys.exc_info` to gather up the information needed to fill in the formatting arguments. Since `sys.exc_info` is not carried outside a handled exception, it's not wise to use this outside of an ``except`` clause - if it is, this will substitute '' for the 4 formatting arguments. r)limitrz )filenamelinenofunctext) traceback extract_tbr.exc_infolenformat)msgargskwargstbr3r4r5r6rrrrWs  rc@s(eZdZdZddZddZddZdS) r a A context manager (for use with the ``with`` statement) that will seed the numpy random number generator (RNG) to a specific value, and then restore the RNG state back to whatever it was before. This is primarily intended for use in the astropy testing suit, but it may be useful in ensuring reproducibility of Monte Carlo simulations in a science context. Parameters ---------- seed : int The value to use to seed the numpy RNG Examples -------- A typical use case might be:: with NumpyRNGContext(): from numpy import random randarr = random.randn(100) ... run your test using `randarr` ... #Any code using numpy.random at this indent level will act just as it #would have if it had been before the with statement - e.g. whatever #the default seed is. cCs ||_dSr')seed)r(r@rrr__init__szNumpyRNGContext.__init__cCs&ddlm}||_||jdSNr)random)numpyrCZ get_state startstater@)r(rCrrr __enter__s  zNumpyRNGContext.__enter__cCsddlm}||jdSrB)rDrCZ set_staterE)r(exc_type exc_valuer7rCrrr__exit__s zNumpyRNGContext.__exit__N)r*r+r,r-rArFrIrrrrr ysr TcCsVddl}ddlm}ddlm}t|tsPt|drPt|drP|jd|j }nt |r`|j }|durddl m }|jrd |j }nd }d |vr|d r|dd }q|dr|}q|d}n"|d ks|dkrd}n d|d}|d}dd|i} ||d|| d} | } d} g} tdD]6}| }| d|d} | | |d| dq&| \}}}}d|vrtd|d| | dd}Wdn1s0Y||d}d}|D]R}|}|d}|d}|dr |dd|}||kr||}q(q|durBtd |n|rR|||S)!a Determines the URL of the API page for the specified object, and optionally open that page in a web browser. .. note:: You must be connected to the internet for this to function even if ``openinbrowser`` is `False`, unless you provide a local version of the documentation to ``version`` (e.g., ``file:///path/to/docs``). Parameters ---------- obj The object to open the docs for or its fully-qualified name (as a str). version : str The doc version - either a version number like '0.1', 'dev' for the development/latest docs, or a URL to point to a specific location that should be the *base* of the documentation. Defaults to latest if you are on aren't on a release, otherwise, the version you are on. openinbrowser : bool If `True`, the `webbrowser` package will be used to open the doc page in a new web browser window. timeout : number, optional The number of seconds to wait before timing-out the query to the astropy documentation. If not given, the default python stdlib timeout will be used. Returns ------- url : str The loaded URL Raises ------ ValueError If the documentation can't be found rN) decompress)get_readable_fileobjr+r*.)versionvZdevz://z index.htmli/Zlatestzhttp://devdocs.astropy.org/zhttps://docs.astropy.org/en/z objects.invz User-AgentzAstropy/Zbinary)encodingZremote_timeoutZ http_headersr"r rzutf-8z3The remainder of this file is compressed using zlibzjThe file downloaded from {} does not seem to bethe usual Sphinx objects.inv format. Maybe it has changed?$z'Could not find the docs for the object ) webbrowserzlibrJZastropy.utils.datarK isinstancestrhasattrr+r*inspectZismoduleastropyrMreleaseendswithreadrangeindexappenddecode ValueErrorr;stripr$splitopen)rrMZ openinbrowserZtimeoutrTrJrKZbaseurlZurlZheadersZufZoireadidxZ headerlines_ZoldidxZiversZprojZversZcomprZ compressedZ decompressedZresurlrZlsnameZlocrrrr sx(              0     r cCs$tddtjD}||dS)zx Given an OS signal number, returns a signal name. If the signal number is unknown, returns ``'UNKNOWN'``. css$|]\}}|dr||fVqdS)ZSIGN) startswith)rrNkrrrr!(s  z(signal_number_to_name..ZUNKNOWN)dictsignal__dict__itemsget)ZsignumZsignal_to_name_maprrrsignal_number_to_name srpZwin32cCsZt|tr|t}z&tjj|}t |d@o:|dk}Wnt yTd}Yn0|S)z Returns True if the given filepath has the hidden attribute on MS-Windows. Based on a post here: https://stackoverflow.com/questions/284115/cross-platform-hidden-file-detection r1r"F) rVbytesrar.getfilesystemencodingctypesZwindllZkernel32ZGetFileAttributesWboolAttributeError)filepathattrsresultrrr_has_hidden_attribute1s   rycCsdS)NFr)rvrrrry@scCs@tjtj|}t|tr*|d}n |d}|p>t|S)z Determines if a given file or directory is hidden. Parameters ---------- filepath : str The path to a file or directory Returns ------- hidden : bool Returns `True` if the file is hidden .rL)ospathbasenameabspathrVrqriry)rvrhZ is_dottedrrrr Ds    r FccsZtj|d||dD]B\}}}dd|D|dd<dd|D|dd<|||fVqdS)a5 A wrapper for `os.walk` that skips hidden files and directories. This function does not have the parameter ``topdown`` from `os.walk`: the directories must always be recursed top-down when using this function. See also -------- os.walk : For a description of the parameters T)topdownonerror followlinkscSsg|]}t|s|qSrr )rdrrr kz$walk_skip_hidden..NcSsg|]}t|s|qSrr)rfrrrrlr)r{walk)toprrrootdirsfilesrrrr Zs r c@seZdZdZddZdS)r aSupport for data types that JSON default encoder does not do. This includes: * Numpy array or number * Complex number * Set * Bytes * astropy.UnitBase * astropy.Quantity Examples -------- >>> import json >>> import numpy as np >>> from astropy.utils.misc import JsonCustomEncoder >>> json.dumps(np.arange(3), cls=JsonCustomEncoder) '[0, 1, 2]' cCsddlm}ddl}t||jr4t|j|jdSt||j |j frN| St|t rd|j |jgSt|trvt|St|tr|St||j|jfr||jkrd}n|Stj||S)Nr)units)valueunitZdimensionless_unit)rZrrDrVZQuantityrkrrZ to_stringZnumberZndarraytolistcomplexrealimagsetlistrqraZUnitBaseZFunctionUnitBaseZdimensionless_unscaledjson JSONEncoderdefault)r(ruZnprrrrs"       zJsonCustomEncoder.defaultN)r*r+r,r-rrrrrr psr cCsdddtd|DS)uv Remove accents from a Unicode string. This helps with matching "ångström" to "angstrom", for example. rcss |]}t|dkr|VqdS)ZMnN) unicodedatacategory)rcrrrr!sz strip_accents..ZNFD)r#r normalize)r%rrr strip_accentss  rrR皙?c Cs4t|trt|}|}i}|D]&}|}||g|||q"|drt|dd|vrt|ddg} ntj||||d} t | r0t } | D]} | || q| } |durg} | D]} | || q| } t t | } t| } t | dkr| d} nd| ddd| d} d | d Sd S) a When a string isn't found in a set of candidates, we can be nice to provide a list of alternatives in the exception. This convenience function helps to format that part of the exception. Parameters ---------- s : str candidates : sequence of str or dict of str keys n : int The maximum number of results to include. See `difflib.get_close_matches`. cutoff : float In the range [0, 1]. Possibilities that don't score at least that similar to word are ignored. See `difflib.get_close_matches`. fix : callable A callable to modify the results after matching. It should take a single string and return a sequence of strings containing the fixed matches. Returns ------- message : str Returns the string "Did you mean X, Y, or Z?", or the empty string if no alternatives were found. r%Nr")ncutoffrrz, z or z Did you mean ?r)rVrWrlower setdefaultr`r\difflibZget_close_matchesr:rupdateextendrsortedr#) r%Z candidatesrrZfixZs_lowerZcandidates_lower candidateZcandidate_lowerZmatchesZcapitalized_matchesmatchZmapped_matchesrrr did_you_means@      raMThe {func} {obj_type} is deprecated and may be removed in a future version. You can replace its functionality with a combination of the __init_subclass__ and __set_name__ magic methods introduced in Python 3.6. See https://github.com/astropy/astropy/issues/11094 for recipes on how to replicate their functionality. z4.3csBeZdZdZdZeejddZdZ fddZ dd Z Z S) ra Base class for descriptors whose order in the class body should be preserved. Intended for use in concert with the `OrderedDescriptorContainer` metaclass. Subclasses of `OrderedDescriptor` must define a value for a class attribute called ``_class_attribute_``. This is the name of a class attribute on the *container* class for these descriptors, which will be set to an `~collections.OrderedDict` at class creation time. This `~collections.OrderedDict` will contain a mapping of all class attributes that were assigned instances of the `OrderedDescriptor` subclass, to the instances themselves. See the documentation for `OrderedDescriptorContainer` for a concrete example. Optionally, subclasses of `OrderedDescriptor` may define a value for a class attribute called ``_name_attribute_``. This should be the name of an attribute on instances of the subclass. When specified, during creation of a class containing these descriptors, the name attribute on each instance will be set to the name of the class attribute it was assigned to on the class. .. note:: Although this class is intended for use with *descriptors* (i.e. classes that define any of the ``__get__``, ``__set__``, or ``__delete__`` magic methods), this base class is not itself a descriptor, and technically this could be used for classes that are not descriptors too. However, use with descriptors is the original intended purpose. rcCsdS)a Subclasses should define this attribute to the name of an attribute on classes containing this subclass. That attribute will contain the mapping of all instances of that `OrderedDescriptor` subclass defined in the class body. If the same descriptor needs to be used with different classes, each with different names of this attribute, multiple subclasses will be needed. Nr)r(rrr_class_attribute_'sz#OrderedDescriptor._class_attribute_Ncs$tj|_tjd7_tdS)Nr)r_nextid_OrderedDescriptor__ordersuperrA)r(r=r> __class__rrrA:szOrderedDescriptor.__init__cCsPt|trHt|trHz|j|jkWStyDtd||YqL0ntSdS)z Defined for convenient sorting of `OrderedDescriptor` instances, which are defined to sort in their creation order. zqCould not determine ordering for {} and {}; at least one of them is not calling super().__init__ in its __init__.N)rVrrru RuntimeErrorr;NotImplemented)r(otherrrr__lt__Bs   zOrderedDescriptor.__lt__) r*r+r,r-rpropertyabcabstractmethodr_name_attribute_rAr __classcell__rrrrrs#  ) metaclasscs$eZdZdZdZfddZZS)ra Classes should use this metaclass if they wish to use `OrderedDescriptor` attributes, which are class attributes that "remember" the order in which they were defined in the class body. Every subclass of `OrderedDescriptor` has an attribute called ``_class_attribute_``. For example, if we have .. code:: python class ExampleDecorator(OrderedDescriptor): _class_attribute_ = '_examples_' Then when a class with the `OrderedDescriptorContainer` metaclass is created, it will automatically be assigned a class attribute ``_examples_`` referencing an `~collections.OrderedDict` containing all instances of ``ExampleDecorator`` defined in the class body, mapped to by the names of the attributes they were assigned to. When subclassing a class with this metaclass, the descriptor dict (i.e. ``_examples_`` in the above example) will *not* contain descriptors inherited from the base class. That is, this only works by default with decorators explicitly defined in the class body. However, the subclass *may* define an attribute ``_inherit_decorators_`` which lists `OrderedDescriptor` classes that *should* be added from base classes. See the examples section below for an example of this. Examples -------- >>> from astropy.utils import OrderedDescriptor, OrderedDescriptorContainer >>> class TypedAttribute(OrderedDescriptor): ... """ ... Attributes that may only be assigned objects of a specific type, ... or subclasses thereof. For some reason we care about their order. ... """ ... ... _class_attribute_ = 'typed_attributes' ... _name_attribute_ = 'name' ... # A default name so that instances not attached to a class can ... # still be repr'd; useful for debugging ... name = '' ... ... def __init__(self, type): ... # Make sure not to forget to call the super __init__ ... super().__init__() ... self.type = type ... ... def __get__(self, obj, objtype=None): ... if obj is None: ... return self ... if self.name in obj.__dict__: ... return obj.__dict__[self.name] ... else: ... raise AttributeError(self.name) ... ... def __set__(self, obj, value): ... if not isinstance(value, self.type): ... raise ValueError('{0}.{1} must be of type {2!r}'.format( ... obj.__class__.__name__, self.name, self.type)) ... obj.__dict__[self.name] = value ... ... def __delete__(self, obj): ... if self.name in obj.__dict__: ... del obj.__dict__[self.name] ... else: ... raise AttributeError(self.name) ... ... def __repr__(self): ... if isinstance(self.type, tuple) and len(self.type) > 1: ... typestr = '({0})'.format( ... ', '.join(t.__name__ for t in self.type)) ... else: ... typestr = self.type.__name__ ... return '<{0}(name={1}, type={2})>'.format( ... self.__class__.__name__, self.name, typestr) ... Now let's create an example class that uses this ``TypedAttribute``:: >>> class Point2D(metaclass=OrderedDescriptorContainer): ... x = TypedAttribute((float, int)) ... y = TypedAttribute((float, int)) ... ... def __init__(self, x, y): ... self.x, self.y = x, y ... >>> p1 = Point2D(1.0, 2.0) >>> p1.x 1.0 >>> p1.y 2.0 >>> p2 = Point2D('a', 'b') # doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): ... ValueError: Point2D.x must be of type (float, int>) We see that ``TypedAttribute`` works more or less as advertised, but there's nothing special about that. Let's see what `OrderedDescriptorContainer` did for us:: >>> Point2D.typed_attributes OrderedDict([('x', ), ('y', )]) If we create a subclass, it does *not* by default add inherited descriptors to ``typed_attributes``:: >>> class Point3D(Point2D): ... z = TypedAttribute((float, int)) ... >>> Point3D.typed_attributes OrderedDict([('z', )]) However, if we specify ``_inherit_descriptors_`` from ``Point2D`` then it will do so:: >>> class Point3D(Point2D): ... _inherit_descriptors_ = (TypedAttribute,) ... z = TypedAttribute((float, int)) ... >>> Point3D.typed_attributes OrderedDict([('x', ), ('y', ), ('z', )]) .. note:: Hopefully it is clear from these examples that this construction also allows a class of type `OrderedDescriptorContainer` to use multiple different `OrderedDescriptor` classes simultaneously. rcsFtt}t}d}i}|jD]}|jD]\} } | |vr.)rrr__mro__rmrnaddrVrrsetattrrr`getattrrsortrrrrrA)clscls_namebasesmembersZ descriptorsseenZinherit_descriptorsZ descr_basesZmro_clsrhrZ obj_cls_baseZdescriptor_clsZ instancesrrrrAsF          z#OrderedDescriptorContainer.__init__)r*r+r,r-rrArrrrrrUsc cst|}tdttj}||kr*dVn8z&ttj|dVWttj|nttj|0Wdn1sv0YdS)a2 Context manager to temporarily set the locale to ``name``. An example is setting locale to "C" so that the C strtod() function will use "." as the decimal point to enable consistent numerical string parsing. Note that one cannot nest multiple _set_locale() context manager statements as this causes a threading lock. This code taken from https://stackoverflow.com/questions/18593661/how-do-i-strftime-a-date-object-in-a-different-locale. Parameters ========== name : str Locale name, e.g. "C" or "fr_FR". N)rW LOCALE_LOCKlocale setlocaleLC_ALL)rhZsavedrrr _set_locale!s rz4.0zdDeprecated version of :func:`_set_locale` above. See https://github.com/astropy/astropy/issues/9196 cCs(td|j}|r t|dnd}|S)a Parse the number out of a dtype.str value like 'sj    "/ x   - N TI !