Merge pull request #377 from cleder/develop

1.0.0 beta 1

.github/workflows/run-all-tests.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13-dev', '3.14-dev']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13', '3.14-dev']
 
     steps:
       - uses: actions/checkout@v4
@@ -29,7 +29,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13-dev']
+        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12', '3.13']
 
     steps:
       - uses: actions/checkout@v4
@@ -43,7 +43,7 @@ jobs:
           pip install -e ".[tests, lxml]"
       - name: Test with pytest
         run: |
-          pytest tests --cov=fastkml --cov=tests --cov-fail-under=88 --cov-report=xml
+          pytest tests --cov=fastkml --cov=tests --cov-fail-under=95 --cov-report=xml
       - name: "Upload coverage to Codecov"
         if: ${{ matrix.python-version==3.11 }}
         uses: codecov/codecov-action@v4
@@ -67,10 +67,18 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip wheel
-          pip install -e ".[tests, lxml]"
+          pip install -e ".[tests, lxml, docs]"
       - name: test the pythoncode in the documentation
         run: |
           python -m doctest docs/*.rst -v
+      - name: Run the pythoncode in the examples
+        run: |
+          python examples/read_kml.py
+          python examples/shp2kml.py
+          python examples/shp2kml_timed.py
+          python examples/simple_example.py
+          python examples/transform_cascading_style.py
+
 
   static-tests:
     runs-on: ubuntu-latest
@@ -122,39 +130,69 @@ jobs:
         run: |
           pytest tests
 
-  publish:
-    if: "github.event_name == 'push' && github.repository == 'cleder/fastkml'"
-    needs: [cpython, static-tests, pypy, cpython-lxml, doctest-lxml]
-    name: Build and publish to PyPI and TestPyPI
+  build-package:
+    name: Build & inspect our package.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: hynek/build-and-inspect-python-package@v2
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Check with pyroma
+        run: |
+          python -m pip install pyroma
+          pyroma .
+      - name: Check tag name
+        if: >-
+          github.event_name == 'push' &&
+          startsWith(github.ref, 'refs/tags')
+        run: |
+          python -m pip install vercheck
+          vercheck $GITHUB_REF_NAME fastkml/about.py
+
+  test-publish:
+    if: >-
+      github.event_name == 'push' &&
+      github.repository == 'cleder/fastkml' &&
+      startsWith(github.ref, 'refs/tags')
+    needs: [cpython, static-tests, pypy, cpython-lxml, doctest-lxml, build-package]
+    name: Test install on TestPyPI
+    runs-on: ubuntu-latest
+    environment: test-release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download packages built by build-package
+        uses: actions/download-artifact@v4
         with:
-          python-version: 3.12
-      - name: Install pypa/build
-        run: >-
-          python -m
-          pip install
-          build
-          --user
-      - name: Build a binary wheel and a source tarball
-        run: >-
-          python -m
-          build
-          --sdist
-          --wheel
-          --outdir dist/
-      - name: Publish distribution 📦 to Test PyPI for tags
-        if: startsWith(github.ref, 'refs/tags')
+          name: Packages
+          path: dist
+
+      - name: Upload package to Test PyPI
         uses: pypa/gh-action-pypi-publish@release/v1
         with:
-          password: ${{ secrets.TEST_PYPI_API_TOKEN }}
-          repository_url: https://test.pypi.org/legacy/
+          repository-url: https://test.pypi.org/legacy/
+
+
+  publish:
+    if: >-
+        github.event_name == 'push' &&
+        github.repository == 'cleder/fastkml' &&
+        github.ref == 'refs/heads/main'
+    needs: [cpython, static-tests, pypy, cpython-lxml, doctest-lxml, build-package]
+    name: Publish to PyPI on push to main
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download packages built by build-package
+        uses: actions/download-artifact@v4
+        with:
+          name: Packages
+          path: dist
+
       - name: Publish distribution 📦 to PyPI for push to main
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         uses: pypa/gh-action-pypi-publish@release/v1
-        with:
-          password: ${{ secrets.PYPI_API_TOKEN }}
 ...

.pre-commit-config.yaml

@@ -1,7 +1,7 @@
 ---
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
       - id: check-added-large-files
       - id: check-docstring-first
@@ -15,7 +15,11 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
       - id: name-tests-test
-        exclude: ^tests/base.py
+        exclude: (?x)^(
+                tests/base.py|
+                tests/hypothesis/common.py|
+                tests/hypothesis/strategies.py
+            )$
       - id: no-commit-to-branch
       - id: pretty-format-json
       - id: requirements-txt-fixer
@@ -25,40 +29,31 @@ repos:
     hooks:
       - id: pyprojectsort
   - repo: https://github.com/abravalheri/validate-pyproject
-    rev: v0.20.2
+    rev: v0.22
     hooks:
       - id: validate-pyproject
-  - repo: https://github.com/ikamensh/flynt/
-    rev: "1.0.1"
-    hooks:
-      - id: flynt
   - repo: https://github.com/MarcoGorelli/absolufy-imports
     rev: v0.3.1
     hooks:
       - id: absolufy-imports
-  - repo: https://github.com/asottile/pyupgrade
-    rev: v3.17.0
-    hooks:
-      - id: pyupgrade
-        args: ["--py3-plus", "--py37-plus"]
   - repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
       - id: black
   - repo: https://github.com/pycqa/isort
     rev: 5.13.2
     hooks:
       - id: isort
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: 'v0.6.8'
+    rev: 'v0.7.2'
     hooks:
       - id: ruff
   - repo: https://github.com/PyCQA/flake8
     rev: 7.1.1
     hooks:
       - id: flake8
   - repo: https://github.com/pre-commit/pygrep-hooks
-    rev: v1.10.0  # Use the ref you want to point at
+    rev: v1.10.0
     hooks:
       - id: python-use-type-annotations
       - id: python-check-blanket-type-ignore
@@ -73,21 +68,21 @@ repos:
     rev: "v6.2.4"
     hooks:
       - id: rstcheck
+  - repo: https://github.com/sphinx-contrib/sphinx-lint
+    rev: "v1.0.0"
+    hooks:
+      - id: sphinx-lint
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.2
+    rev: v1.13.0
     hooks:
       - id: mypy
-        additional_dependencies: [pygeoif>=1.4, arrow, pytest]
+        additional_dependencies: [pygeoif>=1.4, arrow, pytest, hypothesis]
   - repo: https://github.com/adamchainz/blacken-docs
-    rev: "1.18.0"
+    rev: "1.19.1"
     hooks:
       - id: blacken-docs
   - repo: https://github.com/crate-ci/typos
-    rev: v1.25.0
+    rev: v1.27.0
     hooks:
       - id: typos
-  # - repo: https://github.com/Lucas-C/pre-commit-hooks-markup
-  #   rev: v1.0.1
-  #   hooks:
-  #     - id: rst-linter
 ...

README.rst

@@ -1,16 +1,22 @@
 Introduction
 ============
 
+.. inclusion-marker-do-not-remove
+
 KML is an XML geospatial data format and an OGC_ standard that deserves a canonical python implementation.
 
 Fastkml is a library to read, write and manipulate KML files. It aims to keep
 it simple and fast (using lxml_ if available). Fast refers to the time you
 spend to write and read KML files as well as the time you spend to get
 acquainted to the library or to create KML objects. It aims to provide all of
-the functionality that KML clients such as `OpenLayers
-<http://openlayers.org/>`_, `Google Maps <http://maps.google.com/>`_, and
-`Google Earth <http://earth.google.com/>`_ provides.
+the functionality that KML clients such as `Marble <https://marble.kde.org/>`_,
+`Cesium JS <https://cesium.com/>`_, `OpenLayers <https://openlayers.org/>`_,
+`Google Maps <http://maps.google.com/>`_, and
+`Google Earth <http://earth.google.com/>`_ support.
 
+For more details about the KML Specification, check out the `KML Reference
+<https://developers.google.com/kml/documentation/kmlreference>`_ on the Google
+developers site.
 
 Geometries are handled as pygeoif_ objects.
 
@@ -87,14 +93,6 @@ You can find all of the documentation for FastKML at `fastkml.readthedocs.org
 please submit a pull request on `GitHub <https://github.com/cleder/fastkml>`_
 with the improvement.
 
-Have a look at Aryan Guptas
-`The Definite Guide to FastKML. <https://medium.com/@wwaryan/the-definite-only-guide-to-fastkml-58b8e19b8454>`_
-
-Alternatives
-============
-
-`Keytree <https://github.com/Toblerity/keytree>`_ provides a less comprehensive, but more flexible
-approach.
 
 Install
 ========
@@ -117,10 +115,6 @@ Optional
 Limitations
 ===========
 
-*Tessellate*, *Extrude* and *Altitude Mode* are assigned to a Geometry or
-Geometry collection (MultiGeometry). You cannot assign different values of
-*Tessellate*, *Extrude* or *Altitude Mode* on parts of a MultiGeometry.
-
 Currently, the only major feature missing for the full Google Earth experience
 is the `gx extension
 <https://developers.google.com/kml/documentation/kmlreference#kmlextensions>`_.

docs/Document-clean.kml

@@ -0,0 +1 @@
+../tests/ogc_conformance/data/kml/Document-clean.kml

docs/alternatives.rst

@@ -0,0 +1,19 @@
+Alternative KML libraries
+=========================
+There are several other libraries that can read and/or write KML files.
+Here are a few of them:
+
+- Keytree_ provides a less comprehensive, but more flexible approach. It provides functions for reading and writing KML using the ElementTree API.
+- PyKML_ is a more feature-rich library, but it is not actively maintained.
+- geojson2kml_  converts GeoJSON to KML files.
+- kml2geojson_ is a Python library to convert KML files to GeoJSON files.
+- Simplekml_ is a python package which enables you to generate KML with as little effort as possible.
+- kmlb_ A Straightforward Google Earth KML Builder.
+
+
+.. _kml2geojson: https://github.com/mrcagney/kml2geojson
+.. _PyKML: https://pythonhosted.org/pykml/
+.. _Keytree: https://github.com/Toblerity/keytree
+.. _geojson2kml: https://github.com/aguinane/geojson-to-kml
+.. _Simplekml: https://github.com/eisoldt/simplekml
+.. _kmlb: https://github.com/HFM3/kmlb

docs/conf.py

@@ -32,7 +32,11 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.coverage",
+    "sphinx.ext.viewcode",
 ]
+autosummary_generate = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -48,14 +52,14 @@
 
 # General information about the project.
 project = "FastKML"
-copyright = "2014, Christian Ledermann & Ian Lee"
+copyright = "2014 -2024, Christian Ledermann & Ian Lee"
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = about.__version__
+version = ".".join(about.__version__.split(".")[:2])
 # The full version, including alpha/beta/rc tags.
 release = about.__version__