From 8ffe88d6550fceb3dfebeda5eebd0f44c60636f2 Mon Sep 17 00:00:00 2001 From: Adrien Berchet Date: Sat, 5 Mar 2022 20:52:55 +0100 Subject: [PATCH] Improve doc formatting (#369) --- doc/alembic.rst | 110 +++++++++++++-------------- doc/conf.py | 7 +- doc/elements.rst | 14 ++++ geoalchemy2/alembic_helpers.py | 13 ++-- geoalchemy2/elements.py | 30 +++----- geoalchemy2/exc.py | 9 +-- geoalchemy2/functions.py | 15 ++-- geoalchemy2/shape.py | 44 +++++------ geoalchemy2/types.py | 135 ++++++++++++++------------------- requirements-doc.txt | 1 + 10 files changed, 183 insertions(+), 195 deletions(-) diff --git a/doc/alembic.rst b/doc/alembic.rst index ed435424..1850accc 100644 --- a/doc/alembic.rst +++ b/doc/alembic.rst @@ -215,66 +215,66 @@ columns in a SQLite database, the ``env.py`` file should look like the following .. code-block:: python -from alembic.autogenerate import rewriter - -writer = rewriter.Rewriter() - - -@writer.rewrites(ops.AddColumnOp) -def add_geo_column(context, revision, op): -"""This function replaces the default AddColumnOp by a geospatial-specific one.""" - col_type = op.column.type - if isinstance(col_type, TypeDecorator): - dialect = context.bind().dialect - col_type = col_type.load_dialect_impl(dialect) - if isinstance(col_type, (Geometry, Geography, Raster)): - new_op = AddGeospatialColumn(op.table_name, op.column, op.schema) - else: - new_op = op - return new_op - - -@writer.rewrites(ops.DropColumnOp) -def drop_geo_column(context, revision, op): -"""This function replaces the default DropColumnOp by a geospatial-specific one.""" - col_type = op.to_column().type - if isinstance(col_type, TypeDecorator): - dialect = context.bind.dialect - col_type = col_type.load_dialect_impl(dialect) - if isinstance(col_type, (Geometry, Geography, Raster)): - new_op = DropGeospatialColumn(op.table_name, op.column_name, op.schema) - else: - new_op = op - return new_op - - -def load_spatialite(dbapi_conn, connection_record): - """Load SpatiaLite extension in SQLite DB.""" - dbapi_conn.enable_load_extension(True) - dbapi_conn.load_extension(os.environ['SPATIALITE_LIBRARY_PATH']) - dbapi_conn.enable_load_extension(False) - dbapi_conn.execute('SELECT InitSpatialMetaData()') - - -def run_migrations_offline(): - # ... - context.configure( - # ... - process_revision_directives=writer, - ) - # ... + from alembic.autogenerate import rewriter + + writer = rewriter.Rewriter() + + + @writer.rewrites(ops.AddColumnOp) + def add_geo_column(context, revision, op): + """This function replaces the default AddColumnOp by a geospatial-specific one.""" + col_type = op.column.type + if isinstance(col_type, TypeDecorator): + dialect = context.bind().dialect + col_type = col_type.load_dialect_impl(dialect) + if isinstance(col_type, (Geometry, Geography, Raster)): + new_op = AddGeospatialColumn(op.table_name, op.column, op.schema) + else: + new_op = op + return new_op + + + @writer.rewrites(ops.DropColumnOp) + def drop_geo_column(context, revision, op): + """This function replaces the default DropColumnOp by a geospatial-specific one.""" + col_type = op.to_column().type + if isinstance(col_type, TypeDecorator): + dialect = context.bind.dialect + col_type = col_type.load_dialect_impl(dialect) + if isinstance(col_type, (Geometry, Geography, Raster)): + new_op = DropGeospatialColumn(op.table_name, op.column_name, op.schema) + else: + new_op = op + return new_op + + + def load_spatialite(dbapi_conn, connection_record): + """Load SpatiaLite extension in SQLite DB.""" + dbapi_conn.enable_load_extension(True) + dbapi_conn.load_extension(os.environ['SPATIALITE_LIBRARY_PATH']) + dbapi_conn.enable_load_extension(False) + dbapi_conn.execute('SELECT InitSpatialMetaData()') -def run_migrations_online(): - # ... - if connectable.dialect.name == "sqlite": - # Load the SpatiaLite extension when the engine connects to the DB - listen(connectable, 'connect', load_spatialite) - - with connectable.connect() as connection: + def run_migrations_offline(): # ... context.configure( # ... process_revision_directives=writer, ) # ... + + + def run_migrations_online(): + # ... + if connectable.dialect.name == "sqlite": + # Load the SpatiaLite extension when the engine connects to the DB + listen(connectable, 'connect', load_spatialite) + + with connectable.connect() as connection: + # ... + context.configure( + # ... + process_revision_directives=writer, + ) + # ... diff --git a/doc/conf.py b/doc/conf.py index 59571c22..7e0ddc05 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -27,7 +27,12 @@ # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. -extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode', 'sphinx_gallery.gen_gallery'] +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', + 'sphinx.ext.viewcode', + 'sphinx_gallery.gen_gallery', +] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] diff --git a/doc/elements.rst b/doc/elements.rst index 80504bfa..1bdd47ff 100644 --- a/doc/elements.rst +++ b/doc/elements.rst @@ -3,6 +3,16 @@ Elements ======== +.. autoclass:: geoalchemy2.elements.HasFunction + :members: + :undoc-members: + :show-inheritance: + +.. autoclass:: geoalchemy2.elements._SpatialElement + :members: + :undoc-members: + :show-inheritance: + .. autoclass:: geoalchemy2.elements.WKTElement :members: :undoc-members: @@ -16,3 +26,7 @@ Elements .. autoclass:: geoalchemy2.elements.RasterElement :members: :show-inheritance: + +.. autoclass:: geoalchemy2.elements.CompositeElement + :members: + :show-inheritance: diff --git a/geoalchemy2/alembic_helpers.py b/geoalchemy2/alembic_helpers.py index c36687d2..38a73a2a 100644 --- a/geoalchemy2/alembic_helpers.py +++ b/geoalchemy2/alembic_helpers.py @@ -88,8 +88,8 @@ def reverse(self): def add_geospatial_column(operations, operation): """Handle the actual column addition according to the dialect backend. - Parameters: - operations: Operations object from alembic base, defining high level migration operations + Args: + operations: Operations object from alembic base, defining high level migration operations. operation: AddGeospatialColumn call, with attributes for table_name, column_name, column_type, and optional keywords. """ @@ -125,9 +125,12 @@ def add_geospatial_column(operations, operation): @Operations.implementation_for(DropGeospatialColumn) def drop_geospatial_column(operations, operation): - """ - Handles the actual column removal by checking for the dialect backend and issuing proper - commands. + """Handle the actual column removal according to the dialect backend. + + Args: + operations: Operations object from alembic base, defining high level migration operations. + operation: AddGeospatialColumn call, with attributes for table_name, column_name, + column_type, and optional keywords. """ table_name = operation.table_name diff --git a/geoalchemy2/elements.py b/geoalchemy2/elements.py index 8e45922c..fe5829dd 100644 --- a/geoalchemy2/elements.py +++ b/geoalchemy2/elements.py @@ -19,28 +19,20 @@ class HasFunction(object): + """Base class used as a marker to know if a given element has a 'geom_from' function.""" pass class _SpatialElement(HasFunction): - """ - The base class for :class:`geoalchemy2.elements.WKTElement` and - :class:`geoalchemy2.elements.WKBElement`. - - The first argument passed to the constructor is the data wrapped - by the ``_SpatialElement` object being constructed. - - Additional arguments: - - ``srid`` + """The base class for public spatial elements. - An integer representing the spatial reference system. E.g. 4326. - Default value is -1, which means no/unknown reference system. - - ``extended`` - - A boolean indicating whether the extended format (EWKT or EWKB) - is used. Default is ``False``. + Args: + data: The first argument passed to the constructor is the data wrapped + by the ``_SpatialElement`` object being constructed. + srid: An integer representing the spatial reference system. E.g. ``4326``. + Default value is ``-1``, which means no/unknown reference system. + extended: A boolean indicating whether the extended format (EWKT or EWKB) + is used. Default is ``False``. """ @@ -249,9 +241,7 @@ def _data_from_desc(desc): class CompositeElement(FunctionElement): - """ - Instances of this class wrap a Postgres composite type. - """ + """Instances of this class wrap a Postgres composite type.""" inherit_cache = False diff --git a/geoalchemy2/exc.py b/geoalchemy2/exc.py index a6bb9830..ff0b1ce6 100644 --- a/geoalchemy2/exc.py +++ b/geoalchemy2/exc.py @@ -1,12 +1,9 @@ -""" Exceptions used with GeoAlchemy2. -""" +"""Exceptions used with GeoAlchemy2.""" class GeoAlchemyError(Exception): - """ Generic error class. """ + """Generic error class.""" class ArgumentError(GeoAlchemyError): - """ Raised when an invalid or conflicting function argument is - supplied. - """ + """Raised when an invalid or conflicting function argument is supplied.""" diff --git a/geoalchemy2/functions.py b/geoalchemy2/functions.py index 0903cf71..5d41612e 100644 --- a/geoalchemy2/functions.py +++ b/geoalchemy2/functions.py @@ -289,13 +289,14 @@ def _compile_sqlite(element, compiler, **kw): def register_sqlite_mapping(mapping): """Register compilation mappings for the given functions. - ``mapping`` should have the following form:: - - { - "function_name_1": "sqlite_function_name_1", - "function_name_2": "sqlite_function_name_2", - ... - } + Args: + mapping: Should have the following form:: + + { + "function_name_1": "sqlite_function_name_1", + "function_name_2": "sqlite_function_name_2", + ... + } """ for cls, fn in mapping.items(): _compiles_default(cls) diff --git a/geoalchemy2/shape.py b/geoalchemy2/shape.py index 48d9ac1a..a3575894 100644 --- a/geoalchemy2/shape.py +++ b/geoalchemy2/shape.py @@ -24,18 +24,17 @@ def dumps(ob, hex=False, srid=None, **kw): """Dump a WKB representation of a geometry to a byte string, or a hex-encoded string if ``hex=True``. - Parameters - ---------- - ob : geometry - The geometry to export to well-known binary (WKB) representation - hex : bool - If true, export the WKB as a hexadecimal string. The default is to - return a binary string/bytes object. - srid : int - Spatial reference system ID to include in the output. The default - value means no SRID is included. - **kw : kwargs - See available keyword output settings in ``shapely.geos.WKBWriter``. + Args: + ob (geometry): + The geometry to export to well-known binary (WKB) representation + hex (bool): + If true, export the WKB as a hexadecimal string. The default is to + return a binary string/bytes object. + srid (int): + Spatial reference system ID to include in the output. The default + value means no SRID is included. + Keyword args: + kwargs: See available keyword output settings in ``shapely.geos.WKBWriter``. """ if srid is not None: # clone the object and set the SRID before dumping @@ -58,6 +57,9 @@ def to_shape(element): Function to convert a :class:`geoalchemy2.types.SpatialElement` to a Shapely geometry. + Args: + element: The element to convert into a ``Shapely`` object. + Example:: lake = Session.query(Lake).get(1) @@ -80,17 +82,13 @@ def from_shape(shape, srid=-1, extended=False): Function to convert a Shapely geometry to a :class:`geoalchemy2.types.WKBElement`. - Additional arguments: - - ``srid`` - - An integer representing the spatial reference system. E.g. 4326. - Default value is -1, which means no/unknown reference system. - - ``extended`` - - A boolean to switch between WKB and EWKB. - Default value is False. + Args: + srid: + An integer representing the spatial reference system. E.g. ``4326``. + Default value is ``-1``, which means no/unknown reference system. + extended: + A boolean to switch between WKB and EWKB. + Default value is False. Example:: diff --git a/geoalchemy2/types.py b/geoalchemy2/types.py index 18b15ac4..976be062 100644 --- a/geoalchemy2/types.py +++ b/geoalchemy2/types.py @@ -47,79 +47,61 @@ class _GISType(UserDefinedType): objects. The function returned by ``bind_processor`` converts :class:`geoalchemy2.elements.WKTElement` objects to EWKT strings. - Constructor arguments: - - ``geometry_type`` - - The geometry type. - - Possible values are: - - * ``"GEOMETRY"``, - * ``"POINT"``, - * ``"LINESTRING"``, - * ``"POLYGON"``, - * ``"MULTIPOINT"``, - * ``"MULTILINESTRING"``, - * ``"MULTIPOLYGON"``, - * ``"GEOMETRYCOLLECTION"``, - * ``"CURVE"``, - * ``None``. - - The latter is actually not supported with - :class:`geoalchemy2.types.Geography`. - - When set to ``None`` then no "geometry type" constraints will be - attached to the geometry type declaration. Using ``None`` here - is not compatible with setting ``management`` to ``True``. - - Default is ``"GEOMETRY"``. - - ``srid`` - - The SRID for this column. E.g. 4326. Default is ``-1``. - - ``dimension`` - - The dimension of the geometry. Default is ``2``. - - With ``management`` set to ``True``, that is when ``AddGeometryColumn`` is used - to add the geometry column, there are two constraints: - - * The ``geometry_type`` must not end with ``"ZM"``. This is due to PostGIS' - ``AddGeometryColumn`` failing with ZM geometry types. Instead the "simple" - geometry type (e.g. POINT rather POINTZM) should be used with ``dimension`` - set to ``4``. - * When the ``geometry_type`` ends with ``"Z"`` or ``"M"`` then ``dimension`` - must be set to ``3``. - - With ``management`` set to ``False`` (the default) ``dimension`` is not - taken into account, and the actual dimension is fully defined with the - ``geometry_type``. - - ``spatial_index`` - - Indicate if a spatial index should be created. Default is ``True``. - - ``use_N_D_index`` - Use the N-D index instead of the standard 2-D index. - - ``management`` - - Indicate if the ``AddGeometryColumn`` and ``DropGeometryColumn`` - managements functions should be called when adding and dropping the - geometry column. Should be set to ``True`` for PostGIS 1.x and SQLite. Default is - ``False``. Note that this option has no effect for - :class:`geoalchemy2.types.Geography`. - - ``use_typmod`` - - By default PostgreSQL type modifiers are used to create the geometry - column. To use check constraints instead set ``use_typmod`` to - ``False``. By default this option is not included in the call to - ``AddGeometryColumn``. Note that this option is only taken - into account if ``management`` is set to ``True`` and is only available - for PostGIS 2.x. + Args: + geometry_type: The geometry type. + + Possible values are: + + * ``"GEOMETRY"``, + * ``"POINT"``, + * ``"LINESTRING"``, + * ``"POLYGON"``, + * ``"MULTIPOINT"``, + * ``"MULTILINESTRING"``, + * ``"MULTIPOLYGON"``, + * ``"GEOMETRYCOLLECTION"``, + * ``"CURVE"``, + * ``None``. + + The latter is actually not supported with + :class:`geoalchemy2.types.Geography`. + + When set to ``None`` then no "geometry type" constraints will be + attached to the geometry type declaration. Using ``None`` here + is not compatible with setting ``management`` to ``True``. + + Default is ``"GEOMETRY"``. + + srid: The SRID for this column. E.g. 4326. Default is ``-1``. + dimension: The dimension of the geometry. Default is ``2``. + + With ``management`` set to ``True``, that is when ``AddGeometryColumn`` is used + to add the geometry column, there are two constraints: + + * The ``geometry_type`` must not end with ``"ZM"``. This is due to PostGIS' + ``AddGeometryColumn`` failing with ZM geometry types. Instead the "simple" + geometry type (e.g. POINT rather POINTZM) should be used with ``dimension`` + set to ``4``. + * When the ``geometry_type`` ends with ``"Z"`` or ``"M"`` then ``dimension`` + must be set to ``3``. + + With ``management`` set to ``False`` (the default) ``dimension`` is not + taken into account, and the actual dimension is fully defined with the + ``geometry_type``. + + spatial_index: Indicate if a spatial index should be created. Default is ``True``. + use_N_D_index: Use the N-D index instead of the standard 2-D index. + management: Indicate if the ``AddGeometryColumn`` and ``DropGeometryColumn`` + managements functions should be called when adding and dropping the + geometry column. Should be set to ``True`` for PostGIS 1.x and SQLite. Default is + ``False``. Note that this option has no effect for + :class:`geoalchemy2.types.Geography`. + use_typmod: By default PostgreSQL type modifiers are used to create the geometry + column. To use check constraints instead set ``use_typmod`` to + ``False``. By default this option is not included in the call to + ``AddGeometryColumn``. Note that this option is only taken + into account if ``management`` is set to ``True`` and is only available + for PostGIS 2.x. """ name = None @@ -333,11 +315,8 @@ class Raster(_GISType): received from the database are converted to :class:`geoalchemy2.elements.RasterElement` objects. - Constructor arguments: - - ``spatial_index`` - - Indicate if a spatial index should be created. Default is ``True``. + Args: + spatial_index: Indicate if a spatial index should be created. Default is ``True``. """ diff --git a/requirements-doc.txt b/requirements-doc.txt index 9c23eb3e..72ba5238 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,4 +1,5 @@ # Additional requirements for building the documentation +alembic shapely sphinx sphinx-gallery