aBelT d Z ddlmZ ddlZddlZddlZddlmZm Z m
Z
ddl m Z e
j dD ci c] } | d c} Z G d d e Z G d
d e Zd Zd
Zyc c} w )z"
Utilities to support XYZservices
) annotationsN)OptionalCallableUnion)quotez., -_/ c X e Zd ZdZd Zd Zd dZd
dZ d d dZd
dZ y)Buncha 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 V | j | S # t $ r t | w xY wN) __getitem__KeyErrorAttributeError)selfkeys /lib/python3.12/site-packages/xyzservices/lib.py __getattr__zBunch.__getattr__* s2 &##C( ( & % % &s (c " | j S r keysr s r __dir__z
Bunch.__dir__0 s yy{ c 4 d}| j D ]_ }t | | t rd}nd}t t j
}|d| d| d| d| d| | j
d
d z
}a |rdn d t d
}d| dt | d| d}|S )Nr zxyzservices.TileProviderzxyzservices.BunchzO
z zM
T)insidez6
) r
isinstance TileProviderstruuiduuid4 _repr_html_ CSS_STYLElen)r r childrenr objuidstylehtmls r r$ zBunch._repr_html_3 s 99; C$s)\20)djjl#C ,,/5 1 EC5u 5#Y**$*78 9
H
GI;h"? + ,/t9+ 6 "
# " r c * i fd | S )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 t | t r| | j < y | j D ]
} | y r )r r namevalues)providerprov_get_providersflats r r2 z%Bunch.flatten.._get_providerss s9 (L1&.X]]# $OO - )D"4()r )r r2 r3 s @@r flattenz
Bunch.flattenZ s . ) t r Nc 2 d fd | |||| 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)
c g }|]d}| j D ]7 }t |t s|j |j v s5d} n |j | |?d}|j | j
j v rd}|j | |'d}| j
|u rd}|j | t | S )NFT)r/ r r! lowerappendr. requires_tokenall) r0 keywordr. r: cond
keyword_matchv
name_match token_matchs r _validatez Bunch.filter.._validate s D" %
! * "A!!S)"==?aggi7,0M ! "
M* "
::<8==#6#6#88!%J J' ) # **,>"&K K(t9 r c t }| j D ]N \ }}t |t r$|
|||| s%|||< + || s4|||< : ||||| }|sJ|||< P |S )N)r< r. r: r< r. r: function)r
itemsr r ) bunchr< r. r: rE newr valuefiltered
_filter_bunchrB s r rK z#Bunch.filter.._filter_bunch s 'C #kkm
,
U e\2 '$ !$+!%+9 (-CH#E?',CH - ' !'5!) H #+C1
,4 Jr rD r4 )r r< r. r: rE rK rB s @@r filterz Bunch.filter~ s, D 6 < )
r c ( | j j D ci c]) \ }}|j t j |+ }}}|j t j }||v r|| S t d| d c c}}w )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'.)r5 rF translateQUERY_NAME_TRANSLATIONr8
ValueError)r r. kr? xyz_flat_lower
name_cleans r
query_namezBunch.query_name s B ,,.
1
KK. / 5 5 7 :
^^$:;AAC
'!*- -EdV2NOO
s .BF)returndict)NNNN)
r<
Optional[str]r. rX r: Optional[bool]rE z Callable[[TileProvider], bool]rV r
r. r! rV r )
__name__
__module__ __qualname____doc__r r r$ r5 rL rT r4 r r r
r
sm 4& %N"L "& ")-37 A
A
A
' A
1 A
A
F'Pr r
c e Zd ZdZ fdZd
dZd
dZ d d dZd
dZe d Z
ddZ e dd Z
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'
c t | |i | g }dD ]& }|| j vs|j | ( t | dkD r ddj | d}t
| y )N)r. url attributionr zyThe attributes `name`, `url`, and `attribution` are required to initialise a `TileProvider`. Please provide values for: `z`, ``)super__init__r r9 r& joinr )r argskwargsmissingelmsg __class__s r re zTileProvider.__init__i s
$)&)0 #B$r" # w t | }|j | |S r )r updater rh rH s r __call__zTileProvider.__call__x s 4
6
r c t | }|S r )r ro s r copyzTileProvider.copy} s 4
r c n | j }|d}|d}|d}|j | |j r t d |j d }|r|} |j dd n|j dd } |r|j d d
}
|
d } nd } |j
d|||| | d
|S )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().ra rr
subdomainsabcr z{s})xyzsrt r4 )rr rn r: rP popformat) r rw rx ry scale_factorfill_subdomainrh r0 ra rt ru rz s r build_urlzTileProvider.build_url s j 99; 9A 9A 9A " " $ "
ll5! A LLd # S"%A ! lE:J1
AAszz>Aa1>X>>r c | j D ]+ \ }}t |t sd|v s || j v s+ y y)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 z z r r r z
)rF r% r. )r r
provider_infor r r* r+ s r r$ zTileProvider._repr_html_ s
NHCf} :cU2B3%u!MM
N GI;h"? + ,099+ 6 ' ( " r c d}t j t j j | dt | d }|D ] }|d |k( s n t
d| d |d }t j t j j | d| } | |d |d |j d
|j d |j d
S )a
Creates a :class:`TileProvider` object based on the definition from
the `Quick Map Services r ss # , , x'@!2'@A YPD YPxb
5 b
J (t
q (As
A!