tessl/pypi-folium
Make beautiful maps with Leaflet.js & Python
—
Pending
Quality
Pending
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
core-mapping.mddocs/
Core Mapping
Fundamental mapping functionality providing the essential Map class, basic markers, popups, tooltips, tile layers, and layer management controls. These components form the foundation of folium's mapping capabilities.
Capabilities
Map Creation
The primary Map class serves as the root container for all map elements, managing the canvas, coordinate system, and base tile layers.
class Map:
"""
Create a Map with Folium and Leaflet.js.
Parameters:
- location: tuple or list, initial map center coordinates [lat, lon]
- width: str or int, map width (default '100%')
- height: str or int, map height (default '100%')
- left: str, left margin (default '0%')
- top: str, top margin (default '0%')
- position: str, CSS positioning (default 'relative')
- tiles: str or TileLayer, base tile layer (default 'OpenStreetMap')
- attr: str, attribution text for custom tiles
- min_zoom: int, minimum zoom level (default 0)
- max_zoom: int, maximum zoom level (default 18)
- zoom_start: int, initial zoom level (default 10)
- min_lat: float, minimum latitude bounds (default -90)
- max_lat: float, maximum latitude bounds (default 90)
- min_lon: float, minimum longitude bounds (default -180)
- max_lon: float, maximum longitude bounds (default 180)
- max_bounds: bool, restrict map bounds (default False)
- crs: str, coordinate reference system (default 'EPSG3857')
- control_scale: bool, show scale control (default False)
- prefer_canvas: bool, use canvas renderer (default False)
- no_touch: bool, disable touch interactions (default False)
- disable_3d: bool, disable 3D CSS transforms (default False)
- png_enabled: bool, enable PNG export (default False)
- zoom_control: bool, show zoom control (default True)
Returns:
Map instance
"""
def __init__(
self,
location=None,
width='100%',
height='100%',
left='0%',
top='0%',
position='relative',
tiles='OpenStreetMap',
attr=None,
min_zoom=0,
max_zoom=18,
zoom_start=10,
min_lat=-90,
max_lat=90,
min_lon=-180,
max_lon=180,
max_bounds=False,
crs='EPSG3857',
control_scale=False,
prefer_canvas=False,
no_touch=False,
disable_3d=False,
png_enabled=False,
zoom_control=True,
**kwargs
): ...
def add_child(self, child): ...
def add_to(self, parent): ...
def save(self, outfile): ...
def show_in_browser(self): ...
def get_bounds(self): ...
def fit_bounds(self, bounds, padding_top_left=None, padding_bottom_right=None, padding=None, max_zoom=None): ...Markers
Point markers with customizable icons, popups, and interactive behavior.
class Marker:
"""
Create a marker on the map.
Parameters:
- location: tuple or list, marker coordinates [lat, lon]
- tooltip: str or Tooltip, hover text
- popup: str or Popup, click popup content
- icon: Icon, marker icon (default uses standard icon)
- draggable: bool, allow marker dragging (default False)
Returns:
Marker instance
"""
def __init__(
self,
location=None,
tooltip=None,
popup=None,
icon=None,
draggable=False,
**kwargs
): ...
def add_to(self, parent): ...Icons
Customizable marker icons with different styles and appearances.
class Icon:
"""
Create a standard marker icon.
Parameters:
- color: str, icon color ('red', 'blue', 'green', 'purple', 'orange', 'darkred', 'lightred', 'beige', 'darkblue', 'darkgreen', 'cadetblue', 'darkpurple', 'white', 'pink', 'lightblue', 'lightgreen', 'gray', 'black', 'lightgray')
- icon_color: str, icon symbol color (default 'white')
- icon: str, icon symbol name (FontAwesome or Glyphicon)
- angle: int, icon rotation angle (default 0)
- prefix: str, icon prefix ('fa' for FontAwesome, 'glyphicon' for Glyphicon)
Returns:
Icon instance
"""
def __init__(
self,
color='blue',
icon_color='white',
icon='info-sign',
angle=0,
prefix='glyphicon'
): ...
class CustomIcon:
"""
Create a custom image-based icon.
Parameters:
- icon_image: str, URL or path to icon image
- icon_size: tuple, icon dimensions [width, height]
- icon_anchor: tuple, anchor point [x, y]
- popup_anchor: tuple, popup anchor relative to icon [x, y]
- shadow_image: str, shadow image URL (optional)
- shadow_size: tuple, shadow dimensions (optional)
- shadow_anchor: tuple, shadow anchor point (optional)
Returns:
CustomIcon instance
"""
def __init__(
self,
icon_image,
icon_size=None,
icon_anchor=None,
popup_anchor=None,
shadow_image=None,
shadow_size=None,
shadow_anchor=None
): ...
class DivIcon:
"""
Create an HTML/CSS-based icon using div elements.
Parameters:
- html: str, HTML content for the icon
- icon_size: tuple, icon dimensions [width, height]
- icon_anchor: tuple, anchor point [x, y]
- popup_anchor: tuple, popup anchor relative to icon [x, y]
- class_name: str, CSS class name
Returns:
DivIcon instance
"""
def __init__(
self,
html=None,
icon_size=None,
icon_anchor=None,
popup_anchor=None,
class_name='divicon'
): ...Popups and Tooltips
Interactive information display components for map elements.
class Popup:
"""
Create a popup window for map elements.
Parameters:
- html: str, HTML content for popup
- parse_html: bool, parse HTML tags (default False)
- max_width: int, maximum popup width in pixels (default 300)
- show: bool, show popup immediately (default False)
- sticky: bool, keep popup open on mouse out (default False)
- lazy: bool, lazy loading (default False)
Returns:
Popup instance
"""
def __init__(
self,
html=None,
parse_html=False,
max_width=300,
show=False,
sticky=False,
lazy=False,
**kwargs
): ...
class Tooltip:
"""
Create a tooltip for map elements.
Parameters:
- text: str, tooltip text content
- style: str, CSS styles for tooltip
- permanent: bool, always show tooltip (default False)
- direction: str, tooltip direction ('right', 'left', 'top', 'bottom', 'center', 'auto')
- sticky: bool, follow mouse cursor (default True)
- opacity: float, tooltip opacity (default 0.9)
Returns:
Tooltip instance
"""
def __init__(
self,
text='',
style=None,
permanent=False,
direction='right',
sticky=True,
opacity=0.9,
**kwargs
): ...Tile Layers
Raster tile layers providing base maps and overlays from various providers.
class TileLayer:
"""
Create a tile layer for the map.
Parameters:
- tiles: str, tile provider name or URL template
- min_zoom: int, minimum zoom level (default 0)
- max_zoom: int, maximum zoom level (default 18)
- max_native_zoom: int, maximum native zoom of tiles
- attr: str, attribution text
- name: str, layer name for layer control
- overlay: bool, treat as overlay layer (default False)
- control: bool, show in layer control (default True)
- show: bool, show layer initially (default True)
- no_wrap: bool, disable tile wrapping (default False)
- opacity: float, layer opacity (default 1.0)
- z_index: int, layer z-index
- unload_invisible_tiles: bool, unload off-screen tiles (default False)
- update_when_idle: bool, update when map is idle (default False)
- detect_retina: bool, use retina/high-DPI tiles (default False)
Returns:
TileLayer instance
"""
def __init__(
self,
tiles='OpenStreetMap',
min_zoom=0,
max_zoom=18,
max_native_zoom=None,
attr=None,
name=None,
overlay=False,
control=True,
show=True,
no_wrap=False,
opacity=1.0,
z_index=None,
unload_invisible_tiles=False,
update_when_idle=False,
detect_retina=False,
**kwargs
): ...
class WmsTileLayer:
"""
Create a Web Map Service (WMS) tile layer.
Parameters:
- url: str, WMS service URL
- layers: str, WMS layer names (comma-separated)
- styles: str, WMS style names (comma-separated)
- format: str, image format (default 'image/jpeg')
- transparent: bool, transparent background (default False)
- version: str, WMS version (default '1.1.1')
- crs: str, coordinate reference system
- uppercase: bool, uppercase parameter names (default False)
- name: str, layer name for layer control
- overlay: bool, treat as overlay layer (default False)
- control: bool, show in layer control (default True)
- show: bool, show layer initially (default True)
Returns:
WmsTileLayer instance
"""
def __init__(
self,
url,
layers='',
styles='',
format='image/jpeg',
transparent=False,
version='1.1.1',
crs=None,
uppercase=False,
name=None,
overlay=False,
control=True,
show=True,
**kwargs
): ...Layer Management
Components for organizing and controlling map layers.
class LayerControl:
"""
Create a layer control for toggling layer visibility.
Parameters:
- position: str, control position ('topright', 'topleft', 'bottomright', 'bottomleft')
- collapsed: bool, collapse control initially (default True)
- autoZIndex: bool, auto-assign z-index (default True)
- hideSingleBase: bool, hide control with single base layer (default False)
- sortLayers: bool, sort layers alphabetically (default False)
- sortFunction: callable, custom sort function
Returns:
LayerControl instance
"""
def __init__(
self,
position='topright',
collapsed=True,
autoZIndex=True,
hideSingleBase=False,
sortLayers=False,
sortFunction=None
): ...
class FeatureGroup:
"""
Container for grouping related map elements.
Parameters:
- name: str, group name for layer control
- overlay: bool, treat as overlay in layer control (default True)
- control: bool, show in layer control (default True)
- show: bool, show group initially (default True)
Returns:
FeatureGroup instance
"""
def __init__(
self,
name=None,
overlay=True,
control=True,
show=True,
**kwargs
): ...
def add_child(self, child): ...
def add_to(self, parent): ...Map Bounds Control
Utilities for controlling map viewport and bounds.
class FitBounds:
"""
Fit map view to specified bounds.
Parameters:
- bounds: list, bounding box [[south, west], [north, east]]
- padding_top_left: tuple, top-left padding [x, y]
- padding_bottom_right: tuple, bottom-right padding [x, y]
- padding: tuple, uniform padding [x, y]
- max_zoom: int, maximum zoom level for fitting
Returns:
FitBounds instance
"""
def __init__(
self,
bounds,
padding_top_left=None,
padding_bottom_right=None,
padding=None,
max_zoom=None
): ...
class FitOverlays:
"""
Fit map view to contain all overlay layers.
Parameters:
- padding_top_left: tuple, top-left padding [x, y]
- padding_bottom_right: tuple, bottom-right padding [x, y]
- padding: tuple, uniform padding [x, y]
- max_zoom: int, maximum zoom level for fitting
Returns:
FitOverlays instance
"""
def __init__(
self,
padding_top_left=None,
padding_bottom_right=None,
padding=None,
max_zoom=None
): ...Usage Examples
Basic Map with Markers
import folium
# Create map centered on San Francisco
m = folium.Map(
location=[37.7749, -122.4194],
zoom_start=12,
tiles='CartoDB Positron'
)
# Add markers with different icons
folium.Marker(
[37.7849, -122.4094],
popup='Golden Gate Park',
tooltip='Hover for info',
icon=folium.Icon(color='green', icon='tree-deciduous', prefix='fa')
).add_to(m)
folium.Marker(
[37.7649, -122.4294],
popup='Mission District',
icon=folium.Icon(color='red', icon='heart')
).add_to(m)
# Custom icon marker
folium.Marker(
[37.7949, -122.3994],
popup='Custom Icon',
icon=folium.CustomIcon(
icon_image='https://example.com/icon.png',
icon_size=(30, 30)
)
).add_to(m)
m.save('sf_map.html')Layer Control and Feature Groups
import folium
m = folium.Map(location=[40.7128, -74.0060], zoom_start=11)
# Create feature groups
parks = folium.FeatureGroup(name='Parks')
restaurants = folium.FeatureGroup(name='Restaurants')
# Add markers to groups
folium.Marker(
[40.7829, -73.9654],
popup='Central Park',
icon=folium.Icon(color='green')
).add_to(parks)
folium.Marker(
[40.7505, -73.9934],
popup='Famous Restaurant',
icon=folium.Icon(color='red')
).add_to(restaurants)
# Add groups to map
parks.add_to(m)
restaurants.add_to(m)
# Add layer control
folium.LayerControl().add_to(m)
m.save('nyc_layers.html')Install with Tessl CLI
npx tessl i tessl/pypi-folium