aclTdZddlmZddlZddlZddlZddlmZm Z m Z ddl m Z e ddDZGdd eZGd d eZd Zd ZdS)z" Utilities to support XYZservices ) annotationsN)OptionalCallableUnion)quoteci|]}|dS)).0xs /lib/python3.11/site-packages/xyzservices/lib.py r s'@'@'@!2'@'@'@z., -_/cHeZdZdZdZdZddZddZ dddZddZ d S)BunchaA dict with attribute-access :class:`Bunch` is used to store :class:`TileProvider` objects. Examples -------- >>> black_and_white = TileProvider( ... name="My black and white tiles", ... url="https://myserver.com/bw/{z}/{x}/{y}", ... attribution="(C) xyzservices", ... ) >>> colorful = TileProvider( ... name="My colorful tiles", ... url="https://myserver.com/color/{z}/{x}/{y}", ... attribution="(C) xyzservices", ... ) >>> MyTiles = Bunch(BlackAndWhite=black_and_white, Colorful=colorful) >>> MyTiles {'BlackAndWhite': {'name': 'My black and white tiles', 'url': 'https://myserver.com/bw/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}, 'Colorful': {'name': 'My colorful tiles', 'url': 'https://myserver.com/color/{z}/{x}/{y}', 'attribution': '(C) xyzservices'}} >>> MyTiles.BlackAndWhite.url 'https://myserver.com/bw/{z}/{x}/{y}' ch ||S#t$rt|wxYwN) __getitem__KeyErrorAttributeError)selfkeys r __getattr__zBunch.__getattr__*sD &##C(( ( & & & %% % &s1c*|Srkeysrs r __dir__z Bunch.__dir__0syy{{rFcfd}|D]q}t||trd}nd}tt j}|d|d|d|d|d||d d z }r|rdn d td }d|dt|d|d}|S)Nr zxyzservices.TileProviderzxyzservices.BunchzO
  • T)insidez6
    • 
    z
    xyzservices.Bunch
    z items
      z\
    ) r isinstance TileProviderstruuiduuid4 _repr_html_ CSS_STYLElen)rr childrenrobjuidstylehtmls r r)zBunch._repr_html_3s'99;;  C$s)\22 *0)djll##C ,/!%(14 #Y**$*77  HH?"?I"?"?"?   ,/t99   "   " rreturndictc0ifd|S)aReturn the nested :class:`Bunch` collapsed into the one level dictionary. Dictionary keys are :class:`TileProvider` names (e.g. ``OpenStreetMap.Mapnik``) and its values are :class:`TileProvider` objects. Returns ------- flattened : dict dictionary of :class:`TileProvider` objects Examples -------- >>> import xyzservices.providers as xyz >>> len(xyz) 36 >>> flat = xyz.flatten() >>> len(xyz) 207 ct|tr ||j<dS|D] }|dSr)r$r%namevalues)providerprov_get_providersflats r r9z%Bunch.flatten.._get_providersss](L11 )&.X]###$OO--))D"N4(((())rr )rr9r:s @@r flattenz Bunch.flattenZs@. ) ) ) ) ) ) t rNkeyword Optional[str]r5requires_tokenOptional[bool]functionCallable[[TileProvider], bool]c8dfd|||||S)a Return a subset of the :class:`Bunch` matching the filter conditions Each :class:`TileProvider` within a :class:`Bunch` is checked against one or more specified conditions and kept if they are satisfied or removed if at least one condition is not met. Parameters ---------- keyword : str (optional) Condition returns ``True`` if ``keyword`` string is present in any string value in a :class:`TileProvider` object. The comparison is not case sensitive. name : str (optional) Condition returns ``True`` if ``name`` string is present in the name attribute of :class:`TileProvider` object. The comparison is not case sensitive. requires_token : bool (optional) Condition returns ``True`` if :meth:`TileProvider.requires_token` returns ``True`` (i.e. if the object requires specification of API token). function : callable (optional) Custom function taking :class:`TileProvider` as an argument and returns bool. If ``function`` is given, other parameters are ignored. Returns ------- filtered : Bunch Examples -------- >>> import xyzservices.providers as xyz You can filter all free providers (not requiring API token): >>> free_providers = xyz.filter(requires_token=False) Or all providers with ``open`` in the name: >>> open_providers = xyz.filter(name="open") You can use keyword search to find all providers based on OpenStreetMap data: >>> osm_providers = xyz.filter(keyword="openstreetmap") You can combine multiple conditions to find providers based on OpenStreetMap data that require API token: >>> osm_locked = xyz.filter(keyword="openstreetmap", requires_token=True) You can also pass custom function that takes :class:`TileProvider` and returns boolean value. You can then find all providers with ``max_zoom`` smaller than 18: >>> def zoom18(provider): ... if hasattr(provider, "max_zoom") and provider.max_zoom < 18: ... return True ... return False >>> small_zoom = xyz.filter(function=zoom18) cg}|od}|D]C}t|tr,||vrd}nD|||Fd}||jvrd}|||/d}||urd}||t|S)NFT)r6r$r&lowerappendr5r>all) r7r<r5r>cond keyword_matchv name_match token_matchs r _validatezBunch.filter.._validates D + % !**""A!!S))""==??aggii7",0M!E M*** (" ::<<8=#6#6#8#88&!%J J''' )# **,,>'"&K K(((t99 rct}|D]Y\}}t|tr(| ||||r|||<1||r|||<B |||||}|r|||<Z|S)N)r<r5r>r<r5r>r@)ritemsr$r%) bunchr<r5r>r@newrvaluefiltered _filter_bunchrLs r rTz#Bunch.filter.._filter_bunchs''C#kkmm , , Ue\22, -$9!$+!%+9 - (-CH#8E??-',CH -} '!'5!)    H ,#+CJrrNr )rr<r5r>r@rTrLs @@r filterz Bunch.filter~s\D   6      <} )     rr&r%cd|D}|t}||vr||St d|d)aReturn :class:`TileProvider` based on the name query Returns a matching :class:`TileProvider` from the :class:`Bunch` if the ``name`` contains the same letters in the same order as the provider's name irrespective of the letter case, spaces, dashes and other characters. See examples for details. Parameters ---------- name : str Name of the tile provider. Formatting does not matter. Returns ------- match: TileProvider Examples -------- >>> import xyzservices.providers as xyz All these queries return the same ``CartoDB.Positron`` TileProvider: >>> xyz.query_name("CartoDB Positron") >>> xyz.query_name("cartodbpositron") >>> xyz.query_name("cartodb-positron") >>> xyz.query_name("carto db/positron") >>> xyz.query_name("CARTO_DB_POSITRON") >>> xyz.query_name("CartoDB.Positron") cni|]2\}}|t|3Sr ) translateQUERY_NAME_TRANSLATIONrD)r krIs r rz$Bunch.query_name.. sG   1 KK. / / 5 5 7 7   rz*No matching provider found for the query 'z'.)r;rOrXrYrD ValueError)rr5xyz_flat_lower name_cleans r query_namezBunch.query_names>   ,,..   ^^$:;;AACC  ' .!*- -NdNNNOOOrF)r1r2)NNNN) r<r=r5r=r>r?r@rAr1rr5r&r1r%) __name__ __module__ __qualname____doc__rrr)r;rUr^r rr rrs4&&& %%%%N""""L"&")-37 A A A A A F'P'P'P'P'P'PrrceZdZdZfdZddZddZ dddZddZe dZ ddZ e ddZ xZS)r%a$ A dict with attribute-access and that can be called to update keys Examples -------- You can create custom :class:`TileProvider` by passing your attributes to the object as it would have been a ``dict()``. It is required to always specify ``name``, ``url``, and ``attribution``. >>> public_provider = TileProvider( ... name="My public tiles", ... url="https://myserver.com/tiles/{z}/{x}/{y}.png", ... attribution="(C) xyzservices", ... ) Alternatively, you can create it from a dictionary of attributes. When specifying a placeholder for the access token, please use the ``""`` string to ensure that :meth:`~xyzservices.TileProvider.requires_token` method works properly. >>> private_provider = TileProvider( ... { ... "url": "https://myserver.com/tiles/{z}/{x}/{y}.png?apikey={accessToken}", ... "attribution": "(C) xyzservices", ... "accessToken": "", ... "name": "my_private_provider", ... } ... ) It is customary to include ``html_attribution`` attribute containing HTML string as ``'© OpenStreetMap contributors'`` alongisde a plain-text ``attribution``. You can then fetch all information as attributes: >>> public_provider.url 'https://myserver.com/tiles/{z}/{x}/{y}.png' >>> public_provider.attribution '(C) xyzservices' To ensure you will be able to use the tiles, you can check if the :class:`TileProvider` requires a token or API key. >>> public_provider.requires_token() False >>> private_provider.requires_token() True You can also generate URL in the required format with or without placeholders: >>> public_provider.build_url() 'https://myserver.com/tiles/{z}/{x}/{y}.png' >>> private_provider.build_url(x=12, y=21, z=11, accessToken="my_token") 'https://myserver.com/tiles/11/12/21.png?access_token=my_token' ctj|i|g}dD]-}||vr||.t |dkr(dd|d}t |dS)N)r5url attributionrzyThe attributes `name`, `url`, and `attribution` are required to initialise a `TileProvider`. Please provide values for: `z`, ``)super__init__rrEr+joinr)rargskwargsmissingelmsg __class__s r rkzTileProvider.__init__is$)&)))0 # #B$ #r""" w<>> import xyzservices.providers as xyz >>> xyz.CartoDB.DarkMatter.build_url() 'https://a.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}.png' >>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5) 'https://a.basemaps.cartocdn.com/dark_all/5/9/11.png' >>> xyz.CartoDB.DarkMatter.build_url(x=9, y=11, z=5, scale_factor="@2x") 'https://a.basemaps.cartocdn.com/dark_all/5/9/11@2x.png' >>> xyz.MapBox.build_url(accessToken="my_token") 'https://api.mapbox.com/styles/v1/mapbox/streets-v11/tiles/{z}/{x}/{y}?access_token=my_token' Nz{x}z{y}z{z}zToken is required for this provider, but not provided. You can either update TileProvider or pass respective keywords to build_url().rgrr subdomainsabcrz{s})r r{r|srr )ryrtr>r[popformat) rr r{r|r}r~rnr7rgrrrs r build_urlzTileProvider.build_urlsj99;;  A  A  A  " " $ $ "  ll5!!  &A LLd # # # # S"%%A  !lE::J1 AAAsz>Aa1>>X>>>rboolc|D]*\}}t|trd|vr ||jvrdS+dS)al Returns ``True`` if the TileProvider requires access token to fetch tiles. The token attribute name vary and some :class:`TileProvider` objects may require more than one token (e.g. ``HERE``). The information is deduced from the presence of `'"`` string to ensure that :meth:`~xyzservices.TileProvider.requires_token` method works properly. Returns ------- bool Examples -------- >>> import xyzservices.providers as xyz >>> xyz.MapBox.requires_token() True >>> xyz.CartoDB.Positron False We can specify this API key by calling the object or overriding the attribute. Overriding the attribute will alter existing object: >>> xyz.OpenWeatherMap.Clouds["apiKey"] = "my-private-api-key" Calling the object will return a copy: >>> xyz.OpenWeatherMap.Clouds(apiKey="my-private-api-key") z zTileProvider.requires_tokensYH   HC#s## #(= $(? 44urcNd|vr|dS|dS)Nhtml_attributionrhrrs r rzTileProvider.html_attributions.  , ,*+ +M""rFcd}|D]\}}|dkr |d|d|dz }|rdn dtd}d|d |jd |d }|S) Nr r5z
    z
    z
    r!r"r#z
    xyzservices.TileProvider
    z
    z\
    )rOr*r5)rr provider_inforrr/r0s r r)zTileProvider._repr_html_s   N NHCf} N!Mc!M!M3!M!M!MM ?"?I"?"?"?   ,09   '   " rr5c d}tjtj|dt |d}|D]}|d|krnt d|d|d}tjtj|d|}||d|d |d |d |d  S)a Creates a :class:`TileProvider` object based on the definition from the `Quick Map Services `__ open catalog. Parameters ---------- name : str Service name Returns ------- :class:`TileProvider` Examples -------- >>> from xyzservices.lib import TileProvider >>> provider = TileProvider.from_qms("OpenTopoMap") z*https://qms.nextgis.com/api/v1/geoservicesz /?search=z &type=tmsr5z Service 'z ' not found.id/rgz_minz_maxcopyright_text)r5rgmin_zoommax_zoomrh)jsonloadurllibrequesturlopenrr[get)clsr5 QMS_API_URLservicesservice service_idservice_detailss r from_qmszTileProvider.from_qms"s'(C 9 N " "k#R#RE$KK#R#R#R S S    = =Gv$&  ;;;;<< <T] ) N " "k#@#@J#@#@ A A  s (&$((11$((11'++,<==     r)r1r%)NNNNT) r rzr{rzr|rzr}r=r~r?r1r&)r1rr_r`)rarbrcrdrkrvryrr>propertyrr) classmethodr __classcell__)rrs@r r%r%+s;;z & & & & &  (,'+'+&*)- U?U?U?U?U?n((((T##X# 4* * * [* * * * * rr%ctj|}t}|D]Q}||dvrt ||<3tfdD||<R|S)Nrgc<i|]}|t|Sr rx)r ir7s r rz_load_json..^s'@@@!L!--@@@r)rloadsrrr%)fdata providers provider_namer7s @r _load_jsonrPs :a==DI    & HMMOO # '3H'='=Im $ $(-@@@@x@@@((Im $ $ ru8 /* CSS stylesheet for displaying xyzservices objects in Jupyter.*/ .xyz-wrap { --xyz-border-color: var(--jp-border-color2, #ddd); --xyz-font-color2: var(--jp-content-font-color2, rgba(128, 128, 128, 1)); --xyz-background-color-white: var(--jp-layout-color1, white); --xyz-background-color: var(--jp-layout-color2, rgba(128, 128, 128, 0.1)); } html[theme=dark] .xyz-wrap, body.vscode-dark .xyz-wrap, body.vscode-high-contrast .xyz-wrap { --xyz-border-color: #222; --xyz-font-color2: rgba(255, 255, 255, 0.54); --xyz-background-color-white: rgba(255, 255, 255, 1); --xyz-background-color: rgba(255, 255, 255, 0.05); } .xyz-header { padding-top: 6px; padding-bottom: 6px; margin-bottom: 4px; border-bottom: solid 1px var(--xyz-border-color); } .xyz-header>div { display: inline; margin-top: 0; margin-bottom: 0; } .xyz-obj, .xyz-name { margin-left: 2px; margin-right: 10px; } .xyz-obj { color: var(--xyz-font-color2); } .xyz-attrs { grid-column: 1 / -1; } dl.xyz-attrs { padding: 0 5px 0 5px; margin: 0; display: grid; grid-template-columns: 135px auto; background-color: var(--xyz-background-color); } .xyz-attrs dt, dd { padding: 0; margin: 0; float: left; padding-right: 10px; width: auto; } .xyz-attrs dt { font-weight: normal; grid-column: 1; } .xyz-attrs dd { grid-column: 2; white-space: pre-wrap; word-break: break-all; } .xyz-details ul>li>label>span { color: var(--xyz-font-color2); padding-left: 10px; } .xyz-inside { display: none; } .xyz-checkbox:checked~.xyz-inside { display: contents; } .xyz-collapsible li>input { display: none; } .xyz-collapsible>li>label { cursor: pointer; } .xyz-collapsible>li>label:hover { color: var(--xyz-font-color2); } ul.xyz-collapsible { list-style: none!important; padding-left: 20px!important; } .xyz-checkbox+label:before { content: '►'; font-size: 11px; } .xyz-checkbox:checked+label:before { content: '▼'; } .xyz-wrap { margin-bottom: 10px; } )rd __future__rrr'urllib.requestrtypingrrr urllib.parserr& maketransrYr2rr%rr*r rr rs#""""" ,,,,,,,,,,'@'@x'@'@'@AAYPYPYPYPYPDYPYPYPxb b b b b 5b b b J (t  r