Improve docs related to EWKB and SRID

RELEASE.rst

@@ -4,7 +4,7 @@ Release
 This file provides the steps for releasing a new version of GeoAlchemy 2.
 
 Add a new section to CHANGES.txt, change the version number in ``setup.py`` and
-``docs/conf.py``, then create a PR with that. Proceed when the PR is merged.
+``docs/conf.py``, then create a PR with that. Proceed when the PR is merged.
 
 Make sure Travis is all green: https://travis-ci.org/geoalchemy/geoalchemy2.
 

doc/spatialite_tutorial.rst

@@ -10,7 +10,7 @@ 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
+Just like when using PostGIS connecting to a SpatiaLite database requires an ``Engine``. This is how
 you create one for SpatiaLite::
 
     >>> from sqlalchemy import create_engine
@@ -100,7 +100,7 @@ There's nothing specific to SpatiaLite here.
 Create a Session
 ----------------
 
-When using the SQLAlchemy ORM the ORM interacts with the database through 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)

geoalchemy2/elements.py

@@ -130,40 +130,40 @@ class WKBElement(_SpatialElement):
     type. In most cases you won't need to create ``WKBElement`` instances
     yourself.
 
+    If ``extended`` is ``True`` and ``srid`` is ``-1`` at construction time
+    then the SRID will be read from the EWKB data.
+
     Note: you can create ``WKBElement`` objects from Shapely geometries
     using the :func:`geoalchemy2.shape.from_shape` function.
-
-    Extended WKB automatically parse unknown SRID.
-    Warning: unicode data are assumed to be hexadecimal value.
-
-    WKB struct {
-        byte    byteOrder;
-        uint32  wkbType;
-        uint32  SRID;
-        struct  geometry;
-    }
-
-    byteOrder enum {
-        WKB_XDR = 0,  // Most Significant Byte First
-        WKB_NDR = 1,  // Least Significant Byte First
-    }
-
     """
 
     geom_from = 'ST_GeomFromWKB'
     geom_from_extended_version = 'ST_GeomFromEWKB'
 
     def __init__(self, data, srid=-1, extended=False):
-        if extended and srid == -1:  # unpack srid from WKB struct
-            if isinstance(data, str_):  # unicode data assumed to be hex val
+        if extended and srid == -1:
+            # read srid from the EWKB
+            #
+            # WKB struct {
+            #    byte    byteOrder;
+            #    uint32  wkbType;
+            #    uint32  SRID;
+            #    struct  geometry;
+            # }
+            # byteOrder enum {
+            #     WKB_XDR = 0,  // Most Significant Byte First
+            #     WKB_NDR = 1,  // Least Significant Byte First
+            # }
+            if isinstance(data, str_):
+                # SpatiaLite case
+                # assume that the string is an hex value
                 header = binascii.unhexlify(data[:18])
             else:
                 header = data[:9]
             if not PY3:
                 header = bytearray(header)
             byte_order, srid = header[0], header[5:]
             srid = struct.unpack('<I' if byte_order else '>I', srid)[0]
-
         _SpatialElement.__init__(self, data, srid, extended)
 
     @property
@@ -172,6 +172,7 @@ def desc(self):
         This element's description string.
         """
         if isinstance(self.data, str_):
+            # SpatiaLite case
             return self.data
         desc = binascii.hexlify(self.data)
         if PY3:

geoalchemy2/types.py

@@ -195,6 +195,11 @@ class Geometry(_GISType):
     See :class:`geoalchemy2.types._GISType` for the list of arguments that can
     be passed to the constructor.
 
+    If ``srid`` is set then the ``WKBElement` objects resulting from queries will
+    have that SRID, and, when constructing the ``WKBElement`` objects, the SRID
+    won't be read from the data returned by the database. If ``srid`` is not set
+    (meaning it's ``-1``) then the SRID set in ``WKBElement` objects will be read
+    from the data returned by the database.
     """
 
     name = 'geometry'