h2gis 0.0.1__tar.gz

h2gis-0.0.1/MANIFEST.in

@@ -0,0 +1,4 @@
+# MANIFEST.in
+include README.md
+recursive-include h2gis/lib *.so *.dll *.dylib
+recursive-include docs *.md

h2gis-0.0.1/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: h2gis
+Version: 0.0.1
+Summary: A Python library to use an H2GIS database through a native GraalVM bridge.
+Home-page: https://github.com/yourusername/h2gis
+Author: Lemap
+Author-email: you@example.com
+License: LGPL-3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# h2gis-python
+
+A lib thal allows to interract with a h2gis lib. Do not forget when you create an H2gisConnection object to put the lib.so full path as a parameter. Without this, it will not work.
+
+To insall run :
+```
+ python setup.py bdist_wheel
+ pip install dist/h2gis-0.0.1-py3-none-any.whl  --force-reinstall
+```

h2gis-0.0.1/README.md

@@ -0,0 +1,9 @@
+# h2gis-python
+
+A lib thal allows to interract with a h2gis lib. Do not forget when you create an H2gisConnection object to put the lib.so full path as a parameter. Without this, it will not work.
+
+To insall run :
+```
+ python setup.py bdist_wheel
+ pip install dist/h2gis-0.0.1-py3-none-any.whl  --force-reinstall
+```

h2gis-0.0.1/docs/examples.md

@@ -0,0 +1,46 @@
+# Usage Examples
+
+## Basic Example
+
+```python
+# Example usage:
+from h2gis import H2gisConnector
+import time
+import statistics
+
+
+h2gis = H2gisConnector("./h2gis/h2gis.so")
+h2gis.connect("./test", "sa", "sa")
+
+
+#currently the two linew below are not working, you must do it via the .jar of h2gis, otherwise nothing will work
+h2gis.execute("CREATE ALIAS IF NOT EXISTS H2GIS_SPATIAL FOR \"org.h2gis.functions.factory.H2GISFunctions.load\";")
+
+h2gis.execute("DROP TABLE TEST IF EXISTS;")
+
+
+times_nat = []
+i = 0
+for i in range(0, 50):
+    start = time.perf_counter()
+    h2gis.execute("DROP TABLE TEST IF EXISTS;")
+    h2gis.execute("CALL GeoJsonRead('./test.geojson');")
+    end = time.perf_counter()
+    times_nat.append(end - start)
+    print("etape ", i, "finished")
+
+print("elapsed native time ", sum(times_nat))
+
+print("average native time ", statistics.mean(times_nat))
+
+h2gis.close()
+```
+
+## Custom Native Library Path
+
+```python
+db = H2gisConnector(lib_path="/custom/path/h2gis.so")
+```
+
+## Notes
+- By default, the native `.so`, `.dll` are already included in the package, in the `lib` folder.

h2gis-0.0.1/docs/h2gisconnector.md

@@ -0,0 +1,35 @@
+# H2gisConnector Class
+
+## Overview
+
+`H2gisConnector` is a Python class that wraps a native shared library compiled with GraalVM. It provides access to an embedded H2GIS database using GraalVM isolate and thread objects.
+
+## Constructor
+
+```python
+H2gisConnector(lib_path=None)
+```
+
+- `lib_path`: Optional path to the `.so`, `.dll`, or `.dylib` file. If not provided, a default path is used based on the current OS.
+
+## Methods
+
+### `connect(db_file: str, username="sa", password="")`
+
+Connect to a local H2GIS database file.
+
+### `execute(sql: str) -> int`
+
+Execute an `INSERT`, `UPDATE`, or `DELETE` SQL statement.
+
+### `fetch(sql: str) -> list[str]`
+
+Execute a `SELECT` SQL query and return results as a list of strings (one per row).
+
+### `close()`
+
+Close the active database connection.
+
+### `__del__()`
+
+Destructor that automatically tears down the GraalVM isolate and closes any connection.

h2gis-0.0.1/docs/index.md

@@ -0,0 +1,9 @@
+# H2GIS Python Package
+
+This package provides a Python interface to the native H2GIS spatial database engine using a GraalVM-compiled native library and a C interface.
+
+## Modules
+
+- [connector.md](./connector.md): Detailed documentation for the `H2gisConnector` class.
+- [usage.md](./usage.md): Example usage of the library.
+- [installation.md](installation.md): Installation and setup instructions.

h2gis-0.0.1/docs/installation.md

