GeoAlchemy2 0.15.2__tar.gz → 0.17.0__tar.gz

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/.github/workflows/test_and_publish.yml

@@ -33,7 +33,7 @@ jobs:
           {"pkg_name": "python==3.10.*", "flag": "3.10"},
           {"pkg_name": "python==3.11.*", "flag": "3.11"},
           {"pkg_name": "python==3.12.*", "flag": "3.12"},
-          {"pkg_name": "pypy3.8", "flag": "pypy3.8"},
+          {"pkg_name": "pypy3.10", "flag": "pypy3.10"},
         ]
 
     # The type of runner that the job will run on
@@ -54,28 +54,54 @@ jobs:
           --health-interval 10s
           --health-timeout 5s
           --health-retries 5
+      mysql:
+        image: mysql:latest
+        ports:
+          - 3307:3306
+        env:
+          MYSQL_USER: gis
+          MYSQL_PASSWORD: gis
+          MYSQL_DATABASE: gis
+          MYSQL_ROOT_PASSWORD: gis
+        # Set health checks to wait until MySQL has started
+        options: >-
+          --health-cmd="mysqladmin ping"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=3
+      mariadb:
+        image: mariadb:latest
+        ports:
+          - 3308:3306
+        env:
+          MARIADB_USER: gis
+          MARIADB_PASSWORD: gis
+          MARIADB_DATABASE: gis
+          MARIADB_ROOT_PASSWORD: gis
+        # Set health checks to wait until MariaDB has started
+        options: >-
+          --health-cmd="healthcheck.sh --connect --innodb_initialized"
+          --health-interval=10s
+          --health-timeout=5s
+          --health-retries=3
+
 
     steps:
 
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
     - uses: actions/checkout@v4
 
-    # Setup Conda for Python and Pypy
-    - name: Install Conda environment with Micromamba
-      uses: mamba-org/setup-micromamba@v1
+    # Setup Python
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
       with:
-        environment-name: test_${{ matrix.python-version.flag }}
-        cache-environment: true
-        create-args: >-
-          ${{ matrix.python-version.pkg_name }}
-          libgdal
-          libspatialite==5.0.1
-          pyproj
-        condarc: |
-          channels:
-            - conda-forge
-            - defaults
-          channel_priority: strict
+        python-version: ${{ matrix.python-version.flag }}
+
+    # Install MariaDB
+    - name: Install MariaDB and SpatiaLite
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y mariadb-server mariadb-client libsqlite3-mod-spatialite libgdal-dev gdal-bin rasterio
 
     # Config PostgreSQL
     - name: Configure PostgreSQL
@@ -95,13 +121,17 @@ jobs:
         # Drop PostGIS Topology extension to "gis" database
         psql -h localhost -p 5432 -U gis -d gis -c 'DROP EXTENSION IF EXISTS postgis_topology;'
 
-    # Setup MySQL
-    - name: Set up MySQL
+    # Check MySQL
+    - name: Check MySQL
+      run: |
+        mysql --user=gis --password=gis --host=127.0.0.1 -P 3307 -e "SELECT VERSION();"
+        mysql --user=root --password=gis --host=127.0.0.1 -P 3307 -e "GRANT ALL PRIVILEGES ON *.* TO 'gis'@'%' WITH GRANT OPTION;"
+
+    # Check MariaDB
+    - name: Check MariaDB
       run: |
-        sudo systemctl start mysql
-        sudo mysql --user=root --password=root --host=127.0.0.1 -e "CREATE USER 'gis'@'%' IDENTIFIED BY 'gis';"
-        sudo mysql --user=root --password=root --host=127.0.0.1 -e "GRANT ALL PRIVILEGES ON *.* TO 'gis'@'%' WITH GRANT OPTION;"
-        mysql --user=gis --password=gis -e "CREATE DATABASE gis;"
+        mysql --user=gis --password=gis --host=127.0.0.1 -P 3308 -e "SELECT VERSION();"
+        mysql --user=root --password=gis --host=127.0.0.1 -P 3308 -e "GRANT ALL PRIVILEGES ON *.* TO 'gis'@'%' WITH GRANT OPTION;"
 
     # Check python version
     - name: Display Python version
@@ -114,16 +144,23 @@ jobs:
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip setuptools
-        pip install tox-gh-actions
+        python -m pip install tox-gh-actions
 
     # Run the test suite
     - name: Run the tests
       env:
