Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

1.0.0 final #389

Merged
merged 11 commits into from
Nov 19, 2024
Merged

1.0.0 final #389

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
a3c3cbc
update README installation command, bump version to 1.0.0, and change…
cleder Nov 17, 2024
48faf9a
enhance documentation for XML handling classes and methods in fastkml
cleder Nov 17, 2024
bc3fd96
enhance documentation for fastkml modules and classes
cleder Nov 17, 2024
539f545
enhance documentation for Registry class usage and its singleton pattern
cleder Nov 17, 2024
1f383a6
add animation to documentation, reorganize reference guide
cleder Nov 17, 2024
512fc92
enhance documentation for RelaxedEnum and AltitudeMode classes with a…
cleder Nov 17, 2024
1d788aa
enhance documentation for KML file creation examples with additional …
cleder Nov 17, 2024
d8d28e8
enhance documentation for KML file creation examples with additional …
cleder Nov 17, 2024
e980d5f
kml.KML documentation
cleder Nov 18, 2024
a2c3179
[pre-commit.ci] pre-commit autoupdate
pre-commit-ci[bot] Nov 18, 2024
e7d5dd7
Merge pull request #388 from cleder/pre-commit-ci-update-config
cleder Nov 18, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ repos:
hooks:
- id: absolufy-imports
- repo: https://github.com/astral-sh/ruff-pre-commit
rev: 'v0.7.3'
rev: 'v0.7.4'
hooks:
- id: ruff
- id: ruff-format
Expand Down
2 changes: 1 addition & 1 deletion README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,7 @@ Optional

.. code-block:: bash

pip install --pre "fastkml[lxml]"
pip install "fastkml[lxml]"

Limitations
===========
Expand Down
Binary file added docs/co2growth.gif
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
22 changes: 16 additions & 6 deletions docs/create_kml_files.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,14 @@ Read a shapefile and build a 3D KML visualization.

This example shows how to read a shapefile and build a 3D KML visualization from it.

.. image:: co2-per-capita-2020.jpg
:alt: CO2 emissions per capita in 2020
:align: center
:width: 800px
:target: https://ion.cesium.com/stories/viewer/?id=a3cf93bb-bbb8-488b-8643-09c037ec12b8

(click on the image to see the KML visualization in Cesium Ion)

You will need to install `pyshp <https://pypi.org/project/pyshp/>`_ (``pip install pyshp``).

For this example we will use the
Expand Down Expand Up @@ -108,12 +116,6 @@ Finally, we create the KML object and write it to a file:

The resulting KML file can be opened in Google Earth or any other KML viewer.

.. image:: co2-per-capita-2020.jpg
:alt: CO2 emissions per capita in 2020
:align: center
:width: 800px
:target: https://ion.cesium.com/stories/viewer/?id=a3cf93bb-bbb8-488b-8643-09c037ec12b8


Build an animated over time KML visualization
----------------------------------------------
Expand All @@ -122,6 +124,14 @@ This example shows how to build an animated KML visualization over time.
We will use the same data as in the previous example, but this time we will
create a KML file that shows the CO2 emissions accumulating from 1995 to 2022.

.. image:: co2growth.gif
:alt: CO2 emissions per capita growth
:align: center
:width: 800px
:target: https://ion.cesium.com/stories/viewer/?id=602c8c64-72aa-4c57-8a01-752b6fbc62d0

(click on the image to see the full visualization in Cesium Ion)

First we import the necessary modules:

.. code-block:: pycon
Expand Down
96 changes: 57 additions & 39 deletions docs/fastkml.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,27 +4,76 @@ Reference Guide

.. automodule:: fastkml

fastkml.kml
------------------

fastkml.about
--------------------

.. automodule:: fastkml.about
.. automodule:: fastkml.kml
:members:
:undoc-members:
:show-inheritance:

fastkml.atom

fastkml.base
-------------------

.. automodule:: fastkml.atom
.. automodule:: fastkml.base
:members:
:undoc-members:
:show-inheritance:

fastkml.base
.. autoclass:: fastkml.base._XMLObject
:members: etree_element, _get_kwargs, to_string, from_string, validate, __init__
:undoc-members:
:show-inheritance:

fastkml.registry
-----------------------

.. automodule:: fastkml.registry
:members:
:undoc-members:
:show-inheritance:

.. autoclass:: fastkml.registry::Registry
:members: register, get
:undoc-members:
:show-inheritance:
Comment on lines +37 to +40
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codebase verification

Registry class documentation should include additional methods

The Registry class has the following public methods that should be documented:

  • register (already documented)
  • get (already documented)
  • __init__ (constructor)
  • __repr__ (string representation)
  • __call__ (callable interface)

