Using Folium for Map Creation in Python

Folium is a Python library that creates interactive Leaflet maps directly from Python data structures. It bridges the gap between data analysis in Pandas and geographic visualization, allowing you to create professional-quality maps with minimal code. Folium supports tile layers from OpenStreetMap, Mapbox, CartoDB, and other providers, along with markers, choropleths, heatmaps, and popups for data exploration.

Basic Map Creation

Creating a map with Folium starts with the folium.Map constructor, which takes a location (latitude, longitude), zoom level, and tile style as parameters. The default tile set is OpenStreetMap, but you can switch to Stamen Terrain, CartoDB Positron, or other styles to match your aesthetic needs. Maps are HTML widgets that can be displayed in Jupyter notebooks, saved as standalone HTML files, or embedded in web pages.

import folium

# Create a base map centered on New York City
m = folium.Map(location=[40.7128, -74.0060], zoom_start=12,
               tiles="CartoDB positron")
m.save("nyc_map.html")

# Create a map with different tile styles
m_terrain = folium.Map(location=[40.7128, -74.0060],
                       tiles="Stamen Terrain", zoom_start=11)
m_terrain.save("nyc_terrain.html")

Markers and Popups

Markers pinpoint locations on the map. Folium’s Marker class takes a location (lat, lng) and optional popup text or tooltip. For large datasets, using CircleMarker instead of the default icon marker improves performance—they render as SVG circles that scale well with hundreds of points. You can customize marker colors, icons (using Font Awesome or Bootstrap icons), and popup content to include formatted text, images, or even charts rendered as HTML.

import folium, pandas as pd

m = folium.Map(location=[40.7128, -74.0060], zoom_start=11)

# Sample data: coffee shops
shops = [
    {"name": "Blue Bottle", "lat": 40.7266, "lng": -73.9968, "rating": 4.5},
    {"name": "Stumptown", "lat": 40.7295, "lng": -73.9965, "rating": 4.3},
    {"name": "Intelligentsia", "lat": 40.7282, "lng": -73.9943, "rating": 4.4},
]
for shop in shops:
    color = "green" if shop["rating"] >= 4.4 else "orange"
    folium.CircleMarker(
        location=[shop["lat"], shop["lng"]],
        radius=12, color=color, fill=True, fill_opacity=0.7,
        popup=f"{shop['name']}
Rating: {shop['rating']}/5",
        tooltip=shop["name"]
    ).add_to(m)
m.save("coffee_shops.html")

Choropleth Maps for Geographic Data

Choropleth maps color geographic regions (countries, states, districts) based on a data value. Folium’s choropleth layer requires two inputs: a GeoJSON file defining region boundaries, and a data column mapping each region ID to a value. This is powerful for visualizing election results, population density, infection rates, or economic indicators by region. The key is matching the GeoJSON feature IDs to your data keys—usually ISO country codes or FIPS state codes.

import folium, json, pandas as pd

m = folium.Map(location=[39.8, -98.5], zoom_start=4)

# Unemployment data by state (simulated)
data = pd.DataFrame({
    "state": ["AL", "AK", "AZ", ...],  # state FIPS or abbreviation
    "unemployment": [4.2, 5.1, 3.8, ...]
})

folium.Choropleth(
    geo_data="us-states.json",  # GeoJSON file
    name="choropleth",
    data=data,
    columns=["state", "unemployment"],
    key_on="feature.id",
    fill_color="YlOrRd",
    fill_opacity=0.7,
    line_opacity=0.2,
    legend_name="Unemployment Rate (%)"
).add_to(m)
m.save("unemployment.html")

Heatmaps and Clustering

For visualizing point density (e.g., crime locations, taxi pickups, earthquake epicenters), Folium offers HeatMap (from folium.plugins) which renders a smooth density surface where color intensity represents point concentration. The MarkerCluster plugin groups nearby markers into clusters that expand as you zoom in, making it practical to display thousands of points without overwhelming the browser. Both plugins integrate seamlessly with Folium’s API and work well in Jupyter notebooks and web dashboards. Folium maps can also be combined with other visualization libraries—for example, using Altair to generate a chart and embedding it in a map popup, giving you the full power of the Python data visualization ecosystem on an interactive geographic canvas.