@@ -0,0 +1,33 @@
+# Installation
+
+## Requirements
+
+- Python 3.7+
+- Native H2GIS shared library compiled with GraalVM
+- Supported platforms: Linux, Windows, macOS
+
+## Install the Python Package
+
+```bash
+pip install .
+```
+
+Ensure the native library file is present in the following structure:
+
+```
+h2gis/
+├── lib/
+│   ├── h2gis.so      # Linux
+│   ├── h2gis.dylib   # macOS
+│   └── h2gis.dll     # Windows
+```
+
+## Custom Library Path
+
+You can specify a custom path to the native library:
+
+```python
+from h2gis import H2gisConnector
+
+db = H2gisConnector(lib_path="/custom/path/to/h2gis.so")
+```

h2gis-0.0.1/h2gis/__init__.py

@@ -0,0 +1,4 @@
+from .h2gisconnector import H2gisConnector
+
+__all__ = ["H2gisConnector"]
+

h2gis-0.0.1/h2gis/h2gisconnector.py

@@ -0,0 +1,170 @@
+import ctypes
+import os
+import platform
+
+
+# --- Opaque struct placeholders for GraalVM native API ---
+class GraalIsolate(ctypes.Structure):
+    _fields_ = []
+
+
+class GraalIsolateThread(ctypes.Structure):
+    _fields_ = []
+
+
+class GraalIsolateParams(ctypes.Structure):
+    _fields_ = []
+
+
+GraalIsolate_p = ctypes.POINTER(GraalIsolate)
+GraalIsolateThread_p = ctypes.POINTER(GraalIsolateThread)
+
+
+class H2gisConnector:
+    """
+    Python wrapper for the native H2GIS library compiled with GraalVM.
+    """
+
+    def __init__(self, lib_path=None):
+        """
+        Initialize the H2GIS connector and create a GraalVM isolate.
+
+        :param lib_path: Optional path to the native .so/.dll/.dylib library
+        """
+        if lib_path is None:
+            lib_path = self._default_library_path()
+
+        self.lib = ctypes.CDLL(lib_path)
+        self._setup_c_function_signatures()
+
+        self.isolate = GraalIsolate_p()
+        self.thread = GraalIsolateThread_p()
+        self.connection = 0
+
+        params = GraalIsolateParams()
+        result = self.lib.graal_create_isolate(
+            ctypes.byref(params),
+            ctypes.byref(self.isolate),
+            ctypes.byref(self.thread)
+        )
+        if result != 0:
+            raise RuntimeError(f"Failed to create GraalVM isolate (code {result})")
+
+    def _default_library_path(self):
+        """Find default library path relative to this file."""
+        base_dir = os.path.dirname(__file__)
+        system = platform.system()
+        if system == "Windows":
+            libname = "h2gis.dll"
+        else:
+            libname = "h2gis.so"
+
+        return os.path.join(base_dir, "lib", libname)
+
+    def _setup_c_function_signatures(self):
+        """Declare argument and return types for native functions."""
+        self.lib.graal_create_isolate.argtypes = [
+            ctypes.POINTER(GraalIsolateParams),
+            ctypes.POINTER(GraalIsolate_p),
+            ctypes.POINTER(GraalIsolateThread_p),
+        ]
+        self.lib.graal_create_isolate.restype = ctypes.c_int
+
+        self.lib.graal_tear_down_isolate.argtypes = [GraalIsolateThread_p]
+        self.lib.graal_tear_down_isolate.restype = ctypes.c_int
+
+        self.lib.h2gis_connect.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+            ctypes.c_char_p,
+        ]
+        self.lib.h2gis_connect.restype = ctypes.c_long
+
+        self.lib.h2gis_execute_update.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_long,
+            ctypes.c_char_p,
+        ]
+        self.lib.h2gis_execute_update.restype = ctypes.c_int
+
+        self.lib.h2gis_execute.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_long,
+            ctypes.c_char_p,
+        ]
+        self.lib.h2gis_execute.restype = ctypes.c_long
+
+        self.lib.h2gis_fetch_row.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_long,
+        ]
+        self.lib.h2gis_fetch_row.restype = ctypes.c_char_p
+
+        self.lib.h2gis_close_query.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_long,
+        ]
+        self.lib.h2gis_close_query.restype = None
+
+        self.lib.h2gis_close_connection.argtypes = [
+            GraalIsolateThread_p,
+            ctypes.c_long,
+        ]
+        self.lib.h2gis_close_connection.restype = None
+
+    def connect(self, db_file: str, username="sa", password=""):
+        """Connect to a H2GIS database file."""
+        self.connection = self.lib.h2gis_connect(
+            self.thread,
+            db_file.encode("utf-8"),
+            username.encode("utf-8"),
+            password.encode("utf-8"),
+        )
+        if self.connection == 0:
+            raise RuntimeError("Failed to connect to H2GIS database.")
+
+    def execute(self, sql: str) -> int:
+        """Execute INSERT/UPDATE/DELETE statement and return affected row count."""
+        return self.lib.h2gis_execute_update(
+            self.thread,
+            self.connection,
+            sql.encode("utf-8"),
+        )
+
+    def fetch(self, sql: str) -> list[str]:
+        """Execute SELECT statement and return list of rows."""
+        handle = self.lib.h2gis_execute(
+            self.thread,
+            self.connection,
+            sql.encode("utf-8"),
+        )
+        if handle == 0:
+            raise RuntimeError("Query execution failed")
+
+        rows = []
+        while True:
+            row = self.lib.h2gis_fetch_row(self.thread, handle)
+            if not row:
+                break
+            rows.append(row.decode("utf-8"))
+
+        self.lib.h2gis_close_query(self.thread, handle)
+        return rows
+
+    def close(self):
+        """Close the database connection."""
+        if self.connection:
+            self.lib.h2gis_close_connection(self.thread, self.connection)
+            self.connection = 0
+
+    def __del__(self):
+        """Destructor to clean up isolate and resources."""
+        try:
+            self.close()
+        except Exception:
+            pass
+        try:
+            self.lib.graal_tear_down_isolate(self.thread)
+        except Exception:
+            pass