-        SPATIALITE_LIBRARY_PATH: /home/runner/micromamba/envs/test_${{ matrix.python-version.flag }}/lib/mod_spatialite.so
-        PROJ_LIB: /home/runner/micromamba/envs/test_${{ matrix.python-version.flag }}/share/proj
+        SPATIALITE_LIBRARY_PATH: /usr/lib/x86_64-linux-gnu/mod_spatialite.so
         COVERAGE_FILE: .coverage
-        PYTEST_MYSQL_DB_URL: mysql://gis:gis@127.0.0.1/gis
+        PYTEST_MYSQL_DB_URL: mysql://gis:gis@127.0.0.1:3307/gis
+        PYTEST_MARIADB_DB_URL: mariadb://gis:gis@127.0.0.1:3308/gis
       run: |
+        if [[ ${{ matrix.python-version.flag }} == 'pypy3.10' ]]; then
+          export PYTEST_ADDOPTS=${PYTEST_ADDOPTS}' --ignore=tests/gallery/test_insert_raster.py'
+          export PYTEST_SPATIALITE3_DB_URL="FAILING URL"
+          export PYTEST_SPATIALITE4_DB_URL="FAILING URL"
+        else
+          export PYTEST_ADDOPTS='--require-all-dialects'
+        fi;
         # Run the unit test suite with SQLAlchemy=1.4.* and then with the latest version of SQLAlchemy
         tox -vv
 

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/.pre-commit-config.yaml

@@ -1,8 +1,6 @@
-default_language_version:
-  python: python3.8
 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-case-conflict
@@ -17,7 +15,7 @@ repos:
     hooks:
       - id: isort
   - repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.10.0
     hooks:
       - id: black
   - repo: https://github.com/codespell-project/codespell
@@ -31,7 +29,7 @@ repos:
         additional_dependencies: ["tomli"]
         exclude: "tests"
   - repo: https://github.com/PyCQA/flake8
-    rev: 7.1.0
+    rev: 7.1.1
     hooks:
       - id: flake8
 ci:

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/CHANGES.txt

@@ -1,6 +1,20 @@
 GeoAlchemy 2 Changelog
 ======================
 
