Metadata-Version: 2.4
Name: kml2geojson
Version: 6.0.0
Summary: A Python library to convert KML files to GeoJSON files
Project-URL: Homepage, https://codeberg.org/araichev/kml2geojson
Project-URL: Documentation, https://araichev.codeberg.page/kml2geojson_docs
Author-email: Alexander Raichev <alexander@raichev.net>
License-Expression: MIT
License-File: LICENSE.txt
Requires-Python: >=3.11
Requires-Dist: click>=8.0.1
Description-Content-Type: text/x-rst

kml2geojson
************
Tests: |ci-badge|

.. |ci-badge| image:: https://ci.codeberg.org/api/badges/araichev/kml2geojson/status.svg?branch=master
   :target: https://ci.codeberg.org/repos/araichev/kml2geojson
   :alt: pipeline status
    
kml2geojson is a Python package to convert KML files to GeoJSON files.
It's a lightweight, dependency-minimal, web-output-focused alternative to GDAL.
Most of its code is a translation into Python of the Node.js package `togeojson <https://github.com/placemark/togeojson>`_, but kml2geojson also adds the following features.

- Preserve KML object styling, such as color and opacity
- Optionally create a style dictionary cataloging all the KML styles used, including styles referenced through StyleMaps
- Optionally create several GeoJSON FeatureCollections, one for each KML folder present
- Optionally build a tree of Features that preserves nested KML folder structure
- Convert GroundOverlays and NetworkLinks to Features alongside Placemarks
- Convert typed ExtendedData via KML Schemas


Authors
========
- Alex Raichev (2015-10-03), maintainer


Installation
=============
Install from PyPI via, say, ``uv add kml2geojson``.


Usage
======
Use as a library or from the command line.
For instructions on the latter, type ``k2g --help``.


Documentation
=============
The documentation is built via Sphinx from the source code in the ``docs`` directory then published at `Codeberg Pages <https://araichev.codeberg.page/kml2geojson_docs>`_.


Contributing
===================
If you want to help develop this project, here is some background reading.

- The `KML reference <https://developers.google.com/kml/documentation/kmlreference?hl=en>`_
- Python's `Minimal DOM implementation <https://docs.python.org/3.4/library/xml.dom.minidom.html>`_, which this project uses to parse KML files

Notes
========
- This project's development status is Beta.
- This project uses semantic versioning.
- If you would like to fund additional features to this project, feel free to email me.
- Thanks to `MRCagney <http://www.mrcagney.com/>`_ for periodically donating to this project.
- Constructive feedback and contributions are welcome.
  Please issue pull requests from a feature branch into the ``develop`` branch and include tests.



Maintainer Notes
================
- After pushing to master, update the published docs via ``uv run make -C docs publish-docs``

Changes
========

6.0.0, 2026-07-06
-----------------
- Brought feature extraction to parity with `@tmcw/togeojson <https://github.com/placemark/togeojson>`_ v7, while keeping this package's reusable style catalog approach.
- Added StyleMap resolution to the style catalogs, with a ``style_map_key`` option to choose the 'normal' or 'highlight' pair.
- Added LabelStyle and richer IconStyle extraction (color, opacity, scale, heading, hot spot offset) and a new public function ``build_style``.
- Fixed the bug where an IconStyle wiped previously collected line and polygon styles in the same Style element.
- Fixed opacity conversion to divide alpha by 255 instead of 256.
- Added GroundOverlay support for LatLonBox (with rotation) and gx:LatLonQuad via the new function ``build_ground_overlay``.
- Added NetworkLink support (without fetching linked files) via the new function ``build_network_link``.
- Added typed ExtendedData conversion via KML Schema SimpleFields and the new function ``build_schema``.
- Added TimeStamp extraction into a ``timeStamp`` property.
- Added extraction of address, phoneNumber, open, and visibility properties, with visibility converted to a boolean.
- Added HTML-flagged descriptions for CDATA description content, following togeojson's convention.
- Added the new function ``build_feature_tree`` to preserve nested KML folder structure.
- Breaking change: track times moved from a ``times`` property to a ``coordinateProperties`` property, following the geojson-coordinate-properties convention.
- Breaking change: features without geometry are now kept with a null geometry by default; use the new ``skip_null_geometry`` option to drop them.
- Breaking change: geometry extraction now considers only direct geometry children of a Placemark, closes unclosed polygon rings, converts bare LinearRings to LineStrings, converts single-coordinate tracks to Points, and skips degenerate geometries.
- Breaking change: ``convert`` now returns a dictionary with the key 'feature_collections' and, when a style type is given, the key 'style', instead of a variable-shape sequence.
- Breaking change: removed the unused ``GEOTYPES`` constant and added ``__all__`` to the ``main`` module to stop star imports leaking implementation names.
- Added the ``--style-map-key`` and ``--skip-null-geometry`` options to the ``k2g`` command line interface.
- Removed stale test fixtures that reflected the old output format.