Please update the documentation to include all public methods for completeness.

🔗 Analysis chain

Verify Registry class documentation completeness.

The Registry class documentation only shows register and get methods. Please verify if there are other public methods that should be documented.

🏁 Scripts executed

The following scripts were executed for the analysis:

Script:

#!/bin/bash
# Search for additional public methods in Registry class
ast-grep --pattern 'class Registry:
  $$$
  def $_($$$) {
    $$$
  }
  $$$
}'

Length of output: 80

Script:

#!/bin/bash
# Let's try a different approach to find the Registry class implementation
rg -l "class Registry"

Length of output: 44

Script:

#!/bin/bash
# Search for method definitions in files containing Registry class
rg "^\s+def\s+\w+" --type py -A 1 $(rg -l "class Registry")

Length of output: 452

Script:

#!/bin/bash
# Get the actual content of the Registry class implementation
rg "class Registry" -A 30 --type py

Length of output: 3272


fastkml.kml\_base
------------------------

.. automodule:: fastkml.kml_base
:members:
:undoc-members:
:show-inheritance:

.. autoclass:: fastkml.kml_base::_BaseObject
:members: __init__
:undoc-members:
:show-inheritance:

fastkml.helpers
----------------------

.. automodule:: fastkml.helpers
:members:
:undoc-members:
:show-inheritance:

fastkml.about
--------------------

.. automodule:: fastkml.about
:members:
:undoc-members:
:show-inheritance:

.. autodata:: __version__

fastkml.atom
-------------------

.. automodule:: fastkml.base
.. automodule:: fastkml.atom
:members:
:undoc-members:
:show-inheritance:
Expand Down Expand Up @@ -93,30 +142,6 @@ fastkml.gx
:undoc-members:
:show-inheritance:

fastkml.helpers
----------------------

.. automodule:: fastkml.helpers
:members:
:undoc-members:
:show-inheritance:

fastkml.kml
------------------

.. automodule:: fastkml.kml
:members:
:undoc-members:
:show-inheritance:

fastkml.kml\_base
------------------------

.. automodule:: fastkml.kml_base
:members:
:undoc-members:
:show-inheritance:

fastkml.links
--------------------

Expand All @@ -141,13 +166,6 @@ fastkml.overlays
:undoc-members:
:show-inheritance:

fastkml.registry
-----------------------

.. automodule:: fastkml.registry
:members:
:undoc-members:
:show-inheritance:

fastkml.styles
---------------------
Expand Down
3 changes: 2 additions & 1 deletion fastkml/about.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
The only purpose of this module is to provide a version number for the package.
"""

__version__ = "1.0.0rc2"
__version__ = "1.0.0"
"""Fastkml version number."""

__all__ = ["__version__"]
54 changes: 53 additions & 1 deletion fastkml/base.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,22 @@
# along with this library; if not, write to the Free Software Foundation, Inc.,
# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

"""Abstract base classes."""
"""
Abstract XML base class.

The purpose of ``_XMLObject`` is to serve as a base class for KML objects in fastkml.
Its main functions are:

- Provide a common interface for XML serialization and deserialization.
- Handle namespace management for KML elements.
- Manage attribute storage and retrieval for derived classes.
- Provide the ``etree_element()`` method for converting objects to XML Elements.
- Facilitate integration with the registry system for flexible XML mapping.

By inheriting from ``_XMLObject``, KML classes gain these capabilities, ensuring
consistent handling of XML operations across the library.

"""

import logging
from typing import Any
Expand Down Expand Up @@ -127,6 +142,18 @@ def etree_element(
"""
Return the KML Object as an Element.

This method essentially converts the Python object to its XML representation,
using the registry to determine how each attribute should be serialized.

- Create an XML Element with the object's tag name and namespace.
- Iterate through registered attributes for the object's class.
For each attribute:
- Call the corresponding set_element function. This function adds the
attribute to the Element as a sub-element or attribute.
- Handle different data types and nested objects.
- Apply precision and verbosity settings if specified.
- Return the complete Element tree representing the object.

