simplestmaps 1.7.2__py3-none-any.whl

simplestmaps-1.7.2.dist-info/METADATA

@@ -0,0 +1,67 @@
+Metadata-Version: 2.5
+Name: simplestmaps
+Version: 1.7.2
+Summary: Super simple on-liner maps in python.
+Project-URL: Homepage, http://github.com/fisadev/simplestmaps
+Project-URL: Documentation, https://simplestmaps.fisadev.com/
+Author-email: Juan Pedro Fisanotti <fisadev@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: folium>=0.15.0
+Requires-Dist: xyzservices
+Description-Content-Type: text/markdown
+
+# Simplest Maps
+
+Super simple on-liner maps in python.
+
+# Installation
+
+`pip3 install simplestmaps`
+
+# Usage
+
+This lib aims to be super simple to use. For instance, to draw a markers and an area, you could do something like this:
+
+```python
+from simplestmaps import draw_map, area, marker
+
+draw_map(
+    marker(-31.2526, -61.4917, popup="my hometown"),
+    area([(-31.2741, -61.5105), (-31.2872, -61.5137), (-31.2895, -61.5003), (-31.2764, -61.4973)], color="green", popup="our airfield"),
+)
+```
+
+![example map](./docs/readme_example1.png)
+
+It can even do more advanced stuff, like plotting the contents of a geojson file (points, areas, lines):
+
+```python
+from simplestmaps import draw_map, geojson
+
+draw_map(
+    geojson("./docs/readme_example.geojson"),
+)
+```
+
+![example map](./docs/readme_example2.png)
+
+SimplestMaps can plot markers, dots, labels (text), custom html, lines, areas and geojsons, and all of that can be combined in every map.
+
+And every element plotted into the map is also customizable (colors, fonts, sizes, popups, etc).
+
+# More demos and docs
+
+Here are a good set of examples that showcase (and document) all of the supported features:
+
+## [Take a look at everything that's possible with so little code!](https://simplestmaps.fisadev.com/)
+
+# Development
+
+The project uses [uv](https://docs.astral.sh/uv/). Run `uv sync` to create the virtualenv with all the dev dependencies, `make build_docs` to rebuild the docs, and `make release` to build and publish a new version to PyPI.

simplestmaps-1.7.2.dist-info/RECORD

@@ -0,0 +1,5 @@
+simplestmaps.py,sha256=VPUipdNMVS0aUtip-0onDi_MPSQOxSry175fuhPk7UU,16568
+simplestmaps-1.7.2.dist-info/METADATA,sha256=AB2cxGdoyAOYuwGHK8BiGJvwNVY1TCsvlM_zNpa9Gjo,2174
+simplestmaps-1.7.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+simplestmaps-1.7.2.dist-info/licenses/LICENSE,sha256=zkQJHtFEGPwAMePT5TgZg8wNz6Pyb7o7kV-8wqtwlQA,1077
+simplestmaps-1.7.2.dist-info/RECORD,,

simplestmaps-1.7.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

simplestmaps-1.7.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Juan Pedro Fisanotti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

simplestmaps.py

@@ -0,0 +1,439 @@
+from collections import namedtuple
+from functools import partial, wraps
+from pathlib import Path
+from types import GeneratorType
+import json
+
+import folium
+import xyzservices
+
+
+Point = namedtuple("Point", "lat lon")
+
+# type -> converter function that receives instance of type and returns either a single (lat,lon)
+# tuple, or a sequence of (lat,lon) tuples
+converters = {}
+
+
+def all_numbers(sequence):
+    """
+    Is a sequence composed of just numbers?
+    """
+    return all(
+        isinstance(x, (int, float)) and not isinstance(x, bool)
+        for x in sequence
+    )
+
+
+def to_points(source, inverted_tuples=False):
+    """
+    Convert any possible thing to lat lon points and/or sequences of points.
+    Optionally reverse lat,lon values (used when converting points from lists of coordinates in
+    geojsons).
+    """
+    while source.__class__ in converters:
+        # a custom type for which we have a converter registered, use it before trying to extract
+        # points from it
+        source = converters[source.__class__](source)
+
+    if isinstance(source, Point):
+        # don't re-convert things that are already points
+        return source
+    elif isinstance(source, GeneratorType):
+        # traverse the generator and build a tuple with its components, that we can inspect and
+        # parse (so we can do things like decide how to parse it based on its length and the types
+        # of its items)
+        return to_points(tuple(source), inverted_tuples=inverted_tuples)
+    elif hasattr(source, "lat") and hasattr(source, "lon"):
+        # a few known classes that have lat long attributes
+        lat, lon = source.lat, source.lon
+    elif hasattr(source, "latitude") and hasattr(source, "longitude"):
+        # a few known classes that have latitude longitude attributes, like some common geo
+        # libs
+        lat, lon = source.latitude, source.longitude
+    elif hasattr(source, "latitude_deg") and hasattr(source, "longitude_deg"):
+        # a few known classes that have latitude_deg longitude_deg attributes, like the
+        # locations from the orbit-predictor lib
+        lat, lon = source.latitude_deg, source.longitude_deg
+    elif source.__class__.__name__ == "Position" and hasattr(source, "position_llh"):
+        # a known class from the orbit-predictor lib, which has ECEF coordinates but can easily
+        # produce lat, lon, height coords
+        lat, lon, _ = source.position_llh
+    elif isinstance(source, (tuple, list)):
+        if len(source) == 1:
+            # a sequence with a single object inside, so extract a point from it as if we just got
+            # that object alone
+            return to_points(source[0], inverted_tuples=inverted_tuples)
+        elif len(source) in (2, 3) and all_numbers(source):
+            # a sequence of 2 or 3 numbers, these must be coordinates, finally!
+            if inverted_tuples:
+                lon, lat = source[:2]
+            else:
+                lat, lon = source[:2]
+        else:
+            # a sequence that doesn't look like coordinates but maybe a collection of points, try
+            # to extract all of them into a list
+            return [to_points(item, inverted_tuples=inverted_tuples) for item in source]
+    else:
+        raise ValueError(
+            f"Can't guess the latitude and longitude from this object: {repr(source)}"
+        )
+
+    return Point(lat, lon)
+
+
+def auto_convert(custom_type, converter_function):
+    """
+    Register a custom type to be automatically converted to single coordinates or sequences of
+    coordinates, to be able to use them in the helper functions for map elements.
+    """
+    converters[custom_type] = converter_function
+
+
+# types of things we can display on a map, with their attributes
+Marker = namedtuple("Marker", "point popup")
+Dot = namedtuple("Dot", "point color radius opacity border_color border_width popup")
+Label = namedtuple("Label", "point text color size font opacity popup")
+Html = namedtuple("Html", "point code popup")
+Line = namedtuple("Line", "points_sequence color width opacity popup")
+Area = namedtuple("Area", "points_sequence color opacity border_color border_width popup")
+Geojson = namedtuple("Geojson", "path points_as lines_as areas_as")
+
+
+def extract_single_points(points_source):
+    """
+    Extract and iterate over single points that might be part of point sequences, or even trees of
+    points.
+
+    This function assumes that points_source can contain only two types of things: Point instances,
+    or sequences (lists/tuples/generators) containing any of both.
+
+    Something like [[point_a], [point_b, point_c, point_d], [[[point_e]], point_f]]
+    Will yield all of the Point instances, one by one, in order.
+    """
+    pending = [points_source]
+    while pending:
+        current = pending.pop(0)
+
+        if isinstance(current, Point):
+            yield current
+        elif isinstance(current, (list, tuple, GeneratorType)):
+            pending.extend(current)
+
+
+def extract_points_sequences(points_source):
+    """
+    Extract and iterate over point sequences that might be themselves part of higher order
+    sequences, or even trees of sequences.
+
+    This function assumes that points_source can contain only two types of things: Point instances,
+    or sequences (lists/tuples/generators) containing any of both.
+
+    The only condition is that any sequence (list/tuple/generator) contains either all Point
+    instances, or all sequences. No mixing of the two element types inside the same sequence.
+
+    Something like [[point_a], [point_b, point_c, point_d], [[[point_e]]]]
+    Will yield three sequences:
+    [point_a]
+    [point_b, point_c, point_d]
+    [point_e]
+
+    While something like [point_a, [point_b, point_c]]
+    Will yield an error, as there's a sequence (the top level one) mixing types inside it.
+    """
+    pending = [points_source]
+    while pending:
+        current = pending.pop(0)
+
+        if isinstance(current, Point):
+            # we received a single point, not even in a sequence, just yield it as a sequence of
+            # one element
+            yield [current]
+        elif isinstance(current, (list, tuple, GeneratorType)):
+            # we have a sequence, but is it a sequence of points? or a sequence of other sequences?
+            if all(isinstance(item, Point) for item in current):
+                # current is a sequence of coords!
+                yield current
+            elif any(isinstance(item, Point) for item in current):
+                raise ValueError(
+                    f"There's a sequence mixing points and other kinds of objects: {repr(current)}"
+                )
+            else:
+                # a sequence of sequences, or a sequence of broken things. Add each item to the
+                # pending queue and deal with them when popped
+                pending.extend(current)
+        else:
+            raise ValueError(
+                f"Can't guess a sequence of coordinates from this object: {repr(current)}"
+            )
+
+
+def marker(*points_sources, popup=None):
+    """
+    Helper to easily build a Marker instance.
+    """
+    if not points_sources:
+        return partial(marker, popup=popup)
+
+    return [
+        Marker(point, popup)
+        for point in extract_single_points(to_points(points_sources))
+    ]
+
+
+def dot(*points_sources, color="blue", radius=3, opacity=1, border_color=None, border_width=0,
+        popup=None):
+    """
+    Helper to easily build a Dot instance.
+    """
+    if not points_sources:
+        return partial(dot, color=color, radius=radius, opacity=opacity, border_color=border_color,
+                       border_width=border_width, popup=popup)
+
+    if border_color is None:
+        border_color = color
+    elif border_width == 0:
+        border_width = 2
+
+    return [
+        Dot(point, color, radius, opacity, border_color, border_width, popup)
+        for point in extract_single_points(to_points(points_sources))
+    ]
+
+
+def label(*points_sources, text, color="blue", size=12, font="arial", opacity=1, popup=None):
+    """
+    Helper to easily build a Label instance.
+    """
+    if not points_sources:
+        return partial(label, text=text, color=color, size=size, font=font, opacity=opacity,
+                       popup=popup)
+
+    return [
+        Label(point, text, color, size, font, opacity, popup)
+        for point in extract_single_points(to_points(points_sources))
+    ]
+
+
+def html(*points_sources, code, popup=None):
+    """
+    Helper to easily build a Html instance.
+    """
+    if not points_sources:
+        return partial(html, code=code, popup=popup)
+
+    return [
+        Html(point, code, popup)
+        for point in extract_single_points(to_points(points_sources))
+    ]
+
+
+def line(*points_sequences_sources, color="blue", width=2, opacity=1, popup=None):
+    """
+    Helper to easily build a Line instance.
+    """
+    if not points_sequences_sources:
+        return partial(line, color=color, width=width, opacity=opacity, popup=popup)
+
+    return [
+        Line(points_sequence, color, width, opacity, popup)
+        for points_sequence in extract_points_sequences(to_points(points_sequences_sources))
+    ]
+
+
+def area(*points_sequences_sources, color="blue", opacity=0.5, border_color=None, border_width=0,
+         popup=None):
+    """
+    Helper to easily build an Area instance.
+    """
+    if not points_sequences_sources:
+        return partial(area, color=color, opacity=opacity, border_color=border_color,
+                       border_width=border_width, popup=popup)
+
+    if border_color is None:
+        border_color = color
+    elif border_width == 0:
+        border_width = 2
+
+    return [
+        Area(points_sequence, color, opacity, border_color, border_width, popup)
+        for points_sequence in extract_points_sequences(to_points(points_sequences_sources))
+    ]
+
+
+def geojson(path_or_data, points_as=marker, lines_as=line, areas_as=area):
+    """
+    Helper to easily read the contents of a geojson, and extract all the things it contains.
+    """
+    if isinstance(path_or_data, (str, Path)):
+        # a path to a geojson file, read it and extract its contents
+        with open(path_or_data, "r") as geojson_f:
+            geojson_data = json.load(geojson_f)
+    else:
+        geojson_data = path_or_data
+
+    if isinstance(geojson_data, list):
+        # a list of geo items, extract them individually
+        for item_data in geojson_data:
+            yield from geojson(item_data, points_as, lines_as, areas_as)
+
+    elif isinstance(geojson_data, dict):
+        # a single geo object, try to identify its type
+        geojson_type = geojson_data.get("type")
+
+        if geojson_type is None:
+            raise ValueError(
+                "The provided geojson seems to contain invalid data (no 'type' key present):\n\n"
+                f"{repr(geojson_data)}"
+            )
+
+        elif geojson_type == "FeatureCollection":
+            # a collection of features, extract them individually
+            for feature in geojson_data["features"]:
+                yield from geojson(feature["geometry"], points_as, lines_as, areas_as)
+        elif geojson_type == "Point":
+            yield points_as(
+                extract_single_points(to_points(geojson_data["coordinates"],
+                                                inverted_tuples=True))
+            )
+        elif geojson_type == "LineString":
+            yield lines_as(
+                extract_points_sequences(to_points(geojson_data["coordinates"],
+                                                   inverted_tuples=True))
+            )
+        elif geojson_type in ("Polygon", "MultiPolygon"):
+            yield areas_as(
+                extract_points_sequences(to_points(geojson_data["coordinates"],
+                                                   inverted_tuples=True))
+            )
+
+
+def draw_map(*things, center=(0, 0), zoom=1.5, tiles="OpenStreetMap", tiles_key=None):
+    """
+    Draw a simple map with elements on it.
+
+    Some tile providers (like "CartoDB.Positron") require an API key, which can be specified with
+    tiles_key.
+
+    More info on tiles:
+    https://python-visualization.github.io/folium/latest/user_guide/raster_layers/tiles.html
+    """
+    center = to_points(center)
+
+    if tiles_key:
+        tiles = xyzservices.providers.query_name(tiles)
+        # each provider names its key field differently (apikey, key, accessToken, ...)
+        tiles = tiles(**{field: tiles_key for field, value in tiles.items()
+                       if isinstance(value, str) and value.startswith("<insert your")})
+
+    map_ = folium.Map(location=(center.lat, center.lon), zoom_start=zoom, attr=".", tiles=tiles)
+
+    # consume all the things to display, and use inverted order so the user can easily understand
+    # what's o top of what
+    things = list(reversed(things))
+
+    while things:
+        thing = things.pop()
+
+        if isinstance(thing, (list, tuple, GeneratorType)):
+            # a collection of things, probably created using the geojson() helper. Feed those
+            # things into the pending list
+            things.extend(thing)
+
+        if isinstance(thing, Marker):
+            folium.Marker(
+                location=[thing.point.lat, thing.point.lon],
+                popup=thing.popup,
+            ).add_to(map_)
+
+        elif isinstance(thing, Dot):
+            folium.CircleMarker(
+                location=[thing.point.lat, thing.point.lon],
+                radius=thing.radius,
+                color=thing.border_color,
+                weight=thing.border_width,
+                fillColor=thing.color,
+                fillOpacity=thing.opacity,
+                popup=thing.popup,
+            ).add_to(map_)
+
+        elif isinstance(thing, Label):
+            folium.Marker(
+                location=[thing.point.lat, thing.point.lon],
+                icon=folium.DivIcon(html=f"""
+                    <div style="font-family: {thing.font};
+                                font-size: {thing.size}px;
+                                color: {thing.color};
+                                opacity: {thing.opacity}">
+                        {thing.text}
+                    </div>
+                """),
+                popup=thing.popup,
+            ).add_to(map_)
+
+        elif isinstance(thing, Html):
+            folium.Marker(
+                location=[thing.point.lat, thing.point.lon],
+                icon=folium.DivIcon(html=thing.code),
+                popup=thing.popup,
+            ).add_to(map_)
+
+        elif isinstance(thing, Line):
+            folium.PolyLine(
+                locations=[(point.lat, point.lon)
+                           for point in thing.points_sequence],
+                color=thing.color,
+                weight=thing.width,
+                opacity=thing.opacity,
+                popup=thing.popup,
+            ).add_to(map_)
+
+        elif isinstance(thing, Area):
+            folium.Polygon(
+                locations=[(point.lat, point.lon)
+                           for point in thing.points_sequence],
+                color=thing.border_color,
+                weight=thing.border_width,
+                fill_color=thing.color,
+                fill_opacity=thing.opacity,
+                popup=thing.popup,
+            ).add_to(map_)
+
+    return map_
+
+
+try:
+    # add shapely support if present
+    from shapely.geometry import (
+        Point as ShpPoint,
+        LineString as ShpLineString,
+        LinearRing as ShpLinearRing,
+        Polygon as ShpPolygon,
+        MultiPoint as ShpMultiPoint,
+        MultiPolygon as ShpMultiPolygon,
+        MultiLineString as ShpMultiLineString
+    )
+
+    auto_convert(ShpPoint, lambda p: (p.y, p.x))
+    auto_convert(ShpLineString, lambda ls: [(c[1], c[0]) for c in ls.coords])
+    auto_convert(ShpLinearRing, lambda ls: [(c[1], c[0]) for c in ls.coords])
+    auto_convert(ShpPolygon, lambda p: [(c[1], c[0]) for c in p.exterior.coords])
+    auto_convert(ShpMultiPoint, lambda mp: list(mp.geoms))
+    auto_convert(ShpMultiLineString, lambda mp: list(mp.geoms))
+    auto_convert(ShpMultiPolygon, lambda mp: list(mp.geoms))
+except ImportError:
+    # shapely not present, do nothing
+    pass
+
+
+try:
+    # add shapely support if present
+    # (https://telluric.readthedocs.io/en/latest/index.html)
+    from telluric import GeoVector, FeatureCollection, GeoFeature
+
+    auto_convert(GeoVector, lambda gv: gv.get_shape(gv.crs))
+    auto_convert(GeoFeature, lambda gf: gf.geometry)
+    auto_convert(FeatureCollection, lambda fc: fc.geometries)
+except ImportError:
+    # telluric not present, do nothing
+    pass