h2gis-0.0.1/h2gis.egg-info/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: h2gis
+Version: 0.0.1
+Summary: A Python library to use an H2GIS database through a native GraalVM bridge.
+Home-page: https://github.com/yourusername/h2gis
+Author: Lemap
+Author-email: you@example.com
+License: LGPL-3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: requires-python
+Dynamic: summary
+
+# h2gis-python
+
+A lib thal allows to interract with a h2gis lib. Do not forget when you create an H2gisConnection object to put the lib.so full path as a parameter. Without this, it will not work.
+
+To insall run :
+```
+ python setup.py bdist_wheel
+ pip install dist/h2gis-0.0.1-py3-none-any.whl  --force-reinstall
+```

h2gis-0.0.1/h2gis.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+MANIFEST.in
+README.md
+setup.py
+docs/examples.md
+docs/h2gisconnector.md
+docs/index.md
+docs/installation.md
+h2gis/__init__.py
+h2gis/h2gisconnector.py
+h2gis.egg-info/PKG-INFO
+h2gis.egg-info/SOURCES.txt
+h2gis.egg-info/dependency_links.txt
+h2gis.egg-info/top_level.txt
+h2gis/lib/h2gis.dll
+h2gis/lib/h2gis.so
+test/test_h2gis.py

h2gis-0.0.1/h2gis.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

h2gis-0.0.1/h2gis.egg-info/top_level.txt

@@ -0,0 +1 @@
+h2gis

h2gis-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

h2gis-0.0.1/setup.py

@@ -0,0 +1,27 @@
+from setuptools import find_packages, setup
+
+setup(
+    name='h2gis',
+    version='0.0.1',
+    description='A Python library to use an H2GIS database through a native GraalVM bridge.',
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author='Lemap',
+    author_email='you@example.com',  # Optional, but recommended
+    url='https://github.com/yourusername/h2gis',  # Replace with actual URL
+    packages=find_packages(),
+    include_package_data=True,
+    package_data={
+        "h2gis": ["lib/*.so", "lib/*.dll", "lib/*.dylib"],
+        "h2gis.docs": ["*.md"],  # add this if docs is inside the h2gis package
+    },
+    license="LGPL-3.0",
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.7",
+    setup_requires=['pytest-runner'],
+    tests_require=['pytest==4.4.1'],
+)

h2gis-0.0.1/test/test_h2gis.py