Parameters
----------
precision : Optional[int], default=None
Expand Down Expand Up @@ -280,6 +307,31 @@ def _get_kwargs(
"""
Get the keyword arguments for the class constructor.

A class method used for XML deserialization. Its main purposes are:

- Extract attribute values from an XML element.
- Convert these values into appropriate Python types.
- Prepare a dictionary of keyword arguments for object initialization.
- It is called during the parsing process to populate object attributes from XML
data. The method uses the registry and helper functions to handle different
attribute types and nested objects.

Subclasses may override this method to add custom deserialization logic for
specific KML elements, although this should be rare. Prefer registration over
a custom ``_get_kwargs`` implementation to ensure consistent handling of KML:

- Consistency: Ensures uniform handling across all KML elements.
- Maintainability: Centralizes parsing logic, making updates easier.
- Declarative approach: Simplifies code by moving logic to configuration.
- Reusability: Allows sharing of parsing logic across different classes.
- Separation of concerns: Keeps parsing logic separate from class definitions.
- Extensibility: Makes it easier to add new attributes or change parsing
behavior.
- Reduced duplication: Avoids repeating similar parsing code in multiple
classes.
- Easier testing: Allows testing of parsing logic independently of class
implementations.

Parameters
----------
ns : str
Expand Down
77 changes: 47 additions & 30 deletions fastkml/enums.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,22 @@
from enum import Enum
from enum import unique

__all__ = [
"AltitudeMode",
"ColorMode",
"DataType",
"DateTimeResolution",
"DisplayMode",
"GridOrigin",
"PairKey",
"RefreshMode",
"RelaxedEnum",
"Shape",
"Units",
"Verbosity",
"ViewRefreshMode",
]

logger = logging.getLogger(__name__)


Expand All @@ -40,14 +56,15 @@ class RelaxedEnum(Enum):
Usage:
To use this enum, simply subclass `RelaxedEnum` and define your enum values.

Example:
-------
class MyEnum(RelaxedEnum):
VALUE1 = "value1"
VALUE2 = "value2"
Example::

class AltitudeMode(RelaxedEnum):
clamp_to_ground = "clampToGround"
relative_to_ground = "relativeToGround"
absolute = "absolute"

my_value = MyEnum("VALUE1") # Case-insensitive match
print(my_value) # Output: MyEnum.VALUE1
my_value = AltitudeMode("CLAMPTOGROUND") # Case-insensitive match
print(my_value) # Output: AltitudeMode.clamp_to_ground

The subclass must define all values as strings.

Expand Down Expand Up @@ -102,33 +119,33 @@ class AltitudeMode(RelaxedEnum):
Possible values are

- clampToGround - (default) Indicates to ignore an altitude specification
(for example, in the <coordinates> tag).
(for example, in the <coordinates> tag).
- relativeToGround - Sets the altitude of the element relative to the actual
ground elevation of a particular location.
For example, if the ground elevation of a location is exactly at sea level
and the altitude for a point is set to 9 meters,
then the elevation for the icon of a point placemark elevation is 9 meters
with this mode.
However, if the same coordinate is set over a location where the ground
elevation is 10 meters above sea level, then the elevation of the coordinate
is 19 meters.
A typical use of this mode is for placing telephone poles or a ski lift.
ground elevation of a particular location.
For example, if the ground elevation of a location is exactly at sea level
and the altitude for a point is set to 9 meters,
then the elevation for the icon of a point placemark elevation is 9 meters
with this mode.
However, if the same coordinate is set over a location where the ground
elevation is 10 meters above sea level, then the elevation of the coordinate
is 19 meters.
A typical use of this mode is for placing telephone poles or a ski lift.
- absolute - Sets the altitude of the coordinate relative to sea level,
regardless of the actual elevation of the terrain beneath the element.
For example, if you set the altitude of a coordinate to 10 meters with an
absolute altitude mode, the icon of a point placemark will appear to be at
ground level if the terrain beneath is also 10 meters above sea level.
If the terrain is 3 meters above sea level, the placemark will appear elevated
above the terrain by 7 meters.
A typical use of this mode is for aircraft placement.
regardless of the actual elevation of the terrain beneath the element.
For example, if you set the altitude of a coordinate to 10 meters with an
absolute altitude mode, the icon of a point placemark will appear to be at
ground level if the terrain beneath is also 10 meters above sea level.
If the terrain is 3 meters above sea level, the placemark will appear elevated
above the terrain by 7 meters.
A typical use of this mode is for aircraft placement.
- relativeToSeaFloor - Interprets the altitude as a value in meters above the
sea floor.
If the point is above land rather than sea, the altitude will be interpreted
as being above the ground.
sea floor.
If the point is above land rather than sea, the altitude will be interpreted
as being above the ground.
- clampToSeaFloor - The altitude specification is ignored, and the point will be
positioned on the sea floor.
If the point is on land rather than at sea, the point will be positioned on
the ground.
positioned on the sea floor.
If the point is on land rather than at sea, the point will be positioned on
the ground.

The Values relativeToSeaFloor and clampToSeaFloor are not part of the KML definition
but of the <gx:altitudeMode> a KML extension in the Google extension namespace,
Expand Down
Loading
Loading