GeoPandas Integration

GeoPandas extends Pandas with geospatial data types (GeoSeries, GeoDataFrame) and operations (buffer, intersection, distance, convex hull). Folium maps can directly visualize GeoDataFrames using the explore() method, which accepts a GeoDataFrame and automatically creates a choropleth or point map. This integration enables complex spatial analysis pipelines: load shapefiles or GeoJSON with GeoPandas, perform spatial operations (filter points within a polygon, compute nearest neighbors), and visualize results with Folium in a few lines of code. The combination of GeoPandas for analysis and Folium for visualization covers 90% of geospatial data science workflows without requiring GIS desktop software.

import geopandas as gpd

# Load world countries shapefile
world = gpd.read_file(gpd.datasets.get_path("naturalearth_lowres"))
# Filter to a continent
asia = world[world["continent"] == "Asia"]
# Create Folium map
m = asia.explore(column="pop_est", cmap="YlOrRd", legend=True)
m.save("asia_population.html")

Real-Time Data with Folium

Folium maps can display real-time data by updating markers dynamically. While Folium itself generates static HTML, combining it with JavaScript setInterval() calls to refresh GeoJSON data sources creates live-updating maps. For production dashboards, consider using Streamlit with st_folium which supports bidirectional communication between Python and the map. The folium.plugins package adds TimestampedGeoJson for animating data over time, Draw for user input, and Fullscreen for presentation mode. Folium’s FeatureGroup organizes related markers into toggleable layers. The integration with ipyleaflet provides higher performance for interactive exploration with WebGL support for millions of points.

Creating a CLI Utility for Bulk File Rename Operations Using Python

Renaming hundreds of files manually is tedious and error-prone. A Python command-line utility can automate bulk renaming with patterns, regex substitution, numbering sequences, and dry-run previews. This article walks through building a practical CLI tool using argparse and pathlib, covering common renaming scenarios like normalizing filenames, adding prefixes/suffixes, replacing text, and numbering files sequentially.

Core Design with argparse and pathlib

Python’s argparse module handles command-line argument parsing, and pathlib provides an object-oriented interface to filesystem paths. The tool should support several rename modes: replace (find and replace text in filenames), prefix/suffix (add leading or trailing text), number (add sequential numbering), and regex (pattern-based replacement using regular expressions). A dry-run flag (-n or –dry-run) is essential—it shows what would happen without actually renaming anything, letting users verify the operation before executing.

import argparse, re
from pathlib import Path

def bulk_rename(directory, find=None, replace=None,
                prefix="", suffix="", dry_run=False):
    path = Path(directory)
    for file in path.iterdir():
        if not file.is_file():
            continue
        old_name = file.name
        new_name = old_name
        if find and replace is not None:
            new_name = new_name.replace(find, replace)
        if prefix:
            new_name = prefix + new_name
        if suffix:
            stem = Path(new_name).stem
            ext = Path(new_name).suffix
            new_name = f"{stem}{suffix}{ext}"
        if new_name != old_name:
            print(f"  {old_name} → {new_name}")
            if not dry_run:
                file.rename(file.with_name(new_name))

if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Bulk rename files")
    parser.add_argument("directory", help="Target directory")
    parser.add_argument("--find", help="Text to find")
    parser.add_argument("--replace", help="Replacement text")
    parser.add_argument("--prefix", default="", help="Add prefix")
    parser.add_argument("--suffix", default="", help="Add suffix")
    parser.add_argument("-n", "--dry-run", action="store_true", help="Preview only")
    args = parser.parse_args()
    bulk_rename(args.directory, args.find, args.replace,
                args.prefix, args.suffix, args.dry_run)

Sequential Numbering

Adding sequential numbers to files is useful for photo collections, document scanning, or creating ordered playlists. The –number flag adds a zero-padded sequence number (e.g., 001, 002) to each file. You can specify the starting number, padding width, and position (prefix vs suffix). Sorting can be by name, modification date, or creation date to control the numbering order. The script detects and prevents collisions by checking whether the target filename already exists before renaming.