@@ -0,0 +1,146 @@
+import unittest
+from unittest.mock import MagicMock, patch
+from h2gis.h2gisconnector import H2gisConnector
+
+
+@patch("h2gis.h2gisconnector.ctypes.CDLL")
+class TestH2gis(unittest.TestCase):
+    def setUp(self):
+        """
+        Set up mock native library with default return values.
+        This is run before each test.
+        """
+        self.mock_lib = MagicMock()
+        self.mock_lib.graal_create_isolate.return_value = 0
+        self.mock_lib.h2gis_connect.return_value = 1234
+        self.mock_lib.h2gis_execute.return_value = 42
+        self.mock_lib.h2gis_fetch_row.side_effect = [b"row1", b"row2", None]
+        self.mock_lib.h2gis_execute_update.return_value = 1
+        self.mock_lib.graal_tear_down_isolate.return_value = 0
+
+    def _create_h2gis(self, mock_cdll):
+        """
+        Helper method to create H2gis instance with mocked native lib.
+
+        @param mock_cdll: patched ctypes.CDLL
+        @return: instance of H2gis
+        """
+        mock_cdll.return_value = self.mock_lib
+        return H2gisConnector(lib_path="fake.so")
+
+    # ------------------------
+    # ✅ SUCCESS TEST CASES
+    # ------------------------
+
+    def test_connect_success(self, mock_cdll):
+        """
+        Test successful connection to database.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connect("/path/to/db")
+        self.assertEqual(h2gis.connection, 1234)
+
+    def test_execute_query_success(self, mock_cdll):
+        """
+        Test successful SELECT query with multiple rows.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        result = h2gis.execute_query("SELECT * FROM my_table")
+        self.assertEqual(result, ["row1", "row2"])
+        self.mock_lib.h2gis_close_query.assert_called_once()
+
+    def test_execute_update_success(self, mock_cdll):
+        """
+        Test successful UPDATE query with 1 row affected.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        affected = h2gis.execute_update("UPDATE my_table SET x = 1")
+        self.assertEqual(affected, 1)
+
+    def test_close_connection_success(self, mock_cdll):
+        """
+        Test closing the connection resets the connection handle.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        h2gis.close()
+        self.assertEqual(h2gis.connection, 0)
+        self.mock_lib.h2gis_close_connection.assert_called_once()
+
+    # ------------------------
+    # ⚠️ LIMIT TEST CASES
+    # ------------------------
+
+    def test_execute_query_empty_result(self, mock_cdll):
+        """
+        Test SELECT query returning no rows.
+        """
+        self.mock_lib.h2gis_fetch_row.side_effect = [None]
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        result = h2gis.execute_query("SELECT * FROM empty_table")
+        self.assertEqual(result, [])
+
+    def test_execute_update_zero_affected(self, mock_cdll):
+        """
+        Test UPDATE query with 0 rows affected.
+        """
+        self.mock_lib.h2gis_execute_update.return_value = 0
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        affected = h2gis.execute_update("DELETE FROM my_table WHERE 1=0")
+        self.assertEqual(affected, 0)
+
+    def test_close_when_not_connected(self, mock_cdll):
+        """
+        Test close() does nothing if already disconnected.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 0
+        h2gis.close()
+        self.mock_lib.h2gis_close_connection.assert_not_called()
+
+    def test_del_implicit_cleanup(self, mock_cdll):
+        """
+        Test that __del__ triggers close and cleanup.
+        """
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        del h2gis  # __del__ should be called without exception
+
+    # ------------------------
+    # ❌ ERROR TEST CASES
+    # ------------------------
+
+    def test_connect_failure(self, mock_cdll):
+        """
+        Test exception when connection fails (native returns 0).
+        """
+        self.mock_lib.h2gis_connect.return_value = 0
+        h2gis = self._create_h2gis(mock_cdll)
+        with self.assertRaises(RuntimeError) as ctx:
+            h2gis.connect("/bad/path")
+        self.assertIn("Failed to connect", str(ctx.exception))
+
+    def test_execute_query_failure(self, mock_cdll):
+        """
+        Test exception if query execution fails (native returns 0).
+        """
+        self.mock_lib.h2gis_execute.return_value = 0
+        h2gis = self._create_h2gis(mock_cdll)
+        h2gis.connection = 1234
+        with self.assertRaises(RuntimeError) as ctx:
+            h2gis.execute_query("SELECT * FROM bad_table")
+        self.assertIn("Query execution failed", str(ctx.exception))
+
+    def test_graal_create_isolate_failure(self, mock_cdll):
+        """
+        Test exception if GraalVM isolate creation fails.
+        """
+        self.mock_lib.graal_create_isolate.return_value = 1
+        mock_cdll.return_value = self.mock_lib
+        with self.assertRaises(RuntimeError) as ctx:
+            H2gisConnector(lib_path="fake.so")
+        self.assertIn("Failed to create GraalVM isolate", str(ctx.exception))