+0.17.0
+------
+
+* Perf: Enable cache for all types of GeoAlchemy2 @adrien-berchet (#525)
+* Feat: Add new plugin to automatically attach events based on the engine dialect @adrien-berchet (#525)
+* CI: Disable SQLite for Pypy job @adrien-berchet (#528)
+
+0.16.0
+------
+
+* Test: Add test in test_functional.py for custom Geometry that uses WKT elements @adrien-berchet (#525)
+* Add option to ensure all dialects are properly tested in CI @adrien-berchet (#526)
+* Improve MariaDB support @adrien-berchet (#524)
+
 0.15.2
 ------
 

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0/GeoAlchemy2.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: GeoAlchemy2
-Version: 0.15.2
+Version: 0.17.0
 Summary: Using SQLAlchemy with Spatial Databases
 Home-page: https://geoalchemy-2.readthedocs.io/en/stable/
 Author: Eric Lemoine
@@ -28,6 +28,18 @@ Requires-Dist: SQLAlchemy>=1.4
 Requires-Dist: packaging
 Provides-Extra: shapely
 Requires-Dist: Shapely>=1.7; extra == "shapely"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 ============
 GeoAlchemy 2

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/GeoAlchemy2.egg-info/SOURCES.txt

@@ -29,6 +29,7 @@ tox.ini
 GeoAlchemy2.egg-info/PKG-INFO
 GeoAlchemy2.egg-info/SOURCES.txt
 GeoAlchemy2.egg-info/dependency_links.txt
+GeoAlchemy2.egg-info/entry_points.txt
 GeoAlchemy2.egg-info/not-zip-safe
 GeoAlchemy2.egg-info/requires.txt
 GeoAlchemy2.egg-info/top_level.txt
@@ -39,15 +40,18 @@ doc/alembic_helpers.rst
 doc/changelog.rst
 doc/conf.py
 doc/core_tutorial.rst
+doc/dialect_specific_features.rst
 doc/elements.rst
 doc/index.rst
 doc/make.bat
 doc/migrate.rst
+doc/mysql_mariadb_dialect.rst
 doc/orm_tutorial.rst
+doc/plugin.rst
 doc/shape.rst
 doc/spatial_functions.rst
 doc/spatial_operators.rst
-doc/spatialite_tutorial.rst
+doc/spatialite_dialect.rst
 doc/types.rst
 doc/_static/geoalchemy.png
 doc/_static/geoalchemy.svg
@@ -76,9 +80,11 @@ geoalchemy2/py.typed
 geoalchemy2/shape.py
 geoalchemy2/utils.py
 geoalchemy2/admin/__init__.py
+geoalchemy2/admin/plugin.py
 geoalchemy2/admin/dialects/__init__.py
 geoalchemy2/admin/dialects/common.py
 geoalchemy2/admin/dialects/geopackage.py
+geoalchemy2/admin/dialects/mariadb.py
 geoalchemy2/admin/dialects/mysql.py
 geoalchemy2/admin/dialects/postgresql.py
 geoalchemy2/admin/dialects/sqlite.py
@@ -86,15 +92,20 @@ geoalchemy2/types/__init__.py
 geoalchemy2/types/dialects/__init__.py
 geoalchemy2/types/dialects/common.py
 geoalchemy2/types/dialects/geopackage.py
+geoalchemy2/types/dialects/mariadb.py
 geoalchemy2/types/dialects/mysql.py
 geoalchemy2/types/dialects/postgresql.py
 geoalchemy2/types/dialects/sqlite.py
 test_container/.dockerignore
 test_container/.gitignore
 test_container/Dockerfile
+test_container/Dockerfile_mariadb
 test_container/build.sh
+test_container/build_mariadb.sh
 test_container/run.sh
+test_container/run_mariadb.sh
 test_container/helpers/entrypoint.sh
+test_container/helpers/init_mariadb.sh
 test_container/helpers/init_mysql.sh
 test_container/helpers/init_postgres.sh
 test_container/helpers/install_requirements.sh
@@ -111,6 +122,7 @@ tests/test_functional_postgresql.py
 tests/test_functional_sqlite.py
 tests/test_functions.py
 tests/test_pickle.py
+tests/test_plugin.py
 tests/test_shape.py
 tests/test_types.py
 tests/alembic_config/alembic.ini

geoalchemy2-0.17.0/GeoAlchemy2.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[sqlalchemy.plugins]
+geoalchemy2 = geoalchemy2.admin.plugin:GeoEngine

{geoalchemy2-0.15.2/GeoAlchemy2.egg-info → geoalchemy2-0.17.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: GeoAlchemy2
-Version: 0.15.2
+Version: 0.17.0
 Summary: Using SQLAlchemy with Spatial Databases
 Home-page: https://geoalchemy-2.readthedocs.io/en/stable/
 Author: Eric Lemoine
@@ -28,6 +28,18 @@ Requires-Dist: SQLAlchemy>=1.4
 Requires-Dist: packaging
 Provides-Extra: shapely
 Requires-Dist: Shapely>=1.7; extra == "shapely"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 ============
 GeoAlchemy 2

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/doc/admin.rst

@@ -25,16 +25,21 @@ PostgreSQL-specific objects
    :private-members:
    :show-inheritance:
 
-MySQL-specific objects
----------------------------
+MySQL/MariadDB-specific objects
+-------------------------------
 
 .. automodule:: geoalchemy2.admin.dialects.mysql
    :members:
    :private-members:
    :show-inheritance:
 
+.. automodule:: geoalchemy2.admin.dialects.mariadb
+   :members:
+   :private-members:
+   :show-inheritance:
+
 SQLite-specific objects
----------------------------
+-----------------------
 
 .. automodule:: geoalchemy2.admin.dialects.sqlite
    :members:

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/doc/core_tutorial.rst

@@ -21,7 +21,11 @@ For this tutorial we will use a PostGIS 2 database. To connect we use
 SQLAlchemy's ``create_engine()`` function::
 
     >>> from sqlalchemy import create_engine
-    >>> engine = create_engine('postgresql://gis:gis@localhost/gis', echo=True)
+    >>> engine = create_engine(
+    ...     'postgresql://gis:gis@localhost/gis',
+    ...     echo=True,
+    ...     plugins=["geoalchemy2"],
+    ... )
 
 In this example the name of the database, the database user, and the database
 password, is ``gis``.
@@ -30,6 +34,11 @@ The ``echo`` flag is a shortcut to setting up SQLAlchemy logging, which is
 accomplished via Python's standard logging module. With it is enabled, we'll
 see all the generated SQL produced.
 
+The ``plugins`` argument adds some event listeners to adapt the behavior of
+``GeoAlchemy2`` to the dialect. This is not mandatory but if the plugin is not
+loaded, then the listeners will have to be added to the engine manually (see an
+example in :ref:`spatialite_dialect`).
+
 The return value of ``create_engine`` is an ``Engine`` object, which
 represents the core interface to the database.
 
@@ -84,7 +93,10 @@ be registered into SQLAlchemy, even if it is not used explicitly.
 
     >>> from geoalchemy2 import Geometry  # <= not used but must be imported
     >>> from sqlalchemy import create_engine, MetaData
-    >>> engine = create_engine("postgresql://myuser:mypass@mydb.host.tld/mydbname")
+    >>> engine = create_engine(
+    ...     "postgresql://myuser:mypass@mydb.host.tld/mydbname",
+    ...     plugins=["geoalchemy2"]
+    ... )
     >>> meta = MetaData()
     >>> meta.reflect(bind=engine)
 

geoalchemy2-0.17.0/doc/dialect_specific_features.rst

@@ -0,0 +1,13 @@
+.. _dialect_specific_features:
+
+Dialect specific features
+=========================
+
+Several dialects handle spatial data in different ways. ``GeoAlchemy2`` tries to hide these
+differences but sometimes manual tweaks are needed.
+
+.. toctree::
+   :maxdepth: 1
+
+   mysql_mariadb_dialect
+   spatialite_dialect

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/doc/index.rst

@@ -17,7 +17,7 @@ GeoAlchemy 2 also supports the following dialects:
 * `GeoPackage <http://www.geopackage.org/spec/>`_
 
 Note that using GeoAlchemy 2 with these dialects may require some specific configuration on the
-application side.
+application side. It also may not be optimal for performance.
 
 GeoAlchemy 2 aims to be simpler than its predecessor, `GeoAlchemy
 <https://pypi.python.org/pypi/GeoAlchemy>`_. Simpler to use, and simpler
@@ -87,7 +87,7 @@ system. If you're new to GeoAlchemy 2 start with this.
 
    orm_tutorial
    core_tutorial
-   spatialite_tutorial
+   dialect_specific_features
 
 
 Gallery
@@ -121,6 +121,7 @@ Reference Documentation
    :maxdepth: 1
 
    admin
+   plugin
    types
    elements
    spatial_functions
@@ -133,10 +134,14 @@ Development
 
 The code is available on GitHub: https://github.com/geoalchemy/geoalchemy2.
 
-Contributors:
+Main authors:
 
 * Adrien Berchet (https://github.com/adrien-berchet)
 * Éric Lemoine (https://github.com/elemoine)
+
+Other contributors:
+
+* Caleb Johnson (https://github.com/calebj)
 * Dolf Andringa (https://github.com/dolfandringa)
 * Frédéric Junod, Camptocamp SA (https://github.com/fredj)
 * ijl (https://github.com/ijl)

geoalchemy2-0.17.0/doc/mysql_mariadb_dialect.rst

@@ -0,0 +1,43 @@
+.. _mysql_mariadb_dialect:
+
+MySQL / MariaDB Tutorial
+========================
+
+GeoAlchemy 2's main target is PostGIS. But GeoAlchemy 2 also supports MySQL and MariaDB.
+This tutorial describes how to use GeoAlchemy 2 with these dialects.
+
+.. _mysql_mariadb_connect:
+
+Connect to the DB
+-----------------
+
+Just like when using PostGIS connecting to a MySQL or MariaDB database requires an ``Engine``.
+An engine for these dialects can be created in two ways. Using the plugin provided by
+``GeoAlchemy2`` (see :ref:`plugin` for more details)::
+
+    >>> from sqlalchemy import create_engine
+    >>> engine = create_engine(
+    ...     "mysql://user:password@host:port/dbname",
+    ...     echo=True,
+    ...     plugins=["geoalchemy2"]
+    ... )
+
+The call to ``create_engine`` creates an engine bound to the database given in the URL. After that
+a ``before_cursor_execute`` listener is registered on the engine (see
+:func:`geoalchemy2.admin.dialects.mysql.before_cursor_execute` and
+:func:`geoalchemy2.admin.dialects.mariadb.before_cursor_execute`). The listener is responsible for
+converting the parameters passed to query in the proper format, which is often a necessary operation
+for using these dialects, though it depends on the driver used. If the driver does not require such
+conversion, it is possible to disable this feature with the URL parameter
+``geoalchemy2_before_cursor_execute_mysql_convert`` or
+``geoalchemy2_before_cursor_execute_mariadb_convert``, depending on the dialect used.
+
+
+It is also possible to create a raw engine and attach the listener manually::
+
+    >>> from geoalchemy2.admin.dialects.mysql import before_cursor_execute
+    >>> from sqlalchemy import create_engine
+    >>> from sqlalchemy.event import listen
+    >>>
+    >>> engine = create_engine("mysql://user:password@host:port/dbname", echo=True)
+    >>> listen(engine, "before_cursor_execute", before_cursor_execute)

{geoalchemy2-0.15.2 → geoalchemy2-0.17.0}/doc/orm_tutorial.rst

@@ -20,7 +20,11 @@ For this tutorial we will use a PostGIS 2 database. To connect we use
 SQLAlchemy's ``create_engine()`` function::
 
     >>> from sqlalchemy import create_engine
-    >>> engine = create_engine('postgresql://gis:gis@localhost/gis', echo=True)
+    >>> engine = create_engine(
+    ...     'postgresql://gis:gis@localhost/gis',
+    ...     echo=True,
+    ...     plugins=["geoalchemy2"]
+    ... )
 
 In this example the name of the database, the database user, and the database
 password, is ``gis``.
@@ -29,6 +33,11 @@ The ``echo`` flag is a shortcut to setting up SQLAlchemy logging, which is
 accomplished via Python's standard logging module. With it is enabled, we'll
 see all the generated SQL produced.
 
+The ``plugins`` argument adds some event listeners to adapt the behavior of
+``GeoAlchemy2`` to the dialect. This is not mandatory but if the plugin is not
+loaded, then the listeners will have to be added to the engine manually (see an
+example in :ref:`spatialite_dialect`).
+
 The return value of ``create_engine`` is an ``Engine`` object, which
 represents the core interface to the database.
 
@@ -128,7 +137,9 @@ Add New Objects
 
 To persist our ``Lake`` object, we ``add()`` it to the ``Session``::
 
+    >>> lake = Lake(name="Majeur", geom="POLYGON((0 0,1 0,1 1,0 1,0 0))")
     >>> session.add(lake)
+    >>> session.commit()
 
 At this point the ``lake`` object has been added to the ``Session``, but no SQL
 has been issued to the database. The object is in a *pending* state. To persist
@@ -237,6 +248,9 @@ We can also apply relationship functions to
 ``session.scalar`` allows executing a clause and returning a scalar
 value (a boolean value in this case).
 
+The value ``True`` indicates that the lake "Garde" does intersects the ``LINESTRING(2 1,4 1)``
+geometry. See the SpatiaLite SQL functions reference list for more information.
+
 The GeoAlchemy functions all start with ``ST_``. Operators are also called as
 functions, but the function names don't include the ``ST_`` prefix. As an
 example let's use PostGIS' ``&&`` operator, which allows testing

geoalchemy2-0.17.0/doc/plugin.rst

@@ -0,0 +1,9 @@
+.. _plugin:
+
+Plugin
+======
+
+.. automodule:: geoalchemy2.admin.plugin
+   :members:
+   :private-members:
+   :show-inheritance:

geoalchemy2-0.15.2/doc/spatialite_tutorial.rst → geoalchemy2-0.17.0/doc/spatialite_dialect.rst

@@ -1,4 +1,4 @@
-.. _spatialite_tutorial:
+.. _spatialite_dialect:
 
 SpatiaLite Tutorial
 ===================
@@ -12,8 +12,18 @@ the :ref:`orm_tutorial`, which you may want to read first.
 Connect to the DB
 -----------------
 
-Just like when using PostGIS connecting to a SpatiaLite database requires an ``Engine``. This is how
-you create one for SpatiaLite::
+Just like when using PostGIS connecting to a SpatiaLite database requires an ``Engine``. An engine
+for the SpatiaLite dialect can be created in two ways. Using the plugin provided by
+``GeoAlchemy2`` (see :ref:`plugin` for more details)::
+
+    >>> from sqlalchemy import create_engine
+    >>> engine = create_engine(
+    ...     "sqlite:///gis.db",
+    ...     echo=True,
+    ...     plugins=["geoalchemy2"]
+    ... )
+
+Or by attaching the listeners manually::
 
     >>> from geoalchemy2 import load_spatialite
     >>> from sqlalchemy import create_engine
@@ -70,108 +80,6 @@ From the user point of view this works in the same way as with PostGIS. The diff
 internally the ``RecoverGeometryColumn`` and ``DiscardGeometryColumn`` management functions will be
 used for the creation and removal of the geometry column.
 
-Create the Table in the Database
---------------------------------
-
-We can now create the ``lake`` table in the ``gis.db`` database::
-
-    >>> Lake.__table__.create(engine)
-
-If we wanted to drop the table we'd use::
-
-    >>> Lake.__table__.drop(engine)
-
-There's nothing specific to SpatiaLite here.
-
-Create a Session
-----------------
-
-When using the SQLAlchemy ORM the ORM interacts with the database through a ``Session``.
-
-    >>> from sqlalchemy.orm import sessionmaker
-    >>> Session = sessionmaker(bind=engine)
-    >>> session = Session()
-
-The session is associated with our SpatiaLite ``Engine``. Again, there's nothing
-specific to SpatiaLite here.
-
-Add New Objects
----------------
-
-We can now create and insert new ``Lake`` objects into the database, the same way we'd
-do it using GeoAlchemy 2 with PostGIS.
-
-::
-
-    >>> lake = Lake(name="Majeur", geom="POLYGON((0 0,1 0,1 1,0 1,0 0))")
-    >>> session.add(lake)
-    >>> session.commit()
-
-We can now query the database for ``Majeur``::
-
-    >>> our_lake = session.query(Lake).filter_by(name="Majeur").first()
-    >>> our_lake.name
-    u"Majeur"
-    >>> our_lake.geom
-    <WKBElement at 0x9af594c; "0103000000010000000500000000000000000000000000000000000000000000000000f03f0000000000000000000000000000f03f000000000000f03f0000000000000000000000000000f03f00000000000000000000000000000000">
-    >>> our_lake.id
-    1
-
-Let's add more lakes::
-
-    >>> session.add_all([
-    ...     Lake(name="Garde", geom="POLYGON((1 0,3 0,3 2,1 2,1 0))"),
-    ...     Lake(name="Orta", geom="POLYGON((3 0,6 0,6 3,3 3,3 0))")
-    ... ])
-    >>> session.commit()
-
-Query
------
-
-Let's make a simple, non-spatial, query::
-
-    >>> query = session.query(Lake).order_by(Lake.name)
-    >>> for lake in query:
-    ...     print(lake.name)
-    ...
-    Garde
-    Majeur
-    Orta
-
-Now a spatial query::
-
-    >>> from geolachemy2 import WKTElement
-    >>> query = session.query(Lake).filter(
-    ...             func.ST_Contains(Lake.geom, WKTElement("POINT(4 1)")))
-    ...
-    >>> for lake in query:
-    ...     print(lake.name)
-    ...
-    Orta
-
-Here's another spatial query, using ``ST_Intersects`` this time::
-
-    >>> query = session.query(Lake).filter(
-    ...             Lake.geom.ST_Intersects(WKTElement("LINESTRING(2 1,4 1)")))
-    ...
-    >>> for lake in query:
-    ...     print(lake.name)
-    ...
-    Garde
-    Orta
-
-We can also apply relationship functions to :class:`geoalchemy2.elements.WKBElement`. For example::
-
-    >>> lake = session.query(Lake).filter_by(name="Garde").one()
-    >>> print(session.scalar(lake.geom.ST_Intersects(WKTElement("LINESTRING(2 1,4 1)"))))
-    1
-
-``session.scalar`` allows executing a clause and returning a scalar value (an integer value in this
-case).
-
-The value ``1`` indicates that the lake "Garde" does intersects the ``LINESTRING(2 1,4 1)``
-geometry. See the SpatiaLite SQL functions reference list for more information.
-
 Function mapping
 ----------------
 
@@ -201,7 +109,7 @@ GeoPackage format
 Starting from the version ``4.2`` of Spatialite, it is possible to use GeoPackage files as DB
 containers. GeoAlchemy 2 is able to handle most of the GeoPackage features automatically if the
 GeoPackage dialect is used (i.e. the DB URL starts with ``gpkg:///``) and the SpatiaLite extension
-is loaded. Usually, this extension should be loaded using the ``load_spatialite_gpkg`` listener::
+is loaded. Usually, this extension should be loaded using the the ``GeoAlchemy2`` plugin (see :ref:`connect <spatialite_connect>` section) or by attaching the ``load_spatialite_gpkg`` listener to the engine::
 
     >>> from geoalchemy2 import load_spatialite_gpkg
     >>> from sqlalchemy import create_engine