KMLFile

The KMLFile class is the main entry point for loading and working with KML data.

It can be imported directly from the main package:

from kmlorm import KMLFile

Note

Understanding Hierarchical Access

Manager methods provide two ways to access elements:

kml.placemarks.children() - Direct children only (root-level elements)
kml.placemarks.all() - All elements including nested ones in folders

This applies to all element types: placemarks, folders, paths, polygons, points, and multigeometries.

KMLFile class for loading and parsing KML files.

This module provides the main entry point for loading KML data from files, strings, or URLs and exposing it through the Django-style ORM interface.

class kmlorm.parsers.kml_file.KMLFile[source]

Bases: object

Main class for loading and accessing KML file data.

Provides Django-style managers for accessing different types of KML elements with familiar query interfaces.

__init__()[source]

Initialize an empty KML file.

folders: FolderManager

placemarks: PlacemarkManager

paths: PathManager

polygons: PolygonManager

points: PointManager

multigeometries: MultiGeometryManager

classmethod from_file(file_path)[source]

Load KML data from a file.

Parameters:

file_path (str) – Path to KML or KMZ file

Return type:

KMLFile

Returns:

KMLFile instance with loaded data

Raises:

KMLParseError – If file cannot be read or parsed
FileNotFoundError – If file doesn’t exist

classmethod from_string(kml_string)[source]

Load KML data from a string.

Parameters:: kml_string (str) – KML content as string
Return type:: KMLFile
Returns:: KMLFile instance with loaded data
Raises:: KMLParseError – If KML cannot be parsed

classmethod from_url(url)[source]

Load KML data from a URL.

Parameters:: url (str) – URL to KML or KMZ file
Return type:: KMLFile
Returns:: KMLFile instance with loaded data
Raises:: KMLParseError – If URL cannot be accessed or parsed

property document_name: str | None: Get the document name from KML.

property document_description: str | None: Get the document description from KML.

all_elements()[source]

Get all elements from the KML file.

Return type:: List[Any]
Returns:: Combined list of all elements

element_counts()[source]

Get counts of each element type.

Return type:: Dict[str, int]
Returns:: Dictionary with element type counts

Loading KML Data

The KMLFile class provides several class methods for loading KML data from different sources:

classmethod KMLFile.from_file(file_path)[source]

Load KML data from a file.

Parameters:

file_path (str) – Path to KML or KMZ file

Return type:

KMLFile

Returns:

KMLFile instance with loaded data

Raises:

KMLParseError – If file cannot be read or parsed
FileNotFoundError – If file doesn’t exist

classmethod KMLFile.from_string(kml_string)[source]

Load KML data from a string.

Parameters:: kml_string (str) – KML content as string
Return type:: KMLFile
Returns:: KMLFile instance with loaded data
Raises:: KMLParseError – If KML cannot be parsed

classmethod KMLFile.from_url(url)[source]

Load KML data from a URL.

Parameters:: url (str) – URL to KML or KMZ file
Return type:: KMLFile
Returns:: KMLFile instance with loaded data
Raises:: KMLParseError – If URL cannot be accessed or parsed

Working with Managers

Once loaded, KMLFile provides Django-style managers for accessing different types of KML elements. Each manager provides the full QuerySet API for filtering, querying, and manipulating elements.

Available Managers:

folders - FolderManager for accessing folders
placemarks - PlacemarkManager for accessing placemarks
paths - PathManager for accessing paths (LineStrings)
polygons - PolygonManager for accessing polygons
points - PointManager for accessing points
multigeometries - MultiGeometryManager for accessing multi-geometries

Each manager supports the full range of Django-style query methods including .filter(), .get(), .near(), .within_bounds(), and more. See QuerySets and Managers for complete documentation of available query methods.

from kmlorm import KMLFile

kml = KMLFile.from_file('example.kml')

# Access different element types (direct children only)
root_placemarks = kml.placemarks.children()
root_folders = kml.folders.children()
root_paths = kml.paths.children()
root_polygons = kml.polygons.children()
root_points = kml.points.children()
root_multigeometries = kml.multigeometries.children()

# Access ALL elements including those nested in folders
all_placemarks = kml.placemarks.all()
all_folders = kml.folders.all()
all_paths = kml.paths.all()
all_polygons = kml.polygons.all()
all_points = kml.points.all()
all_multigeometries = kml.multigeometries.all()

# Note: For geometry elements (points, paths, polygons), .all() also collects from:
# - Placemarks at root level and in all nested folders
# - MultiGeometry containers (both standalone and within Placemarks)

Document Properties

KMLFile.document_name: Get the document name from KML.

KMLFile.document_description: Get the document description from KML.

Utility Methods

KMLFile.element_counts()[source]

Get counts of each element type.

Return type:: Dict[str, int]
Returns:: Dictionary with element type counts

KMLFile.all_elements()[source]

Get all elements from the KML file.

Return type:: List[Any]
Returns:: Combined list of all elements

Complete Usage Examples

Basic Usage

from kmlorm import KMLFile

# Load from various sources
kml_from_file = KMLFile.from_file('data.kml')
kml_from_url = KMLFile.from_url('https://example.com/data.kml')
kml_from_string = KMLFile.from_string(kml_content)

# Access document metadata
print(f"Document: {kml_from_file.document_name}")
print(f"Description: {kml_from_file.document_description}")

# Get element counts
counts = kml_from_file.element_counts()
print(f"Total placemarks: {counts['placemarks']}")
print(f"Total folders: {counts['folders']}")

Querying Elements

from kmlorm import KMLFile

kml = KMLFile.from_file('stores.kml')

# Basic queries (direct children only)
capital_stores = kml.placemarks.children().filter(name__icontains='capital')
visible_folders = kml.folders.children().filter(visibility=True)

# Comprehensive queries (including nested elements)
all_capital_stores = kml.placemarks.all().filter(name__icontains='capital')
all_visible_folders = kml.folders.all().filter(visibility=True)

# Geospatial queries
nearby_stores = kml.placemarks.all().near(-76.6, 39.3, radius_km=25)
bounded_elements = kml.placemarks.all().within_bounds(
    north=39.5, south=39.0, east=-76.0, west=-77.0
)

# Get specific elements
try:
    specific_store = kml.placemarks.all().get(name='Capital Electric - Rosedale')
    print(f"Found: {specific_store.name} at {specific_store.address}")
except KMLElementNotFound:
    print("Store not found")

Working with All Elements

from kmlorm import KMLFile

kml = KMLFile.from_file('comprehensive.kml')

# Get all elements as a single list
all_elements = kml.all_elements()
print(f"Total elements in KML: {len(all_elements)}")

# Process different element types
for element in all_elements:
    if hasattr(element, 'coordinates') and element.coordinates:
        print(f"{element.__class__.__name__}: {element.name} at {element.coordinates}")
    else:
        print(f"{element.__class__.__name__}: {element.name}")