phS S r SSKJr SSKrSSKrSSKrSSKJr SSK J
r
\ R S V s0 s H o S_M sn 5 r
" S S \5 r " S
S \5 rS rS
rgs sn f )z"
Utilities to support XYZservices
) annotationsN)Callable)quotez., -_/ c j \ rS rSrSrS rS rS S jrS S jr S
SS jjr SS jr
S
r g)Bunch a[ A 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}'
c b U R U5 $ ! [ a n[ U5 UeS nAff = fN) __getitem__KeyErrorAttributeError)selfkeyerrs gC:\Users\julio\OneDrive\Documentos\Trabajo\IdeasFrscas\Cabanna\env\Lib\site-packages\xyzservices/lib.py __getattr__Bunch.__getattr__+ s5 /##C( ( / %3 . /s
. ).c " U R 5 $ r )keysr s r __dir__
Bunch.__dir__1 s yy{ c ( SnU Ha n[ X [ 5 ( a SnOSn[ [ R " 5 5 nUSU SU SU SU SX R S S
9 S 3 -
nMc U( a SO S [ S
3nSU S[ U 5 SU S3nU$ )Nr zxyzservices.TileProviderzxyzservices.BunchzO
z zM
T)insidez6
)
isinstance TileProviderstruuiduuid4 _repr_html_ CSS_STYLElen)r r childrenr objuidstylehtmls r r% Bunch._repr_html_4 s C$)\220)djjl#C ,,/5 1 EC5u 5Y**$*78 9
H
GI;h"? + ,/t9+ 6 "
# " r c , ^^ 0 mUU4S jmT" U 5 T$ )a Return 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
c > [ U [ 5 ( a U TU R ' g U R 5 H nT" U5 M
g r )r r! namevalues)providerprov_get_providersflats r r4 %Bunch.flatten.._get_providerss s7 (L11&.X]]# $OO -D"4( .r )r r4 r5 s @@r flatten
Bunch.flattenZ s . ) t r Nc . ^^ S mUU4S jmT" U UUUUS9$ )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)
c / nUbg SnU R 5 H@ n[ U[ 5 ( d M UR 5 UR 5 ; d M> Sn O UR U5 UbA SnUR 5 U R
R 5 ; a SnUR U5 Ub( SnU R
5 UL a SnUR U5 [ U5 $ )NFT)r1 r r" lowerappendr0 requires_tokenall) r2 keywordr0 r> cond
keyword_matchv
name_match token_matchs r _validate Bunch.filter.._validate s D" %
! *A!!S))gmmo.J(,
+ M* "
::<8==#6#6#88!%J J' ) # **,>"&K K(t9 r c > [ 5 nU R 5 H_ u pg[ U[ 5 ( a. Uc T
" UUUUS9( a XuU' M1 M3 U" U5 ( a XuU' MF MH T " UUUUUS9nU( d M[ XU' Ma U$ )N)r@ r0 r> r@ r0 r> function)r itemsr r! ) bunchr@ r0 r> rJ newr valuefiltered
_filter_bunchrF s r rP #Bunch.filter.._filter_bunch s 'C #kkm
e\22 '$ !$+!%+9 (-H
$E??',H + - ' !'5!) H x#+C/ ,2 Jr rI r7 )r r@ r0 r> rJ rP rF s @@r filter Bunch.filter~ s, D 2 : )
r c , U R 5 R 5 VVs0 s H) u p#UR [ 5 R 5 U_M+ nnnUR [ 5 R 5 nXT; a XE $ [ SU S35 es snnf )a Return :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")
z*No matching provider found for the query 'z'.)r8 rK translateQUERY_NAME_TRANSLATIONr<
ValueError)r r0 krC xyz_flat_lower
name_cleans r
query_nameBunch.query_name s B ,,.
.
KK. / 5 5 7 :.
^^$:;AAC
'!- -EdV2NOO
s 0Br7 F)returndict)NNNN)
r@
str | Noner0 r` r> bool | NonerJ z Callable[[TileProvider], bool]r^ r r0 r" r^ r! ) __name__
__module__ __qualname____firstlineno____doc__r r r% r8 rR r[ __static_attributes__r7 r r r r sm 4/ $L"L # &*37 ~
~
~
$ ~
1 ~
~
@'Pr r c ^ \ rS rSrSrU 4S jrS S jrS S jr S
SS jjrSS jr \
S 5 r SS jr \
SS
j5 rS rU =r$ )r! i( at
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'
c > [ TU ] " U0 UD6 / nS H) nX@R 5 ; d M UR U5 M+ [ U5 S: a SSR U5 S3n[
U5 eg )N)r0 url attributionr zyThe attributes `name`, `url`, and `attribution` are required to initialise a `TileProvider`. Please provide values for: `z`, ``)super__init__r r= r' joinr )r argskwargsmissingelmsg __class__s r ro TileProvider.__init__f s~
$)&)0B$r" 1 w [ U 5 nUR U5 U$ r )r! update)r rr rM s r __call__TileProvider.__call__u s 4
6
r c [ U 5 nU$ r )r! )r rM s r copyTileProvider.copyz s 4
r c U R 5 nUc SnUc SnUc SnUR U5 UR 5 ( a [ S5 eUR S5 nU( a Un UR SS5 OUR SS5 n U( a UR S S
5 n
U
S n OS n UR
" SXX;U S
.UD6$ )a
Build the URL of tiles from the :class:`TileProvider` object
Can return URL with placeholders or the final tile URL.
Parameters
----------
x, y, z : int (optional)
tile number
scale_factor : str (optional)
Scale factor (where supported). For example, you can get double resolution
(512 x 512) instead of standard one (256 x 256) with ``"@2x"``. If you want
to keep a placeholder, pass `"{r}"`.
fill_subdomain : bool (optional, default True)
Fill subdomain placeholder with the first available subdomain. If False, the
URL will contain ``{s}`` placeholder for subdomain.
**kwargs
Other potential attributes updating the :class:`TileProvider`.
Returns
-------
url : str
Formatted URL
Examples
--------
>>> 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().rk rr
subdomainsabcr z{s})xyzsr r7 )r} ry r> rW popformat) r r r r scale_factorfill_subdomainrr r2 rk r r r s r build_urlTileProvider.build_url~ s j 99; 9A 9A 9A " " $ $ "
ll5! A LLd # S"%A ! lE:J1
AAzz>Aa>X>>r c U R 5 H5 u p[ U[ 5 ( d M SU; d M$ XR ; d M5 g g)a
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 TileProvider.requires_token s; H
HC#s###(=#/ % r c " SU ; a U S $ U S $ )Nhtml_attributionrl r7 r s r r TileProvider.html_attribution s! %*+ +M""r c SnU R 5 H u p4US:w d M
USU SU S3-
nM U( a SO S[ S3nSU S U R S
U S 3nU$ ) Nr r0 z
z z r r r z
)rK r& r0 )r r
provider_infor r r+ r, s r r% TileProvider._repr_html_ s
HCf} :cU2B3%u!MM
% GI;h"? + ,099+ 6 ' ( " r c Sn[ R " [ R R U S[ U5 S35 5 nU H nUS U:X d M O [
SU S35 eUS n[ R " [ R R U SU 35 5 nU " US US UR S
5 UR S 5 UR S 5 S
9$ )aW
Creates a :class:`TileProvider` object based on the definition from
the `Quick Map Services r sr # x'@x!2x'@A UPD UPpa
5 a
H &t
e (As A