KML ORM Documentation

A Django-style ORM for KML (Keyhole Markup Language) files that provides intuitive, chainable query interfaces for geospatial data without requiring Django as a dependency.

User Guide:

• Quick Start Guide
  • Installation
  • Basic Usage
  • Complete Example
  • Error Handling
  • Next Steps
• Tutorial
  • Advanced Querying
  • Working with Hierarchies
  • Spatial Operations
  • Working with Different Geometry Types
  • Data Validation
  • Performance Optimization
  • Error Handling Patterns
  • Integration Patterns
  • Custom Extensions
  • Next Steps
• Query Method Behavior Reference
  • Summary
  • Core Principle
  • Truth Table for Query Methods
  • Behavior by Element Type
  • Real-World Examples
  • Implementation Details
  • Best Practices
  • Common Pitfalls
  • Summary Recommendation
• Examples
  • Store Locator Analysis
  • Route Planning
  • Geographic Data Validation
  • Data Access with to_dict() Methods
  • Spatial Analysis
  • Data Quality Assessment
  • Batch Processing

API Reference:

• API Reference
  • Core Components
  • Quick Navigation
  • Overview
  • Getting Started
  • Example Usage
• KMLFile
  • Loading KML Data
  • Working with Managers
  • Document Properties
  • Utility Methods
  • Complete Usage Examples
• Models
  • Base Element
  • Placemark
  • Folder
  • Path (LineString)
  • Polygon
  • Point
  • MultiGeometry
  • Distance and Bearing Methods
  • Example Usage
• QuerySets and Managers
  • QuerySet
  • Manager
  • Core Query Methods
  • Geospatial Methods
  • Distance Calculation Details
  • Query Examples
  • Field Lookups
• Coordinates and Geometry
  • Coordinate Class
  • Creating Coordinates
  • Properties
  • Validation
  • Data Access
  • Usage Examples
  • Integration with Placemark
  • Coordinate Validation Rules
• Exceptions
  • Exception Hierarchy
  • Base Exception
  • Parsing Exceptions
  • Validation Exceptions
  • Query Exceptions
  • Usage Examples
  • Best Practices
  • Error Codes and Context

Development:

• Contributing

Features

• Django-style API: Familiar .objects.all(), .filter(), .get() methods

• Chainable queries: Build complex geospatial queries step by step

• Type hints: Full type annotation support for modern Python development

• Django knowledge transfers: Use the Django patterns that you know and love to parse and examine KML (now with less Django!)

• Geospatial operations: Built-in spatial queries like .near(), .within_bounds()

• Python data structures: Access KML data as native Python objects

Quick Example

from kmlorm import KMLFile

# Load KML file
kml = KMLFile.from_file('places.kml')

# Query placemarks (includes those in nested folders)
all_places = kml.placemarks.all()
capital_stores = kml.placemarks.all().filter(name__icontains='capital')
nearby = kml.placemarks.all().near(-76.6, 39.3, radius_km=25)

# Chain queries
nearby_open = (kml.placemarks.all()
    .filter(name__icontains='electric')
    .near(-76.6, 39.3, radius_km=50)
    .filter(visibility=True)
)

Hierarchical Querying

Work with nested folder structures using intuitive methods:

# Get only direct children (root-level placemarks)
root_placemarks = kml.placemarks.children()

# Get ALL placemarks including nested ones
all_placemarks = kml.placemarks.all()

# Same pattern works for folders
root_folders = kml.folders.children()
all_folders = kml.folders.all()

Installation

pip install kmlorm

Requirements

• Python 3.11+

• lxml

Indices and tables

• Index

• Module Index

• Search Page