def add_numbering(files, start=1, padding=3, as_prefix=True, by="name"):
    if by == "date":
        files.sort(key=lambda f: f.stat().st_mtime)
    else:
        files.sort()
    for i, file in enumerate(files, start=start):
        num = str(i).zfill(padding)
        old = file.name
        stem = file.stem
        ext = file.suffix
        new_name = f"{num}_{stem}{ext}" if as_prefix else f"{stem}_{num}{ext}"
        yield old, new_name

# Usage: python rename.py ./photos --number --start 1 --padding 4 --by date

Regex-Based Renaming

For complex transformations, regex is indispensable. The –regex flag enables pattern-based matching with capture groups that can be referenced in the replacement string (e.g.,
, ). This is useful for extracting and reformatting date patterns, normalizing spacing, or restructuring naming conventions. For example, renaming “IMG_20260709_123456.jpg” to “2026-07-09_12-34-56.jpg” uses a single regex substitution with capture groups for year, month, day, hour, minute, and second.

def regex_rename(directory, pattern, replacement, dry_run=False):
    path = Path(directory)
    for file in path.iterdir():
        if not file.is_file():
            continue
        new_name = re.sub(pattern, replacement, file.name)
        if new_name != file.name:
            print(f"  {file.name} → {new_name}")
            if not dry_run:
                file.rename(file.with_name(new_name))

# Example: python rename.py ./photos --regex "(IMG_)(\d{4})(\d{2})(\d{2})" --replace "--_"

Safety Features

Beyond dry-run mode, the utility should include collision detection (preventing overwrites), undo functionality (saving rename operations to a log file that can reverse them), and confirmation prompts before executing on more than a threshold number of files. Using pathlib’s rename() method is atomic on most filesystems, meaning a partially completed batch leaves some files renamed and others not—logging each operation to a JSON file allows reversing with a simple –undo flag that reads the log and reverses the mapping.

Cross-Platform Considerations

Python’s pathlib.Path handles path separators correctly on Windows (backslash), macOS, and Linux. However, renaming files across filesystems (e.g., renaming on an external drive) may not be atomic. The script should handle permission errors gracefully by catching PermissionError and continuing with the remaining files. On Unix systems, renaming a file to a name that differs only in case may behave unexpectedly on case-insensitive filesystems (macOS default, Windows). Adding a warning when –find and –replace would change only case prevents silent failures. For very large directories (100K+ files), using os.scandir() instead of pathlib.iterdir() improves initial listing speed, and batching rename operations in transactions of 1000 files prevents partial failures from leaving the directory in an inconsistent state.

GUI Frontend with Tkinter or PyQt

For users uncomfortable with the command line, a simple GUI frontend provides the same functionality with file dialogs and preview lists. Python’s tkinter (built-in) creates native-looking dialogs for selecting directories, defining rename rules, and previewing changes before applying them. A GUI version shows the original filenames next to the new names with color coding (green = rename, red = conflict, gray = unchanged). Drag-and-drop support lets users drop files or folders onto the window. The PyQt6 version includes a progress bar for large directories, a parallel rename option, and an undo button that reverses the last rename operation.

Python Packaging and Distribution with Poetry

Packaging a Python project properly ensures that other developers can install, use, and contribute to your code without dependency conflicts or missing files. Poetry is a modern dependency management and packaging tool that simplifies the entire workflow — from project creation to publishing on PyPI. Unlike pip and setuptools, Poetry uses a declarative pyproject.toml file, resolves dependencies with a SAT solver to avoid version conflicts, and generates deterministic installs via a lock file. This article walks through creating, building, and publishing a Python package with Poetry.

Creating a New Project

Starting a new project with Poetry is a single command. It creates the directory structure, initializes a Git repository, and generates a pyproject.toml file with sensible defaults. The generated structure includes a source directory named after your project, a README.md, and a tests directory.

# Create a new Poetry project
poetry new my-project
cd my-project