5.1.1, 2026-03-12
-----------------
- Migrated packaging metadata to PEP 621 in ``pyproject.toml`` and switch the
  build backend to Hatchling.
- Updated project URLs to the current repository and documentation site.
- Raised the declared minimum Python version in package metadata.
- Modernized GitHub Actions to use ``uv`` and refresh the Python test matrix.
- Updated README installation and documentation guidance.
- Fixed ``k2g`` CLI output handling for styled and unstyled conversion paths.
- Restructured tests to use one test function per API function with sectioned
  behavioral coverage.
- Added CLI integration tests for the no-style and styled separate-folders paths.

5.1.0, 2022-04-29
-----------------
- Extended ``convert()`` to accept a KML file object.
- Added type hints.
- Updated dependencies and removed version caps.
- Dropped support for Python versions less than 3.8.
- Switched from Travis CI to Github Actions.


5.0.1, 2021-10-11
-----------------
- Re-included the MIT License file and added more metadata to the file ``pyproject.toml`` for a more informative listing on PyPi.


5.0.0, 2021-10-07
-----------------
- Upgraded to Python 3.9 and dropped support for Python versions < 3.6.
- Switched to Poetry.
- Breaking change: refactored the ``convert`` function to return dictionaries instead of files.
- Moved docs from Rawgit to Github Pages.


4.0.2, 2017-04-26
-------------------
- Fixed the bug where ``setup.py`` could not find the license file.


4.0.1, 2017-04-22
-------------------
- Moved the name of a FeatureCollection into a 'name' attribute, because `RFC 7946 says that a GeoJSON FetaureCollection must not have a 'properties' attribute <https://tools.ietf.org/html/rfc7946#section-7>`_
- Stripped leanding and trailing whitespace from text content to avoid cluttered or blank name and description attribute values
- Switched to pytest for testing


4.0.0, 2016-11-24
-------------------
- Moved command line functionality to separate module
- Renamed some functions


3.0.4, 2015-10-15
-------------------
Disambiguated filenames in ``main()``.


3.0.3, 2015-10-13
-------------------
Improved ``to_filename()`` again.


3.0.2, 2015-10-12
-------------------
Improved ``to_filename()`` and removed the lowercasing.


3.0.1, 2015-10-12
-------------------
Tweaked ``to_filename()`` to lowercase and underscore results. 
Forgot to do that last time.


3.0.0, 2015-10-12
------------------
Changed the output of ``build_layers()`` and moved layer names into the GeoJSON FeatureCollections


2.0.2, 2015-10-12
-------------------
- Replaced underscores with dashes in command line options


2.0.1, 2015-10-12
-------------------
- Set default border style for colored polygons
 

2.0.0, 2015-10-08
------------------
- Added documentation
- Tweaked the command line tool options 


1.0.0, 2015-10-05
------------------
- Changed some names 
- Added lots of tests


0.1.1, 2015-10-03
-------------------
Fixed packaging to find ``README.rst``


0.1.0, 2015-10-03
-----------------
First


