Map

maplibre.Map

Bases: object

Map

Parameters:

Name	Type	Description	Default
map_options	MapOptions	Map options.	MapOptions()
**kwargs		Keyword arguments that are appended to the MapOptions object.	{}

Examples:

>>> from maplibre.map import Map, MapOptions

>>> map_options = MapOptions(center=(9.5, 51.31667), zoom=8)
>>> map = Map(map_options)
>>> dict(map)
{'mapOptions': {'center': (9.5, 51.31667), 'style': 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json', 'zoom': 8}, 'calls': []}

Source code in maplibre/map.py

class Map(object):
    """Map

    Args:
        map_options (MapOptions): Map options.
        **kwargs: Keyword arguments that are appended to the `MapOptions` object.

    Examples:
        >>> from maplibre.map import Map, MapOptions

        >>> map_options = MapOptions(center=(9.5, 51.31667), zoom=8)
        >>> map = Map(map_options)
        >>> dict(map)
        {'mapOptions': {'center': (9.5, 51.31667), 'style': 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json', 'zoom': 8}, 'calls': []}
    """

    MESSAGE = "not implemented yet"

    def __init__(self, map_options: MapOptions = MapOptions(), **kwargs):
        self.map_options = map_options.to_dict() | kwargs
        self._message_queue = []

    def __iter__(self):
        for k, v in self.to_dict().items():
            yield k, v

    def to_dict(self) -> dict:
        return {"mapOptions": self.map_options, "calls": self._message_queue}

    """
    @property
    def sources(self) -> list:
        return [item["data"] for item in self._calls if item["name"] == "addSource"]

    @property
    def layers(self) -> list:
        return [item["data"] for item in self._calls if item["name"] == "addLayer"]
    """

    # TODO: Rename to add_map_call
    def add_call_(self, func_name: str, params: list) -> None:
        self._message_queue.append(
            {"name": "applyFunc", "data": {"funcName": func_name, "params": params}}
        )

    def add_call(self, method_name: str, *args) -> None:
        """Add a method call that is executed on the map instance

        Args:
            method_name (str): The name of the map method to be executed.
            *args (any): The arguments to be passed to the map method.
        """
        # TODO: Pass as dict? {"name": method_name, "args": args}
        call = [method_name, args]
        self._message_queue.append(call)

    def add_control(
        self,
        control: Control,
        position: [str | ControlPosition] = ControlPosition.TOP_RIGHT,
    ) -> None:
        """Add a control to the map

        Args:
            control (Control): The control to be added to the map.
            position (str | ControlPosition): The position of the control.
        """
        self.add_call(
            "addControl",
            control.type,
            control.to_dict(),
            ControlPosition(position).value,
        )

    def add_source(self, id: str, source: [Source | dict]) -> None:
        """Add a source to the map

        Args:
            id (str): The unique ID of the source.
            source (Source | dict): The source to be added to the map.
        """
        if isinstance(source, Source):
            source = source.to_dict()

        self.add_call("addSource", id, source)

    def add_layer(self, layer: [Layer | dict], before_id: str = None) -> None:
        """Add a layer to the map

        Args:
            layer (Layer | dict): The Layer to be added to the map.
            before_id (str): The ID of an existing layer to insert the new layer before,
                resulting in the new layer appearing visually beneath the existing layer.
                If `None`, the new layer will appear above all other layers.
        """
        if isinstance(layer, Layer):
            layer = layer.to_dict()

        self.add_call("addLayer", layer, before_id)

    def add_marker(self, marker: Marker) -> None:
        """Add a marker to the map

        Args:
            marker (Marker): The marker to be added to the map.
        """
        self.add_call("addMarker", marker.to_dict())

    def add_popup(self, layer_id: str, prop: str = None, template: str = None) -> None:
        """Add a popup to the map

        Args:
            layer_id (str): The layer to which the popup is added.
            prop (str): The property of the source to be displayed. If `None`, all properties are displayed.
            template (str): A mustache template. If supplied, `prop` is ignored.
        """
        self.add_call("addPopup", layer_id, prop, template)

    def add_tooltip(
        self, layer_id: str, prop: str = None, template: str = None
    ) -> None:
        """Add a tooltip to the map

        Args:
            layer_id (str): The layer to which the tooltip is added.
            prop (str): The property of the source to be displayed. If `None`, all properties are displayed.
            template (str): A mustache template. If supplied, `prop` is ignored.

        Examples:
            >>> map = Map()
            >>> # ...
            >>> map.add_tooltip("test-layer", template="Name: {{ name }}")
        """
        self.add_call("addTooltip", layer_id, prop, template)

    def set_filter(self, layer_id: str, filter_: list):
        """Update the filter of a layer

        Args:
            layer_id (str): The name of the layer to be updated.
            filter_ (list): The filter expression that is applied to the source of the layer.
        """
        self.add_call("setFilter", layer_id, filter_)

    def set_paint_property(self, layer_id: str, prop: str, value: any) -> None:
        """Update the paint property of a layer

        Args:
            layer_id (str): The name of the layer to be updated.
            prop (str): The name of the paint property to be updated.
            value (any): The new value of the paint property.
        """
        self.add_call("setPaintProperty", layer_id, prop, value)

    def set_layout_property(self, layer_id: str, prop: str, value: any) -> None:
        """Update a layout property of a layer

        Args:
            layer_id (str): The name of the layer to be updated.
            prop (str): The name of the layout property to be updated.
            value (any): The new value of the layout property.
        """
        self.add_call("setLayoutProperty", layer_id, prop, value)

    def set_data(self, source_id: str, data: dict) -> None:
        """Update the data of a GeoJSON source

        Args:
            source_id (str): The name of the source to be updated.
            data (dict): The data of the source.
        """
        self.add_call("setSourceData", source_id, data)

    def set_visibility(self, layer_id: str, visible: bool = True) -> None:
        """Update the visibility of a layer

        Args:
            layer_id (str): The name of the layer to be updated.
            visible (bool): Whether the layer is visible or not.
        """
        value = "visible" if visible else "none"
        self.add_call("setLayoutProperty", layer_id, "visibility", value)

    def to_html(self, title: str = "My Awesome Map", **kwargs) -> str:
        """Render to html

        Args:
            title (str): The Title of the HTML document.
            **kwargs (Any): Additional keyword arguments that are passed to the template.
                Currently, `style` is the only supported keyword argument.

        Examples:
            >>> from maplibre import Map

            >>> map = Map()
            >>> with open("/tmp/map.html", "w") as f:
            ...     f.write(map.to_html(style="height: 800px;") # doctest: +SKIP
        """
        js_lib = read_internal_file("srcjs", "pywidget.js")
        js_snippet = Template(js_template).render(data=json.dumps(self.to_dict()))
        css = read_internal_file("srcjs", "pywidget.css")
        headers = [f"<style>{css}</style>"]

        # Deck.GL headers
        add_deckgl_headers = "addDeckOverlay" in [
            item[0] for item in self._message_queue
        ]
        # TODO: Set version in constants
        deckgl_headers = (
            [
                '<script src="https://unpkg.com/deck.gl@9.0.16/dist.min.js"></script>',
                '<script src="https://unpkg.com/@deck.gl/json@9.0.16/dist.min.js"></script>',
            ]
            if add_deckgl_headers
            else []
        )

        # Mapbox Draw headers
        add_mapbox_draw_headers = "addMapboxDraw" in [
            item[0] for item in self._message_queue
        ]
        # TODO: Set version in constants
        mapbox_draw_headers = (
            [
                # "<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.js'></script>",
                # "<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.css' type='text/css' />",
                "<script src='https://www.unpkg.com/@mapbox/mapbox-gl-draw@1.4.3/dist/mapbox-gl-draw.js'></script>",
                "<link rel='stylesheet' href='https://www.unpkg.com/@mapbox/mapbox-gl-draw@1.4.3/dist/mapbox-gl-draw.css' type='text/css' />",
            ]
            if add_mapbox_draw_headers
            else []
        )

        output = Template(html_template).render(
            js="\n".join([js_lib, js_snippet]),
            title=title,
            headers=headers + deckgl_headers + mapbox_draw_headers,
            **kwargs,
        )
        return output

    # -------------------------
    # Plugins
    # -------------------------
    def add_deck_layers(self, layers: list[dict], tooltip: str | dict = None) -> None:
        """Add Deck.GL layers to the layer stack

        Args:
            layers (list[dict]): A list of dictionaries containing the Deck.GL layers to be added.
            tooltip (str | dict): Either a single mustache template string applied to all layers
                or a dictionary where keys are layer ids and values are mustache template strings.
        """
        self.add_call("addDeckOverlay", layers, tooltip)

    def set_deck_layers(self, layers: list[dict], tooltip: str | dict = None) -> None:
        """Update Deck.GL layers

        Args:
            layers (list[dict]): A list of dictionaries containing the Deck.GL layers to be updated.
                New layers will be added. Missing layers will be removed.
            tooltip (str | dict): Must be set to keep tooltip even if it did not change.
        """
        self.add_call("setDeckLayers", layers, tooltip)

    def add_mapbox_draw(
        self,
        options: dict | MapboxDrawOptions = None,
        position: str | ControlPosition = ControlPosition.TOP_LEFT,
        geojson: dict = None,
    ) -> None:
        """Add MapboxDraw controls to the map

        Note:
            See [MapboxDraw API Reference](https://github.com/mapbox/mapbox-gl-draw/blob/main/docs/API.md)
                for available options.

        Args:
            options (dict | MapboxDrawOptions): MapboxDraw options.
            position (str | ControlPosition): The position of the MapboxDraw controls.
            geojson (dict): A GeoJSON Feature, FeatureCollection or Geometry to be added to the draw layer.
        """
        if isinstance(options, MapboxDrawOptions):
            options = options.to_dict()

        self.add_call(
            "addMapboxDraw", options or {}, ControlPosition(position).value, geojson
        )

add_call(method_name, *args)

Add a method call that is executed on the map instance

Parameters:

Name	Type	Description	Default
method_name	str	The name of the map method to be executed.	required
*args	any	The arguments to be passed to the map method.	()

Source code in maplibre/map.py

def add_call(self, method_name: str, *args) -> None:
    """Add a method call that is executed on the map instance

    Args:
        method_name (str): The name of the map method to be executed.
        *args (any): The arguments to be passed to the map method.
    """
    # TODO: Pass as dict? {"name": method_name, "args": args}
    call = [method_name, args]
    self._message_queue.append(call)

add_control(control, position=ControlPosition.TOP_RIGHT)

Add a control to the map

Parameters:

Name	Type	Description	Default
control	Control	The control to be added to the map.	required
position	str | ControlPosition	The position of the control.	TOP_RIGHT

Source code in maplibre/map.py

def add_control(
    self,
    control: Control,
    position: [str | ControlPosition] = ControlPosition.TOP_RIGHT,
) -> None:
    """Add a control to the map

    Args:
        control (Control): The control to be added to the map.
        position (str | ControlPosition): The position of the control.
    """
    self.add_call(
        "addControl",
        control.type,
        control.to_dict(),
        ControlPosition(position).value,
    )

add_deck_layers(layers, tooltip=None)

Add Deck.GL layers to the layer stack

Parameters:

Name	Type	Description	Default
layers	list[dict]	A list of dictionaries containing the Deck.GL layers to be added.	required
tooltip	str | dict	Either a single mustache template string applied to all layers or a dictionary where keys are layer ids and values are mustache template strings.	None

Source code in maplibre/map.py

def add_deck_layers(self, layers: list[dict], tooltip: str | dict = None) -> None:
    """Add Deck.GL layers to the layer stack

    Args:
        layers (list[dict]): A list of dictionaries containing the Deck.GL layers to be added.
        tooltip (str | dict): Either a single mustache template string applied to all layers
            or a dictionary where keys are layer ids and values are mustache template strings.
    """
    self.add_call("addDeckOverlay", layers, tooltip)

add_layer(layer, before_id=None)

Add a layer to the map

Parameters:

Name	Type	Description	Default
layer	Layer | dict	The Layer to be added to the map.	required
before_id	str	The ID of an existing layer to insert the new layer before, resulting in the new layer appearing visually beneath the existing layer. If None, the new layer will appear above all other layers.	None

Source code in maplibre/map.py

def add_layer(self, layer: [Layer | dict], before_id: str = None) -> None:
    """Add a layer to the map

    Args:
        layer (Layer | dict): The Layer to be added to the map.
        before_id (str): The ID of an existing layer to insert the new layer before,
            resulting in the new layer appearing visually beneath the existing layer.
            If `None`, the new layer will appear above all other layers.
    """
    if isinstance(layer, Layer):
        layer = layer.to_dict()

    self.add_call("addLayer", layer, before_id)

add_mapbox_draw(options=None, position=ControlPosition.TOP_LEFT, geojson=None)

Add MapboxDraw controls to the map

Note

See MapboxDraw API Reference for available options.

Parameters:

Name	Type	Description	Default
options	dict | MapboxDrawOptions	MapboxDraw options.	None
position	str | ControlPosition	The position of the MapboxDraw controls.	TOP_LEFT
geojson	dict	A GeoJSON Feature, FeatureCollection or Geometry to be added to the draw layer.	None

Source code in maplibre/map.py

def add_mapbox_draw(
    self,
    options: dict | MapboxDrawOptions = None,
    position: str | ControlPosition = ControlPosition.TOP_LEFT,
    geojson: dict = None,
) -> None:
    """Add MapboxDraw controls to the map

    Note:
        See [MapboxDraw API Reference](https://github.com/mapbox/mapbox-gl-draw/blob/main/docs/API.md)
            for available options.

    Args:
        options (dict | MapboxDrawOptions): MapboxDraw options.
        position (str | ControlPosition): The position of the MapboxDraw controls.
        geojson (dict): A GeoJSON Feature, FeatureCollection or Geometry to be added to the draw layer.
    """
    if isinstance(options, MapboxDrawOptions):
        options = options.to_dict()

    self.add_call(
        "addMapboxDraw", options or {}, ControlPosition(position).value, geojson
    )

add_marker(marker)

Add a marker to the map

Parameters:

Name	Type	Description	Default
marker	Marker	The marker to be added to the map.	required

Source code in maplibre/map.py

def add_marker(self, marker: Marker) -> None:
    """Add a marker to the map

    Args:
        marker (Marker): The marker to be added to the map.
    """
    self.add_call("addMarker", marker.to_dict())

add_popup(layer_id, prop=None, template=None)

Add a popup to the map

Parameters:

Name	Type	Description	Default
layer_id	str	The layer to which the popup is added.	required
prop	str	The property of the source to be displayed. If None, all properties are displayed.	None
template	str	A mustache template. If supplied, prop is ignored.	None

Source code in maplibre/map.py

def add_popup(self, layer_id: str, prop: str = None, template: str = None) -> None:
    """Add a popup to the map

    Args:
        layer_id (str): The layer to which the popup is added.
        prop (str): The property of the source to be displayed. If `None`, all properties are displayed.
        template (str): A mustache template. If supplied, `prop` is ignored.
    """
    self.add_call("addPopup", layer_id, prop, template)

add_source(id, source)

Add a source to the map

Parameters:

Name	Type	Description	Default
id	str	The unique ID of the source.	required
source	Source | dict	The source to be added to the map.	required

Source code in maplibre/map.py

def add_source(self, id: str, source: [Source | dict]) -> None:
    """Add a source to the map

    Args:
        id (str): The unique ID of the source.
        source (Source | dict): The source to be added to the map.
    """
    if isinstance(source, Source):
        source = source.to_dict()

    self.add_call("addSource", id, source)

add_tooltip(layer_id, prop=None, template=None)

Add a tooltip to the map

Parameters:

Name	Type	Description	Default
layer_id	str	The layer to which the tooltip is added.	required
prop	str	The property of the source to be displayed. If None, all properties are displayed.	None
template	str	A mustache template. If supplied, prop is ignored.	None

Examples:

>>> map = Map()
>>> # ...
>>> map.add_tooltip("test-layer", template="Name: {{ name }}")

Source code in maplibre/map.py

def add_tooltip(
    self, layer_id: str, prop: str = None, template: str = None
) -> None:
    """Add a tooltip to the map

    Args:
        layer_id (str): The layer to which the tooltip is added.
        prop (str): The property of the source to be displayed. If `None`, all properties are displayed.
        template (str): A mustache template. If supplied, `prop` is ignored.

    Examples:
        >>> map = Map()
        >>> # ...
        >>> map.add_tooltip("test-layer", template="Name: {{ name }}")
    """
    self.add_call("addTooltip", layer_id, prop, template)

set_data(source_id, data)

Update the data of a GeoJSON source

Parameters:

Name	Type	Description	Default
source_id	str	The name of the source to be updated.	required
data	dict	The data of the source.	required

Source code in maplibre/map.py

def set_data(self, source_id: str, data: dict) -> None:
    """Update the data of a GeoJSON source

    Args:
        source_id (str): The name of the source to be updated.
        data (dict): The data of the source.
    """
    self.add_call("setSourceData", source_id, data)

set_deck_layers(layers, tooltip=None)

Update Deck.GL layers

Parameters:

Name	Type	Description	Default
layers	list[dict]	A list of dictionaries containing the Deck.GL layers to be updated. New layers will be added. Missing layers will be removed.	required
tooltip	str | dict	Must be set to keep tooltip even if it did not change.	None

Source code in maplibre/map.py

def set_deck_layers(self, layers: list[dict], tooltip: str | dict = None) -> None:
    """Update Deck.GL layers

    Args:
        layers (list[dict]): A list of dictionaries containing the Deck.GL layers to be updated.
            New layers will be added. Missing layers will be removed.
        tooltip (str | dict): Must be set to keep tooltip even if it did not change.
    """
    self.add_call("setDeckLayers", layers, tooltip)

set_filter(layer_id, filter_)

Update the filter of a layer

Parameters:

Name	Type	Description	Default
layer_id	str	The name of the layer to be updated.	required
filter_	list	The filter expression that is applied to the source of the layer.	required

Source code in maplibre/map.py

def set_filter(self, layer_id: str, filter_: list):
    """Update the filter of a layer

    Args:
        layer_id (str): The name of the layer to be updated.
        filter_ (list): The filter expression that is applied to the source of the layer.
    """
    self.add_call("setFilter", layer_id, filter_)

set_layout_property(layer_id, prop, value)

Update a layout property of a layer

Parameters:

Name	Type	Description	Default
layer_id	str	The name of the layer to be updated.	required
prop	str	The name of the layout property to be updated.	required
value	any	The new value of the layout property.	required

Source code in maplibre/map.py

def set_layout_property(self, layer_id: str, prop: str, value: any) -> None:
    """Update a layout property of a layer

    Args:
        layer_id (str): The name of the layer to be updated.
        prop (str): The name of the layout property to be updated.
        value (any): The new value of the layout property.
    """
    self.add_call("setLayoutProperty", layer_id, prop, value)

set_paint_property(layer_id, prop, value)

Update the paint property of a layer

Parameters:

Name	Type	Description	Default
layer_id	str	The name of the layer to be updated.	required
prop	str	The name of the paint property to be updated.	required
value	any	The new value of the paint property.	required

Source code in maplibre/map.py

def set_paint_property(self, layer_id: str, prop: str, value: any) -> None:
    """Update the paint property of a layer

    Args:
        layer_id (str): The name of the layer to be updated.
        prop (str): The name of the paint property to be updated.
        value (any): The new value of the paint property.
    """
    self.add_call("setPaintProperty", layer_id, prop, value)

set_visibility(layer_id, visible=True)

Update the visibility of a layer

Parameters:

Name	Type	Description	Default
layer_id	str	The name of the layer to be updated.	required
visible	bool	Whether the layer is visible or not.	True

Source code in maplibre/map.py

def set_visibility(self, layer_id: str, visible: bool = True) -> None:
    """Update the visibility of a layer

    Args:
        layer_id (str): The name of the layer to be updated.
        visible (bool): Whether the layer is visible or not.
    """
    value = "visible" if visible else "none"
    self.add_call("setLayoutProperty", layer_id, "visibility", value)

to_html(title='My Awesome Map', **kwargs)

Render to html

Parameters:

Name	Type	Description	Default
title	str	The Title of the HTML document.	'My Awesome Map'
**kwargs	Any	Additional keyword arguments that are passed to the template. Currently, style is the only supported keyword argument.	{}

Examples:

>>> from maplibre import Map

>>> map = Map()
>>> with open("/tmp/map.html", "w") as f:
...     f.write(map.to_html(style="height: 800px;")

Source code in maplibre/map.py

def to_html(self, title: str = "My Awesome Map", **kwargs) -> str:
    """Render to html

    Args:
        title (str): The Title of the HTML document.
        **kwargs (Any): Additional keyword arguments that are passed to the template.
            Currently, `style` is the only supported keyword argument.

    Examples:
        >>> from maplibre import Map

        >>> map = Map()
        >>> with open("/tmp/map.html", "w") as f:
        ...     f.write(map.to_html(style="height: 800px;") # doctest: +SKIP
    """
    js_lib = read_internal_file("srcjs", "pywidget.js")
    js_snippet = Template(js_template).render(data=json.dumps(self.to_dict()))
    css = read_internal_file("srcjs", "pywidget.css")
    headers = [f"<style>{css}</style>"]

    # Deck.GL headers
    add_deckgl_headers = "addDeckOverlay" in [
        item[0] for item in self._message_queue
    ]
    # TODO: Set version in constants
    deckgl_headers = (
        [
            '<script src="https://unpkg.com/deck.gl@9.0.16/dist.min.js"></script>',
            '<script src="https://unpkg.com/@deck.gl/json@9.0.16/dist.min.js"></script>',
        ]
        if add_deckgl_headers
        else []
    )

    # Mapbox Draw headers
    add_mapbox_draw_headers = "addMapboxDraw" in [
        item[0] for item in self._message_queue
    ]
    # TODO: Set version in constants
    mapbox_draw_headers = (
        [
            # "<script src='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.js'></script>",
            # "<link rel='stylesheet' href='https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-draw/v1.4.3/mapbox-gl-draw.css' type='text/css' />",
            "<script src='https://www.unpkg.com/@mapbox/mapbox-gl-draw@1.4.3/dist/mapbox-gl-draw.js'></script>",
            "<link rel='stylesheet' href='https://www.unpkg.com/@mapbox/mapbox-gl-draw@1.4.3/dist/mapbox-gl-draw.css' type='text/css' />",
        ]
        if add_mapbox_draw_headers
        else []
    )

    output = Template(html_template).render(
        js="\n".join([js_lib, js_snippet]),
        title=title,
        headers=headers + deckgl_headers + mapbox_draw_headers,
        **kwargs,
    )
    return output

maplibre.MapOptions

Bases: BaseModel

Map options

Note

See MapOptions for more details.

Source code in maplibre/map.py

class MapOptions(BaseModel):
    """Map options

    Note:
        See [MapOptions](https://maplibre.org/maplibre-gl-js/docs/API/type-aliases/MapOptions) for more details.
    """

    model_config = ConfigDict(
        validate_assignment=True, extra="forbid", use_enum_values=False
    )
    antialias: bool = None
    attribution_control: bool = Field(None, serialization_alias="attributionControl")
    bearing: Union[int, float] = None
    bearing_snap: int = Field(None, serialization_alias="bearingSnap")
    bounds: tuple = None
    box_zoom: bool = Field(None, serialization_alias="boxZoom")
    center: tuple = None
    click_tolerance: int = Field(None, serialization_alias="clickTolerance")
    custom_attribution: bool = Field(None, serialization_alias="customAttribution")
    double_click_zoom: bool = Field(None, serialization_alias="doubleClickZoom")
    fade_duration: int = Field(None, serialization_alias="fadeDuration")
    fit_bounds_options: dict = Field(None, serialization_alias="fitBoundsOptions")
    hash: Union[bool, str] = None
    interactive: bool = None
    keyword: bool = None
    max_bounds: tuple = Field(None, serialization_alias="maxBounds")
    max_pitch: int = Field(None, serialization_alias="maxPitch")
    max_zoom: int = Field(None, serialization_alias="maxZoom")
    min_pitch: int = Field(None, serialization_alias="minPitch")
    min_zoom: int = Field(None, serialization_alias="minZoom")
    pitch: Union[int, float] = None
    scroll_zoom: bool = Field(None, serialization_alias="scrollZoom")
    style: Union[str, Carto, dict] = construct_carto_basemap_url(Carto.DARK_MATTER)
    zoom: Union[int, float] = None

    @field_validator("style")
    def validate_style(cls, v):
        if isinstance(v, Carto):
            return construct_carto_basemap_url(v)

        return v

maplibre.MapContext

Bases: Map

MapContext

Use this class to update a Map instance in a Shiny app. Must be used inside an async function.

See maplibre.Map for available methods.

Parameters:

Name	Type	Description	Default
id	string	The id of the map to be updated.	required
session	Session	A Shiny session. If None, the active session is used.	None

Source code in maplibre/mapcontext.py

class MapContext(Map):
    """MapContext

    Use this class to update a `Map` instance in a Shiny app.
    Must be used inside an async function.

    See `maplibre.Map` for available methods.

    Args:
        id (string): The id of the map to be updated.
        session (Session): A Shiny session.
            If `None`, the active session is used.
    """

    def __init__(self, id: str, session: Session = None) -> None:
        self.id = id
        self._session = require_active_session(session)
        self.map_options = {}
        self._message_queue = []

    async def __aenter__(self):
        return self

    async def __aexit__(self, exc_type, exc_val, exc_tb):
        await self.render()

    async def render(self):
        await self._session.send_custom_message(
            f"pymaplibregl-{self.id}", {"id": self.id, "calls": self._message_queue}
        )

maplibre.ipywidget.MapWidget

Bases: AnyWidget, Map

MapWidget

Use this class to display and update maps in Jupyter Notebooks.

See maplibre.Map for available methods.

Examples:

>>> from maplibre import MapOptions
>>> from maplibre.ipywidget import MapWidget as Map
>>> m = Map(MapOptions(center=(-123.13, 49.254), zoom=11, pitch=45))
>>> m

Source code in maplibre/ipywidget.py

class MapWidget(AnyWidget, Map):
    """MapWidget

    Use this class to display and update maps in Jupyter Notebooks.

    See `maplibre.Map` for available methods.

    Examples:
        >>> from maplibre import MapOptions
        >>> from maplibre.ipywidget import MapWidget as Map
        >>> m = Map(MapOptions(center=(-123.13, 49.254), zoom=11, pitch=45))
        >>> m # doctest: +SKIP
    """

    _esm = join(Path(__file__).parent, "srcjs", "ipywidget.js")
    # _css = join(Path(__file__).parent, "srcjs", "maplibre-gl.css")
    _css = join(Path(__file__).parent, "srcjs", "ipywidget.css")
    _use_message_queue = True
    _rendered = traitlets.Bool(False, config=True).tag(sync=True)
    map_options = traitlets.Dict().tag(sync=True)
    calls = traitlets.List().tag(sync=True)
    height = traitlets.Union([traitlets.Int(), traitlets.Unicode()]).tag(sync=True)

    # Interactions
    clicked = traitlets.Dict().tag(sync=True)
    center = traitlets.Dict().tag(sync=True)
    zoom = traitlets.Float().tag(sync=True)
    bounds = traitlets.Dict().tag(sync=True)
    draw_features_selected = traitlets.List().tag(sync=True)
    draw_feature_collection_all = traitlets.Dict().tag(sync=True)

    def __init__(self, map_options=MapOptions(), **kwargs) -> None:
        self.calls = []
        AnyWidget.__init__(self, **kwargs)
        Map.__init__(self, map_options, **kwargs)

    @traitlets.default("height")
    def _default_height(self):
        return "400px"

    @traitlets.validate("height")
    def _validate_height(self, proposal):
        height = proposal["value"]
        if isinstance(height, int):
            return f"{height}px"

        return height

    @traitlets.observe("_rendered")
    def _on_rendered(self, change):
        self.send({"calls": self._message_queue, "msg": "init"})
        self._message_queue = []

    def use_message_queue(self, value: bool = True) -> None:
        self._use_message_queue = value

    def add_call(self, method_name: str, *args) -> None:
        call = [method_name, args]
        if not self._rendered:
            if not self._use_message_queue:
                self.calls = self.calls + [call]
                return

            self._message_queue.append(call)
            return

        self.send({"calls": [call], "msg": "custom call"})

maplibre.plugins

MapboxDrawControls

Bases: BaseModel

MapboxDraw controls

Source code in maplibre/plugins.py

class MapboxDrawControls(BaseModel):
    """MapboxDraw controls"""

    point: bool = False
    line_string: bool = False
    polygon: bool = False
    trash: bool = False
    combine_features: bool = False
    uncombine_features: bool = False

MapboxDrawOptions

Bases: BaseModel

MapboxDraw Options

Source code in maplibre/plugins.py

class MapboxDrawOptions(BaseModel):
    """MapboxDraw Options"""

    display_controls_default: bool = Field(
        True, serialization_alias="displayControlsDefault"
    )
    controls: MapboxDrawControls = None
    box_select: bool = Field(True, serialization_alias="boxSelect")