# Project structure created:
# my-project/
#   pyproject.toml
#   README.md
#   my_project/
#       __init__.py
#   tests/
#       __init__.py
#       test_my_project.py

If you are adding Poetry to an existing project instead of starting fresh, run poetry init and answer the prompts. Poetry will generate a pyproject.toml based on your existing requirements.txt or setup.py if you point it at the right files.

Managing Dependencies

Poetry uses a pyproject.toml file (defined in PEP 518 and PEP 621) to declare project metadata and dependencies. Dependencies are organized into groups: the main [tool.poetry.dependencies] section for runtime dependencies, and [tool.poetry.group.dev.dependencies] for development-only packages like test runners, linters, and type checkers. When you run poetry add, Poetry automatically resolves all dependency versions to ensure compatibility and records the exact versions in a poetry.lock file. This lock file should be committed to version control so that everyone working on the project gets identical dependency trees.

[tool.poetry]
name = "my-project"
version = "0.1.0"
description = "A sample Python project"
authors = ["Your Name <you@example.com>"]
readme = "README.md"
license = "MIT"

[tool.poetry.dependencies]
python = "^3.10"
requests = "^2.28"
click = "^8.1"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^22.0"
mypy = "^1.0"
ruff = "^0.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

The ^ operator in version constraints means “compatible with.” For example, ^2.28 allows any version from 2.28 up to but not including 3.0.0. This gives you bug fixes and minor features without risking breaking changes from a major version bump. The python = "^3.10" constraint means your package supports Python 3.10, 3.11, 3.12, etc., but not Python 4.0.

Adding and Removing Dependencies

The Poetry CLI provides intuitive commands for managing dependencies. Each command updates both pyproject.toml and poetry.lock automatically, ensuring your environment stays synchronized with the declared dependencies.

# Add runtime dependencies
poetry add fastapi uvicorn

# Add development-only dependencies
poetry add --group dev mypy pytest-cov

# Remove a dependency
poetry remove requests

# Update all dependencies to latest allowed versions
poetry update

# Show dependency tree
poetry show --tree

# Export to requirements.txt format
poetry export -f requirements.txt --output requirements.txt

The poetry show --tree command is invaluable for debugging dependency conflicts — it displays a tree of every package and its sub-dependencies, making it easy to spot situations where two packages require incompatible versions of the same library.

Building and Publishing

Once your project is ready, building distributable archives is a single command. Poetry produces both a source distribution (.tar.gz) and a wheel (.whl) in the dist/ directory. Wheels are the preferred distribution format because they install faster — they are pre-built and do not require running setup.py. Publishing to PyPI is equally simple. You will need a PyPI API token for authentication instead of a username and password.

# Build source distribution and wheel
poetry build

# Publish to PyPI
poetry publish --username __token__ --password pypi-xxxxxxxxxxxxxxxxxxxx

# Publish to Test PyPI first (recommended)
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi --username __token__ --password pypi-xxxx

Version Management

Poetry includes a built-in version command that follows semantic versioning conventions. It updates both the pyproject.toml version field and creates a Git tag.

# Check current version
poetry version

# Bump version (patch, minor, major, prepatch, preminor, premajor)
poetry version patch   # 0.1.0 -> 0.1.1
poetry version minor   # 0.1.0 -> 0.2.0
poetry version major   # 0.1.0 -> 1.0.0

# Pre-release versions
poetry version prepatch  # 0.1.0 -> 0.1.1a0

By integrating Poetry into your workflow, you get reproducible builds, clean dependency resolution, and a straightforward publishing pipeline — all essential for maintaining a professional Python package.

Publishing to PyPI and CI/CD Integration

Once your package is configured with Poetry, publishing to PyPI is a single command: poetry publish. For automated publishing, configure PyPI tokens as CI/CD secrets. A GitHub Actions workflow can run tests, build with poetry build, publish to TestPyPI on PR merges, and publish to PyPI on version tags. Poetry’s version command (poetry version patch/minor/major) bumps versions according to semantic versioning. The pyproject.toml build-system requires poetry-core ensures pip can install directly from the repository. Poetry’s dependency resolver avoids version conflicts that plague setuptools/pip projects.