From 210ad448d16cca4b9af5d4a7d42557eab9df677f Mon Sep 17 00:00:00 2001 From: sethg Date: Thu, 9 Oct 2025 21:41:01 +0200 Subject: [PATCH 1/3] Update docstrings to work with docstub --- swig/include/Operations.i | 31 +- swig/include/python/callback.i | 2 +- .../include/python/docs/gdal_algorithm_docs.i | 54 +- swig/include/python/docs/gdal_band_docs.i | 26 +- swig/include/python/docs/gdal_dataset_docs.i | 119 ++- swig/include/python/docs/gdal_docs.i | 15 +- swig/include/python/docs/gdal_driver_docs.i | 26 +- swig/include/python/docs/gdal_mdm_docs.i | 24 +- .../python/docs/gdal_operations_docs.i | 22 +- swig/include/python/docs/gdal_rat_docs.i | 5 +- swig/include/python/docs/ogr_docs.i | 30 +- swig/include/python/docs/ogr_feature_docs.i | 250 ++--- .../include/python/docs/ogr_featuredef_docs.i | 76 +- swig/include/python/docs/ogr_fielddef_docs.i | 74 +- .../python/docs/ogr_fielddomain_docs.i | 28 +- swig/include/python/docs/ogr_geometry_docs.i | 356 ++++--- swig/include/python/docs/ogr_layer_docs.i | 350 ++++--- swig/include/python/docs/osr_docs.i | 1 - .../python/docs/osr_spatialreference_docs.i | 17 +- swig/include/python/gdal_python.i | 958 +++++++++--------- swig/include/python/ogr_python.i | 89 +- swig/include/python/typemaps_python.i | 16 +- swig/python/pyproject.toml | 13 + 23 files changed, 1320 insertions(+), 1262 deletions(-) diff --git a/swig/include/Operations.i b/swig/include/Operations.i index 2217789426ab..ad31c0bf672e 100644 --- a/swig/include/Operations.i +++ b/swig/include/Operations.i @@ -992,30 +992,31 @@ def SuggestedWarpOutput(*args): Parameters ---------- - src: Dataset + src : Dataset Source dataset - transformer: Transformer + transformer : Transformer The return value of gdal.Transformer(src, None, options) (exclusive with below options parameter) - options: list[str] + options : list[str] List of strings that are the transforming options accepted by :cpp:func:`GDALCreateGenImgProjTransformer2` (e.g ``DST_SRS``) (exclusive with above transformer parameter) Returns ------- - - A SuggestedWarpOutputRes class instance with the following members: - - width: number of pixels in width of the output dataset - - height: number of pixels in height of the output dataset - - xmin: minimum value of the georeferenced X coordinates - - ymin: maximum value of the georeferenced Y coordinates - - xmax: minimum value of the georeferenced X coordinates - - ymax: maximum value of the georeferenced Y coordinates - - geotransform: affine geotransformation matrix (6 values) - - Example - ------- + SuggestedWarpOutputRes + An instance of the SuggestedWarpOutputRes class with the following members: + + - ``width`` (int): Number of pixels in width of the output dataset. + - ``height`` (int): Number of pixels in height of the output dataset. + - ``xmin`` (float): Minimum value of the georeferenced X coordinates. + - ``ymin`` (float): Minimum value of the georeferenced Y coordinates. + - ``xmax`` (float): Maximum value of the georeferenced X coordinates. + - ``ymax`` (float): Maximum value of the georeferenced Y coordinates. + - ``geotransform`` (tuple of 6 floats): Affine geotransformation matrix. + + Examples + -------- >>> ds = gdal.Open("byte.tif") >>> res = gdal.SuggestedWarpOutput(ds, ["DST_SRS=EPSG:4326"]) diff --git a/swig/include/python/callback.i b/swig/include/python/callback.i index 4d3ace3e527b..c6f9d1530cc0 100644 --- a/swig/include/python/callback.i +++ b/swig/include/python/callback.i @@ -43,7 +43,7 @@ PyProgressProxy( double dfComplete, const char *pszMessage, void *pData ) psArgs = Py_BuildValue("(dsO)", dfComplete, pszMessage, Py_None ); else psArgs = Py_BuildValue("(dsO)", dfComplete, pszMessage, - psInfo->psPyCallbackData ); + psInfo->psPyCallbackData ); psResult = PyObject_CallObject( psInfo->psPyCallback, psArgs); Py_XDECREF(psArgs); diff --git a/swig/include/python/docs/gdal_algorithm_docs.i b/swig/include/python/docs/gdal_algorithm_docs.i index 6a71dee7f98a..273495e86d23 100644 --- a/swig/include/python/docs/gdal_algorithm_docs.i +++ b/swig/include/python/docs/gdal_algorithm_docs.i @@ -12,7 +12,7 @@ Close any dataset arguments or outputs of the algorithm. Returns ------- -boolean +bool }; @@ -25,8 +25,8 @@ Returns ------- Algorithm -Example -------- +Examples +-------- >>> alg = gdal.GetGlobalAlgorithmRegistry().InstantiateAlg("raster") >>> alg.ParseCommandLineArguments(["convert" ,"--input", "byte.tif", "--output", "/tmp/byte.png"]) True @@ -47,8 +47,8 @@ Returns ------- AlgorithmArg -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster", "polygonize") >>> arg = alg.GetArg("connect-diagonal-pixels") >>> arg.GetDescription() @@ -64,8 +64,8 @@ Returns ------- list -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster", "convert") >>> sorted(alg.GetArgNames()) ['append', 'config', 'creation-option', ..., 'progress', 'quiet'] @@ -87,8 +87,8 @@ Returns ------- str -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster", "convert") >>> alg.GetDescription() 'Convert a raster dataset.' @@ -103,8 +103,8 @@ Returns ------- str -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster", "convert") >>> alg.GetHelpFullURL() 'https://gdal.org/programs/gdal_raster_convert.html' @@ -125,8 +125,8 @@ Returns ------- str -Example -------- +Examples +-------- >>> gdal.Algorithm("raster", "info").GetName() 'info' @@ -140,8 +140,8 @@ Returns ------- list or None -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster") >>> alg.GetSubAlgorithmNames() ['as-features', 'aspect', ..., 'update', 'viewshed'] @@ -156,8 +156,8 @@ Returns ------- str -Example -------- +Examples +-------- >>> import json >>> import pprint >>> usage = json.loads(gdal.Algorithm("vector", "info").GetUsageAsJSON()) @@ -283,8 +283,8 @@ Returns ------- bool -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster") >>> alg.HasSubAlgorithms() True @@ -302,8 +302,8 @@ Returns ------- Algorithm or None -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("raster") >>> alg.InstantiateSubAlgorithm("convert") > @@ -325,8 +325,8 @@ Returns bool Whether the arguments were successfully parsed -Example -------- +Examples +-------- >>> alg = gdal.Algorithm("vector", "info") >>> alg.ParseCommandLineArguments(['poly.shp', '--format', 'text']) True @@ -341,7 +341,7 @@ Parameters ---------- args : list List of command line arguments -callback : function +callback : callable, optional Optional progress callback function callback_data Optional value to be provided as final argument to callback function @@ -431,8 +431,8 @@ Returns ------- str -Example -------- +Examples +-------- >>> gdal.AlgorithmArgTypeName(gdal.GAAT_REAL) 'real' @@ -448,7 +448,7 @@ type : int Returns ------- -boolean +bool Examples -------- diff --git a/swig/include/python/docs/gdal_band_docs.i b/swig/include/python/docs/gdal_band_docs.i index 001488bcba02..c3905f1775d1 100644 --- a/swig/include/python/docs/gdal_band_docs.i +++ b/swig/include/python/docs/gdal_band_docs.i @@ -69,7 +69,7 @@ nFlags : int Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -80,7 +80,7 @@ Remove the nodata value for this band. Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -99,7 +99,7 @@ imag_fill : float, default = 0.0 Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -273,9 +273,9 @@ include_out_of_range : bool, default=False if ``True``, add out-of-range values into the first and last buckets approx_ok : bool, default=True if ``True``, compute an approximate histogram by using subsampling or overviews -callback : function, optional +callback : callable, optional A progress callback function -callback_data: optional +callback_data : any, optional Optional data to be passed to callback function Returns @@ -549,7 +549,7 @@ papszCategoryNames : list Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -565,7 +565,7 @@ val : int Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -580,7 +580,7 @@ arg : ColorTable Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -600,7 +600,7 @@ buckets_in : list Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. See Also @@ -619,7 +619,7 @@ val : float Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. See Also @@ -650,7 +650,7 @@ val : float Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. See Also @@ -672,7 +672,7 @@ stdev : float Returns ------- -int: +int :py:const:`CE_None` on apparent success or :py:const:`CE_Failure` on failure. This method cannot detect whether metadata will be properly saved and so may return :py:const:`gdal.`CE_None` even if the statistics will never be @@ -699,7 +699,7 @@ val : str Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; diff --git a/swig/include/python/docs/gdal_dataset_docs.i b/swig/include/python/docs/gdal_dataset_docs.i index e308807f0c1d..84052c95e3c9 100644 --- a/swig/include/python/docs/gdal_dataset_docs.i +++ b/swig/include/python/docs/gdal_dataset_docs.i @@ -16,7 +16,10 @@ Not implemented by all drivers. See :cpp:func:`GDALDataset::AbortSQL`. Returns ------- -:py:const:`ogr.OGRERR_NONE` on success or :py:const:`ogr.OGRERR_UNSUPPORTED_OPERATION` if AbortSQL is not supported for this dataset. +int + :py:const:`ogr.OGRERR_NONE` on success, or + :py:const:`ogr.OGRERR_UNSUPPORTED_OPERATION` if AbortSQL is not supported + for this dataset. "; @@ -27,15 +30,15 @@ Adds a band to a :py:class:`Dataset`. Not supported by all drivers. Parameters ------------ -datatype: int +---------- +datatype : int the data type of the pixels in the new band -options: dict/list +options : dict or list, optional an optional dict or list of format-specific ``NAME=VALUE`` option strings. Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. Examples @@ -57,12 +60,12 @@ Only a few drivers support this operation. See :cpp:func:`GDALDataset::AddFieldD Parameters ---------- -fieldDomain : ogr.FieldDomain - The field domain to add +fieldDomain : FieldDomain + The field domain to add Returns --------- -bool: +------- +bool ``True`` if the field domain was added, ``False`` in case of error. @@ -81,7 +84,7 @@ relationship : Relationship Returns ------- -bool: +bool ``True`` if the field domain was added, ``False`` in case of error. "; @@ -107,16 +110,18 @@ resampling : str, optional overviewlist : list A list of overview levels (decimation factors) to build, or an empty list to clear existing overviews. -callback : function, optional +callback : callable, optional A progress callback function -callback_data: optional +callback_data : any, optional Optional data to be passed to callback function -options : dict/list, optional +options : dict or list, optional A dict or list of key=value options Returns ------- -:py:const:`CE_Failure` if an error occurs, otherwise :py:const:`CE_None`. +int + :py:const:`CE_Failure` if an error occurs, otherwise + :py:const:`CE_None`. Examples -------- @@ -170,16 +175,17 @@ See :cpp:func:`GDALDataset::CopyLayer`. Parameters ---------- -src_layer : ogr.Layer +src_layer : Layer source layer new_name : str name of the layer to create -options : dict/list +options : dict or list a dict or list of name=value driver-specific creation options Returns ------- -ogr.Layer, or ``None`` if an error occurs +Layer or None + A layer if successful, or ``None`` if an error occurs. "; %feature("docstring") CreateLayer " @@ -188,21 +194,22 @@ Create a new layer in a vector Dataset. Parameters ---------- -name : string +name : str the name for the new layer. This should ideally not match any existing layer on the datasource. -srs : osr.SpatialReference, default=None - the coordinate system to use for the new layer, or ``None`` if - no coordinate system is available. +srs : SpatialReference, optional + The coordinate system to use for the new layer, + or ``None`` if no coordinate system is available. Defaults to ``None``. geom_type : int, default = :py:const:`ogr.wkbUnknown` geometry type for the layer. Use :py:const:`ogr.wkbUnknown` if there are no constraints on the types geometry to be written. -options : dict/list, optional +options : dict or list, optional Driver-specific dict or list of name=value options Returns ------- -ogr.Layer or ``None`` on failure. +Layer or None + The layer object if successful, or ``None`` on failure. Examples @@ -296,9 +303,9 @@ See :cpp:func:`GDALDataset::GetExtent` Parameters ---------- -srs : osr.SpatialReference, default=None +srs : SpatialReference, optional Optional spatial reference in which the bounds should be - returned + returned. Defaults to ``None``. Returns ------- @@ -337,7 +344,7 @@ See :cpp:func:`GDALDataset::GetExtentWGS84LongLat` .. warning:: Check the return order of the bounds. Returns --------- +------- tuple or None tuple of (minlon, maxlon, minlat, maxlat) or None if the extent cannot be determined in WGS84 @@ -362,12 +369,13 @@ Get a field domain from its name. Parameters ---------- -name: str +name : str The name of the field domain Returns ------- -ogr.FieldDomain, or ``None`` if it is not found. +FieldDomain or None + An FieldDomain instance if found, or ``None`` if it is not found. "; %feature("docstring") GetFieldDomainNames " @@ -376,13 +384,14 @@ Get a list of the names of all field domains stored in the dataset. Parameters ---------- -options: dict/list, optional +options : dict or list, optional Driver-specific options determining how attributes should be retrieved. Returns ------- -list, or ``None`` if no field domains are stored in the dataset. +list or None + ``None`` if no field domains are stored in the dataset. "; %feature("docstring") GetFileList " @@ -397,7 +406,7 @@ See :cpp:func:`GDALGetFileList`. Get number of GCPs. See :cpp:func:`GDALGetGCPCount`. Returns --------- +------- int "; @@ -407,8 +416,8 @@ int Return a WKT representation of the GCP spatial reference. Returns --------- -string +------- +str "; @@ -425,7 +434,7 @@ See :cpp:func:`GDALGetGCPSpatialRef` Get the GCPs. See :cpp:func:`GDALGetGCPs`. Returns --------- +------- tuple a tuple of :py:class:`GCP` objects. @@ -442,8 +451,8 @@ index : int Returns ------- -ogr.Layer - +Layer or None + An layer if successful, or ``None`` on error. "; @@ -457,7 +466,8 @@ layer_name : str Returns ------- -ogr.Layer +Layer or None + A layer if successful, or ``None`` on error. "; @@ -484,7 +494,7 @@ See :cpp:func:`GDALDataset::GetNextFeature`. Returns ------- -ogr.Feature +Feature "; @@ -516,14 +526,14 @@ Fetch the affine transformation coefficients. See :cpp:func:`GDALGetGeoTransform`. Parameters ------------ +---------- can_return_null : bool, default=False if ``True``, return ``None`` instead of the default transformation if the transformation for this :py:class:`Dataset` has not been defined. Returns ------- -tuple: +tuple a 6-member tuple representing the transformation coefficients @@ -534,13 +544,13 @@ tuple: Fetch a :py:class:`Band` band from a :py:class:`Dataset`. See :cpp:func:`GDALGetRasterBand`. Parameters ------------ +---------- nBand : int the index of the band to fetch, from 1 to :py:attr:`RasterCount` Returns --------- -Band: +------- +Band the :py:class:`Band`, or ``None`` on error. "; @@ -560,7 +570,7 @@ Get a list of the names of all relationships stored in the dataset. Parameters ---------- -options : dict/list, optional +options : dict or list, optional driver-specific options determining how the relationships should be retrieved "; @@ -581,8 +591,8 @@ Group Fetch the spatial reference for this dataset. Returns --------- -osr.SpatialReference +------- +SpatialReference "; @@ -592,7 +602,7 @@ Returns dataset style table. Returns ------- -ogr.StyleTable +StyleTable "; @@ -670,7 +680,8 @@ argin : tuple Returns ------- -:py:const:`CE_Failure` if an error occurs, otherwise :py:const:`CE_None`. +int + :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -682,12 +693,13 @@ See :cpp:func:`GDALDataset::SetProjection`. Parameters ---------- -prj: +prj : str The projection string in OGC WKT or PROJ.4 format Returns ------- -:py:const:`CE_Failure` if an error occurs, otherwise :py:const:`CE_None`. +int + :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -701,7 +713,8 @@ srs : SpatialReference Returns ------- -:py:const:`CE_Failure` if an error occurs, otherwise :py:const:`CE_None`. +int + :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -711,7 +724,7 @@ Set dataset style table Parameters ---------- -table : ogr.StyleTable +table : StyleTable "; %feature("docstring") StartTransaction " @@ -763,7 +776,7 @@ Requires the :py:const:`ogr.ODsCUpdateFieldDomain` datasset capability. Parameters ---------- -fieldDomain : ogr.FieldDomain +fieldDomain : FieldDomain Updated field domain. Returns diff --git a/swig/include/python/docs/gdal_docs.i b/swig/include/python/docs/gdal_docs.i index 69c7f65ba03f..3ae397f3abc8 100644 --- a/swig/include/python/docs/gdal_docs.i +++ b/swig/include/python/docs/gdal_docs.i @@ -310,7 +310,8 @@ eAccess : int, default = :py:const:`gdal.GA_ReadOnly` Returns ------- -Dataset, or ``None`` on failure +Dataset or None + A dataset if successful, or ``None`` on failure. See Also -------- @@ -334,14 +335,15 @@ flags : int may be combined using the ``|`` operator. See :cpp:func:`GDALOpenEx`. allowed_drivers : list, optional A list of the names of drivers that may attempt to open the dataset. -open_options : dict/list, optional +open_options : dict or list, optional A dict or list of name=value driver-specific opening options. -sibling_files: list, optional +sibling_files : list, optional A list of filenames that are auxiliary to the main filename Returns ------- -Dataset, or ``None`` on failure. +Dataset or None + A dataset if successful, or ``None`` on failure. See Also -------- @@ -365,7 +367,8 @@ eAccess : int, default = :py:const:`gdal.GA_ReadOnly` Returns ------- -Dataset, or ``None`` on failure +Dataset or None + A dataset if successful, or ``None`` on failure. See Also -------- @@ -382,7 +385,7 @@ See :cpp:func:`GDALSetCacheMax`. Parameters ---------- -nBytes: int +nBytes : int Cache size in bytes See Also diff --git a/swig/include/python/docs/gdal_driver_docs.i b/swig/include/python/docs/gdal_driver_docs.i index 84c733381330..2277bb915947 100644 --- a/swig/include/python/docs/gdal_driver_docs.i +++ b/swig/include/python/docs/gdal_driver_docs.i @@ -16,7 +16,7 @@ oldName : str Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -35,9 +35,9 @@ ysize : int Height of created raster in pixels. Set to zero for vector datasets. bands : int, default = 1 Number of bands. Set to zero for vector datasets. -eType : int/NumPy dtype, default = :py:const:`GDT_Byte` +eType : int or numpy.dtype, default = :py:const:`GDT_Byte` Raster data type. Set to :py:const:`GDT_Unknown` for vector datasets. -options : list/dict +options : list or dict List of driver-specific options Returns @@ -80,15 +80,15 @@ Parameters utf8_path : str Path of the dataset to create. src : Dataset - The Dataset being duplicated. + The dataset being duplicated. strict : bool, default=1 Indicates whether the copy must be strictly equivalent or if it may be adapted as needed for the output format. -options : list/dict +options : list or dict List of driver-specific options -callback : function, optional +callback : callable, optional A progress callback function -callback_data: optional +callback_data : any, optional Optional data to be passed to callback function Returns @@ -105,10 +105,10 @@ Parameters ---------- utf8_path : str Path of the dataset to create. -root_group_options : dict/list +root_group_options : list or dict Driver-specific options regarding the creation of the root group. -options : list/dict +options : list or dict List of driver-specific options regarding the creation of the Dataset. @@ -163,7 +163,7 @@ utf8_path : str Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -183,7 +183,7 @@ openOptionName : str Returns ------- -bool: +bool ``True``, if the option is supported by this driver, ``False`` otherwise. Examples @@ -223,7 +223,7 @@ oldName : str Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; @@ -246,7 +246,7 @@ cap : str Returns ------- -bool: +bool ``True`` if the driver supports the capability, ``False`` otherwise. Examples diff --git a/swig/include/python/docs/gdal_mdm_docs.i b/swig/include/python/docs/gdal_mdm_docs.i index 6b28648bd5d8..2bb256b9c345 100644 --- a/swig/include/python/docs/gdal_mdm_docs.i +++ b/swig/include/python/docs/gdal_mdm_docs.i @@ -12,15 +12,15 @@ dimensions : list List of dimensions, ordered from the slowest varying dimension first to the fastest varying dimension last. Might be empty for a scalar array (if supported by driver) -data_type: :py:class:`ExtendedDataType` +data_type : :py:class:`ExtendedDataType` Attribute data type -options: dict/list - an optional dict or list of driver specific ``NAME=VALUE`` option strings. +options : dict or list, optional + dict or list of driver specific ``NAME=VALUE`` option strings. Returns ------- -Attribute: +Attribute the new :py:class:`Attribute` or ``None`` on failure. Examples @@ -48,17 +48,17 @@ name : str Dimension name dim_type : str Dimension type (might be empty, and ignored by drivers) -direction: str +direction : str Dimension direction (might be empty, and ignored by drivers) size : int Number of values indexed by this dimension. Should be > 0 -options: dict/list - an optional dict or list of driver specific ``NAME=VALUE`` option strings. +options : dict or list, optional + dict or list of driver specific ``NAME=VALUE`` option strings. Returns ------- -Dimension: +Dimension the new :py:class:`Dimension` or ``None`` on failure. Examples @@ -94,15 +94,15 @@ dimensions : list List of dimensions, ordered from the slowest varying dimension first to the fastest varying dimension last. Might be empty for a scalar array (if supported by driver) -data_type: :py:class:`ExtendedDataType` +data_type : :py:class:`ExtendedDataType` Array data type -options: dict/list - an optional dict or list of driver specific ``NAME=VALUE`` option strings. +options : dict or list, optional + dict or list of driver specific ``NAME=VALUE`` option strings. Returns ------- -MDArray: +MDArray the new :py:class:`MDArray` or ``None`` on failure. Examples diff --git a/swig/include/python/docs/gdal_operations_docs.i b/swig/include/python/docs/gdal_operations_docs.i index b01976ed5610..ba06715dde97 100644 --- a/swig/include/python/docs/gdal_operations_docs.i +++ b/swig/include/python/docs/gdal_operations_docs.i @@ -31,12 +31,12 @@ maxSearchDist : float the maximum number of pixels to search in all directions to find values to interpolate from. smoothingIterations : int the number of 3x3 smoothing filter passes to run (0 or more) -options : dict/list, optional +options : dict or list, optional A dict or list of name=value options. Available options are described in :cpp:func:`GDALFillNodata`. -callback : function, optional +callback : callable, optional A progress callback function -callback_data: optional +callback_data : any, optional Optional data to be passed to callback function Returns @@ -84,7 +84,7 @@ Both input coordinates must be within the raster coordinate bounds. Parameters ---------- -band : gdal.RasterBand +band : Band The band to read the DEM data from. This must NOT be null. xA : int The X location (raster column) of the first point to check on the raster. @@ -98,15 +98,19 @@ yB : int The Y location (raster row) of the second point to check on the raster. zB : float The Z location (height) of the second point to check. -options : dict/list, optional +options : dict or list, optional A dict or list of name=value of options for the line of sight algorithm (currently ignored). Returns ------- -collections.namedtuple(is_visible: bool, col_intersection: int, row_intersection: int) - is_visible is True if the two points are within Line of Sight. - col_intersection is the raster column index where the LOS line intersects with terrain (will be set in the future, currently set to -1). - row_intersection is the raster row index where the LOS line intersects with terrain (will be set in the future, currently set to -1). +tuple + A named tuple with the following fields: + + - ``is_visible`` (bool): True if the two points are within Line of Sight. + - ``col_intersection`` (int): Raster column index where the LOS line intersects terrain. + Will be set in the future; currently -1. + - ``row_intersection`` (int): Raster row index where the LOS line intersects terrain. + Will be set in the future; currently -1. "; // gdal.ReprojectImage diff --git a/swig/include/python/docs/gdal_rat_docs.i b/swig/include/python/docs/gdal_rat_docs.i index 52355d31d061..d4bb76ee7745 100644 --- a/swig/include/python/docs/gdal_rat_docs.i +++ b/swig/include/python/docs/gdal_rat_docs.i @@ -10,7 +10,8 @@ Create a copy of the RAT. Returns ------- -GDALRasterAttributeTable +RasterAttributeTable + A Python proxy of a :cpp:class:`GDALRasterAttributeTable` "; @@ -33,7 +34,7 @@ eUsage : int Returns ------- -int: +int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. "; diff --git a/swig/include/python/docs/ogr_docs.i b/swig/include/python/docs/ogr_docs.i index c1381b0f391e..db4cce443b4c 100644 --- a/swig/include/python/docs/ogr_docs.i +++ b/swig/include/python/docs/ogr_docs.i @@ -7,7 +7,7 @@ See :cpp:func:`OGRCodedFieldDomain::OGRCodedFieldDomain`. .. versionadded:: 3.3 Parameters ------------ +---------- name : str Domain name. Should not be ``None``. description : str, optional @@ -20,7 +20,7 @@ enumeration : dict Enumeration as a dictionary of (code : value) pairs. Should not be ``None``. Returns --------- +------- FieldDomain "; @@ -40,7 +40,7 @@ xmax : float maximum x coordinate value ymax : float maximum y coordinate value -srs : osr.SpatialReference, default = 0 +srs : SpatialReference, optional optional spatial reference to assign to the geometry Returns @@ -63,7 +63,7 @@ See :cpp:func:`OGRGlobFieldDomain::OGRGlobFieldDomain` .. versionadded:: 3.3 Parameters ------------ +---------- name : str Domain name. Should not be ``None``. description : str, optional @@ -76,7 +76,7 @@ glob : str Glob expression. Should not be ``None``. Returns --------- +------- FieldDomain "; @@ -88,7 +88,7 @@ See :cpp:func:`OGRRangeFieldDomain::OGRRangeFieldDomain`. .. versionadded:: 3.3 Parameters ------------ +---------- name : str Domain name. Should not be ``None``. description : str, optional @@ -107,7 +107,7 @@ maxIsInclusive : bool Whether the maximum value is included in the range. Returns --------- +------- FieldDomain "; @@ -119,12 +119,12 @@ Fetch human readable name for a field subtype. See :cpp:func:`OGRFieldDefn::GetFieldSubTypeName`. Parameters ------------ +---------- type : int the field subtype to get name for. Returns --------- +------- str the name. @@ -145,12 +145,12 @@ Fetch human readable name for a field type. See :cpp:func:`OGRFieldDefn::GetFieldTypeName`. Parameters ------------ +---------- type : int the field type code to get name for Returns --------- +------- str the name @@ -175,7 +175,7 @@ name : str Returns ------- -gdal.Driver +Driver Examples -------- @@ -208,7 +208,8 @@ utf8_path : str Returns ------- -gdal.Dataset, or ``None`` on failure +Dataset or None + A dataset or ``None`` on failure. Examples -------- @@ -234,7 +235,8 @@ utf8_path : str Returns ------- -gdal.Dataset, or ``None`` on failure +Dataset or None + A dataset or ``None`` on failure. "; diff --git a/swig/include/python/docs/ogr_feature_docs.i b/swig/include/python/docs/ogr_feature_docs.i index 0c8c4593c91e..55d5482c22ea 100644 --- a/swig/include/python/docs/ogr_feature_docs.i +++ b/swig/include/python/docs/ogr_feature_docs.i @@ -6,9 +6,9 @@ Python proxy of an :cpp:class:`OGRFeature`. %feature("docstring") OGRFeatureShadow " Parameters ------------ -feature_def: - :py:class:`FeatureDefn` to which the feature will adhere. +---------- +feature_def : FeatureDefn + The feature definition to which the feature will adhere. "; %feature("docstring") Clone " @@ -16,7 +16,7 @@ Duplicate a Feature. See :cpp:func:`OGRFeature::Clone`. Returns --------- +------- Feature "; @@ -65,12 +65,12 @@ same :py:class:`FeatureDefn`, have the same field values, and the same geometry See :cpp:func:`OGRFeature::Equal`. Parameters ------------ +---------- feature : Feature feature to test this one against Returns --------- +------- bool "; @@ -81,7 +81,7 @@ Fill unset fields with default values that might be defined. See :cpp:func:`OGRFeature::FillUnsetWithDefault`. Parameters ------------ +---------- bNotNullableOnly : bool if we should fill only unset fields with a not-null constraint. @@ -96,7 +96,7 @@ Fetch the :py:class:`FeatureDefn` associated with this Feature. See :cpp:func:`OGRFeature::GetDefnRef()`. Returns --------- +------- FeatureDefn "; @@ -107,7 +107,7 @@ See :cpp:func:`OGRFeature::GetFID` Returns ------- -int: +int feature id or :py:const:`NullFID` if none has been assigned. "; @@ -122,14 +122,14 @@ This method only works for :py:const:`OFTBinary` and :py:const:`OFTString` field See :cpp:func:`OGRFeature::GetFieldAsBinary`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- +------- bytearray "; @@ -143,14 +143,14 @@ and :py:const:`OFTDateTime` fields. See :cpp:func:`OGRFeature::GetFieldAsDateTime`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- +------- list list containing [ year, month, day, hour, minute, second, timezone flag ] @@ -188,15 +188,15 @@ result in a return value of zero. See :cpp:func:`OGRFeature::GetFieldAsDouble`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -float: +------- +float the field value. "; @@ -209,8 +209,8 @@ Currently this function only works for :py:const:`OFTRealList` fields. See :cpp:func:`OGRFeature::GetFieldAsDoubleList`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -242,12 +242,12 @@ See :cpp:func:`OGRFeature::GetFieldAsISO8601DateTime`. .. versionadded:: 3.7 Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. -options : dict / str +options : dict or str Not currently used. "; @@ -262,15 +262,15 @@ errors will result in a return value of zero. See :cpp:func:`OGRFeature::GetFieldAsInteger`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -int: +------- +int the field value. Examples @@ -300,15 +300,15 @@ value of zero. See :cpp:func:`OGRFeature::GetFieldAsInteger64`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -int: +------- +int the field value. "; @@ -320,15 +320,15 @@ Currently this function only works for :py:const:`OFTInteger64List` fields. See :cpp:func:`OGRFeature::GetFieldAsInteger64List`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -list: +------- +list the field value. "; @@ -342,15 +342,15 @@ This function is the same as the C++ method :cpp:func:`OGRFeature::GetFieldAsIntegerList`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -list: +------- +list the field value. "; @@ -363,15 +363,15 @@ Other field types, or errors will result in a return value of zero. See :cpp:func:`OGRFeature::GetFieldAsString`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -str: +------- +str the field value. "; @@ -384,15 +384,15 @@ Currently this method only works for :py:const:`OFTStringList` fields. See :cpp:func:`OGRFeature::GetFieldAsStringList`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -list: +------- +list the field value. "; @@ -404,8 +404,8 @@ the field count for the :py:class:`FeatureDefn`. See :cpp:func:`OGRFeature::GetFieldCount`. Returns --------- -int: +------- +int count of fields. "; @@ -416,14 +416,14 @@ Fetch definition for this field. See :cpp:func:`OGRFeature::GetFieldDefnRef`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- +------- FieldDefn a reference to the field definition. This reference should not be modified. @@ -436,13 +436,13 @@ Fetch the field index given field name. See :cpp:func:`OGRFeature::GetFieldIndex`. Parameters ------------ -field_name: +---------- +field_name : str the name of the field to search for. Returns --------- -int: +------- +int the field index, or -1 if no matching field is found. "; @@ -451,14 +451,14 @@ int: Return the type of the given field. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- +------- int field type code (e.g., :py:const:`OFTInteger`) "; @@ -471,8 +471,8 @@ the same as the geometry field count for the :py:class:`FeatureDefn`. See :cpp:func:`OGRFeature::GetGeomFieldCount`. Returns --------- -int: +------- +int count of geometry fields. "; @@ -483,15 +483,15 @@ Fetch definition for this geometry field. See :cpp:func:`OGRFeature::GetGeomFieldDefnRef`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -GeomFieldDefn: +------- +GeomFieldDefn a reference to the field definition. Should not be deleted or modified. "; @@ -503,13 +503,13 @@ Fetch the geometry field index given geometry field name. See :cpp:func:`OGRFeature::GetGeomFieldIndex`. Parameters ------------ -field_name: +---------- +field_name : str the name of the geometry field to search for. Returns --------- -int: +------- +int the geometry field index, or -1 if no matching geometry field is found. "; @@ -520,8 +520,8 @@ Fetch a feature :py:class:`Geometry`. See :cpp:func:`OGRFeature::GetGeomFieldRef`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -543,8 +543,8 @@ See :cpp:func:`OGRFeature::GetGeometryRef` The :py:func:`Feature.geometry` method is also available as an alias of :py:func:`Feature.GetGeometryRef`. Returns --------- -Geometry: +------- +Geometry the geometry, or None. "; @@ -571,7 +571,7 @@ See :cpp:func:`OGRFeature::GetNativeData` and :ref:`rfc-60`. Returns ------- -str: +str a string with the native data, or ``None``. "; @@ -587,8 +587,8 @@ data. It follows the IANA RFC 2045 See :cpp:func:`OGRFeature::GetNativeMediaType` and :ref:`rfc-60`. Returns --------- -str: +------- +str a string with the native media type, or ``None``. "; @@ -603,7 +603,7 @@ it. See :cpp:func:`OGRFeature::GetStyleString`. Returns --------- +------- str or None "; @@ -614,15 +614,15 @@ Test if a field is null. See :cpp:func:OGRFeature::`IsFieldNull`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -bool: +------- +bool ``True`` if the field is null, otherwise ``False`` "; @@ -633,15 +633,15 @@ Test if a field has ever been assigned a value or not. See :cpp:func:`OGRFeature::IsFieldSet`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -bool: +------- +bool ``True`` if the field has been set, otherwise ``False``. "; @@ -652,15 +652,15 @@ Test if a field is set and not null. See :cpp:func:`OGRFeature::IsFieldSetAndNotNull`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -bool: +------- +bool ``True`` if the field is set and not null, otherwise ``False``. "; @@ -676,13 +676,13 @@ indicating that the feature id is unknown. See :cpp:func:`OGRFeature::SetFID`. Parameters ------------ -fid: +---------- +fid : int the new feature identifier value to assign. Returns --------- -int: +------- +int :py:const:`OGRERR_NONE` on success, or some other value on failure. "; @@ -704,7 +704,7 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ +---------- id : int the field to set, from 0 to :py:meth:`GetFieldCount`-1. nList : list @@ -727,7 +727,7 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ +---------- id : int the field to set, from 0 to :py:meth:`GetFieldCount`-1. nList : list @@ -750,7 +750,7 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ +---------- id : int the field to set, from 0 to :py:meth:`GetFieldCount`-1. nList : list @@ -764,8 +764,8 @@ Clear a field, marking it as null. See :cpp:func:`OGRFeature::SetFieldNull`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -791,12 +791,12 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. -value: +value : any the value to assign. "; @@ -815,12 +815,12 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. -value: +value : any the value to assign. "; @@ -836,7 +836,7 @@ function conversion rules will be applied as needed. See :cpp:func:`OGRFeature::SetFrom`. Parameters ------------ +---------- other : Feature feature from which geometry and field values will be copied. forgiving : bool, default = True @@ -844,8 +844,8 @@ forgiving : bool, default = True output fields matching some of the source fields. Returns --------- -int: +------- +int :py:const:`OGRERR_NONE` if the operation succeeds, even if some values are not transferred, otherwise an error code. "; @@ -866,7 +866,7 @@ names don't match. See :cpp:func:`OGRFeature::SetFrom`. Parameters ------------ +---------- other : Feature handle to the feature from which geometry, and field values will be copied. @@ -881,8 +881,8 @@ nList : list source feature. Returns --------- -OGRErr: +------- +int :py:const:`OGRERR_NONE` if the operation succeeds, even if some values are not transferred, otherwise an error code. "; @@ -898,8 +898,8 @@ ownership of the passed geometry, but instead makes a copy of it. See :cpp:func:`OGRFeature::SetGeomField`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Geometry field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -907,8 +907,8 @@ geom : Geometry handle to the new geometry to apply to feature. Returns --------- -int: +------- +int :py:const:`OGRERR_NONE` if successful, or :py:const:`OGR_UNSUPPORTED_GEOMETRY_TYPE` if the geometry type is illegal for the :py:class:`FeatureDefn` (checking not yet implemented). @@ -933,13 +933,13 @@ afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ------------ +---------- geom : Geometry new geometry to apply to feature. Returns --------- -int: +------- +int :py:const:`OGRERR_NONE` if successful, or :py:const:`OGR_UNSUPPORTED_GEOMETRY_TYPE` if the geometry type is illegal for the :py:class:`FeatureDefn` (checking not yet implemented). @@ -959,7 +959,7 @@ indicated by :py:meth:`GetNativeMediaType`. See :cpp:func:`OGRFeature::SetNativeData` and :ref:`rfc-60`. Parameters ------------ +---------- nativeData : str a string with the native data, or ``None`` "; @@ -976,7 +976,7 @@ data. It follows the IANA RFC 2045 See :cpp:func:`OGRFeature::SetNativeMediaType` and :ref:`rfc-60`. Parameters ------------ +---------- nativeMediaType : str a string with the native media type, or ``None`` "; @@ -988,7 +988,7 @@ Set feature style string. See :cpp:func:`OGRFeature::SetStyleString`. Parameters ------------ +---------- the_string : str the style string to apply to this feature "; @@ -1000,8 +1000,8 @@ Clear a field, marking it as unset. See :cpp:func:`OGRFeature::UnsetField`. Parameters ------------ -fld_index : int / str +---------- +fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -1021,7 +1021,7 @@ conservative (if it fails, then it will fail for all interpretations). See :cpp:func:`OGRFeature::Validate`. Parameters ------------ +---------- flags : int, default = :py:const:`F_VAL_ALL` One or more of :py:const:`OGR_F_VAL_NULL`, :py:const:`OGR_F_VAL_GEOM_TYPE`, py:const:`OGR_F_VAL_WIDTH` and @@ -1032,7 +1032,7 @@ bEmitError : bool, default = True Returns ------- -int: +int TRUE if all enabled validation tests pass. "; diff --git a/swig/include/python/docs/ogr_featuredef_docs.i b/swig/include/python/docs/ogr_featuredef_docs.i index 9d33c1f542b3..dace3dacdc70 100644 --- a/swig/include/python/docs/ogr_featuredef_docs.i +++ b/swig/include/python/docs/ogr_featuredef_docs.i @@ -31,7 +31,7 @@ objects in existence based on this :py:class:`FeatureDefn`. The See :cpp:func:`OGRFeatureDefn::AddFieldDefn`. Parameters ------------ +---------- defn : FieldDefn the new field definition. "; @@ -50,7 +50,7 @@ objects in existence based on this :py:class:`FeatureDefn`. The See :cpp:Func:`OGRFeatureDefn::AddGeomFieldDefn`. Parameters ------------ +---------- defn : GeomFieldDefn new geometry field definition. "; @@ -69,13 +69,13 @@ objects in existence based on this :py:class:`FeatureDefn`. See :cpp:func:`OGRFeatureDefn::DeleteGeomFieldDefn`. Parameters ------------ +---------- idx : int the index of the geometry field definition. Returns --------- -int: +------- +int :py:const:`OGRERR_NONE` in case of success. "; @@ -86,8 +86,8 @@ Fetch number of fields on the passed feature definition. See :cpp:func:`OGRFeatureDefn::GetFieldCount`. Returns --------- -int: +------- +int count of fields. "; @@ -98,15 +98,15 @@ Fetch field definition of the passed feature definition. See :cpp:func:`OGRFeatureDefn::GetFieldDefn`. Parameters ------------ -i : int / str +---------- +i : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. Returns --------- -FieldDefn: +------- +FieldDefn internal field definition object or ``None`` if the field does not exist. This object should not be modified by the application. "; @@ -121,13 +121,13 @@ The field index of the first field matching the passed field name See :cpp:func:`OGRFeatureDefn::GetFieldIndex`. Parameters ------------ +---------- field_name : str the field name to search for. Returns --------- -int: +------- +int the field index, or -1 if no match found. "; @@ -138,8 +138,8 @@ Fetch number of geometry fields on the passed feature definition. See :cpp:func:`OGRFeatureDefn::GetGeomFieldCount`. Returns --------- -int: +------- +int count of geometry fields. "; @@ -150,13 +150,13 @@ Fetch geometry field definition of the passed feature definition. See :cpp:func:`OGRFeatureDefn::GetGeomFieldDefn`. Parameters ------------ +---------- i : int the geometry field to fetch, between 0 and GetGeomFieldCount() - 1. Returns --------- -GeomFieldDefn: +------- +GeomFieldDefn an internal field definition object or ``None`` if invalid index. This object should not be modified by the application. "; @@ -171,13 +171,13 @@ passed field name (case insensitively) is returned. See :cpp:func:`OGRFeatureDefn::GetGeomFieldIndex`. Parameters ------------ +---------- field_name : str the geometry field name to search for. Returns --------- -int: +------- +int the geometry field index, or -1 if no match found. "; @@ -190,8 +190,8 @@ This is equivalent to ``GetGeomFieldDefn(0).GetType()``. See :cpp:func:`OGRFeatureDefn::GetGeomType`. Returns --------- -int : +------- +int the base type for all geometry related to this definition. "; @@ -202,8 +202,8 @@ Get name of the :py:class:`FeatureDefn`. See :cpp:func:`OGRFeatureDefn::GetName`. Returns --------- -str: +------- +str the name "; @@ -214,8 +214,8 @@ Fetch current reference count. See :cpp:func:`OGRFeatureDefn::GetReferenceCount`. Returns --------- -int: +------- +int the current reference count. "; @@ -228,8 +228,8 @@ Equivalent to ``GetGeomFieldDefn(0).IsIgnored()``. See :cpp:func:`OGRFeatureDefn::IsGeometryIgnored`. Returns --------- -int: +------- +int ignore state "; @@ -238,13 +238,13 @@ int: Test if the feature definition is identical to the other one. Parameters ------------ +---------- other_defn : FeatureDefn other feature definition to compare to. Returns --------- -int: +------- +int 1 if the feature definition is identical to the other one. "; @@ -255,8 +255,8 @@ Determine whether the style can be omitted when fetching features. See :cpp:func:`OGRFeatureDefn::IsStyleIgnored`. Returns --------- -int: +------- +int ignore state "; @@ -275,7 +275,7 @@ after any :py:class:`Feature` objects have been created against this definition. See :cpp:func:`OGRFeatureDefn::SetGeomType`. Parameters ------------ +---------- geom_type : int the new type to assign. "; @@ -289,7 +289,7 @@ This is equivalent to ``GetGeomFieldDefn(0).SetIgnored()``. See :cpp:func:`OGRFeatureDefn::SetGeometryIgnored`. Parameters ------------ +---------- bignored : bool ignore state "; @@ -301,7 +301,7 @@ Set whether the style can be omitted when fetching features. See :cpp:func:`OGRFeatureDefn::SetStyleIgnored`. Parameters ------------ +---------- bignored : bool ignore state "; diff --git a/swig/include/python/docs/ogr_fielddef_docs.i b/swig/include/python/docs/ogr_fielddef_docs.i index abd16d969836..6a9570fe9449 100644 --- a/swig/include/python/docs/ogr_fielddef_docs.i +++ b/swig/include/python/docs/ogr_fielddef_docs.i @@ -15,7 +15,7 @@ This function is the same as the CPP method OGRFieldDefn::OGRFieldDefn(). Parameters ------------ +---------- pszName: the name of the new field definition. eType: @@ -44,8 +44,8 @@ See :cpp:func:`OGRFieldDefn::GetAlternativeNameRef`. .. versionadded:: 3.2 Returns --------- -str: +------- +str the alternative name of the field definition. "; @@ -56,8 +56,8 @@ Get default field value. See :cpp:func:`OGRFieldDefn::GetDefault`. Returns --------- -str: +------- +str default field value or ``None``. "; @@ -74,8 +74,8 @@ See :cpp:func:`OGRFieldDefn::GetDomainName`. .. versionadded:: 3.3 Returns --------- -str: +------- +str the field domain name, or an empty string if there is none. "; @@ -88,8 +88,8 @@ See :cpp:func:`OGRFieldDefn::GetJustify`. Note: no driver is know to use the concept of field justification. Returns --------- -OGRJustification: +------- +object the justification. "; @@ -100,8 +100,8 @@ Fetch name of this field. See :cpp:func:`OGRFieldDefn::GetNameRef`. Returns --------- -str: +------- +str the name of the field definition. "; @@ -114,8 +114,8 @@ This should normally be zero for fields of types other than :py:const:`OFTReal`. See :cpp:func:`OGRFieldDefn::GetPrecision`. Returns --------- -int: +------- +int the precision. "; @@ -126,7 +126,7 @@ Fetch subtype of this field. See :cpp:func:`OGRFieldDefn::GetSubType`. Returns --------- +------- int field subtype code, default = :py:const:`OFSTNone` "; @@ -138,7 +138,7 @@ Fetch type of this field. See :cpp:func:`OGRFieldDefn::GetType`. Returns --------- +------- int field type code, e.g. :py:const:`OFTInteger` "; @@ -150,8 +150,8 @@ Get the formatting width for this field. See :cpp:func:`OGRFieldDefn::GetWidth`. Returns --------- -int: +------- +int the width, zero means no specified width. "; @@ -167,8 +167,8 @@ value. See :cpp:func:`OGRFieldDefn::IsDefaultDriverSpecific`. Returns --------- -int: +------- +int TRUE if the default value is driver specific. "; @@ -179,8 +179,8 @@ Return whether this field should be omitted when fetching features. See :cpp:func:`OGRFieldDefn::IsIgnored`. Returns --------- -int: +------- +int ignore state "; @@ -198,8 +198,8 @@ done when :py:meth:`Layer.CreateFeature`/:py:meth:`Layer.SetFeature` is called. See :cpp:func:`OGRFieldDefn::IsNullable`. Returns --------- -int: +------- +int TRUE if the field is authorized to be null. "; @@ -214,8 +214,8 @@ See :cpp:func:`OGRFieldDefn::IsUnique`. .. versionadded:: 3.2 Returns --------- -int: +------- +int TRUE if the field has a unique constraint. "; @@ -236,7 +236,7 @@ See :cpp:func:`OGRFieldDefn::SetAlternativeName`. .. versionadded:: 3.2 Parameters ------------ +---------- alternativeName : str the new alternative name to apply. "; @@ -266,7 +266,7 @@ GDAL_DCAP_DEFAULT_FIELDS driver metadata item. See :cpp:func:`OGRFieldDefn::SetDefault`. Parameters ------------ +---------- pszValue : str new default field value or NULL pointer. "; @@ -282,7 +282,7 @@ See :cpp:func:`OGRFieldDefn::SetDomainName`. .. versionadded:: 3.3 Parameters ------------ +---------- name : str Field domain name. "; @@ -294,7 +294,7 @@ Set whether this field should be omitted when fetching features. See :cpp:func:`OGRFieldDefn::SetIgnored`. Parameters ------------ +---------- bignored : bool ignore state "; @@ -308,7 +308,7 @@ Note: no driver is know to use the concept of field justification. See :cpp:func:`OGRFieldDefn::SetJustify`. Parameters ------------ +---------- justify : int the new justification @@ -325,7 +325,7 @@ Reset the name of this field. See :cpp:func:`OGRFieldDefn::SetName`. Parameters ------------ +---------- name : str the new name to apply "; @@ -343,7 +343,7 @@ Drivers that support writing not-null constraint will advertise the See :cpp:func:`OGRFieldDefn::SetNullable`. Parameters ------------ +---------- bNullable : bool ``False`` if the field must have a not-null constraint. "; @@ -357,7 +357,7 @@ This should normally be zero for fields of types other than :py:const:`OFTReal`. See :cpp:func:`OGRFieldDefn::SetPrecision`. Parameters ------------ +---------- precision : int the new precision. "; @@ -372,7 +372,7 @@ an :py:class:FeatureDefn`. See :cpp:func:`OGRFieldDefn::SetSubType`. Parameters ------------ +---------- type : the new field subtype. @@ -395,7 +395,7 @@ an :py:class:`FeatureDefn`. See :cpp:func:`OGRFieldDefn::SetType`. Parameters ------------ +---------- type : int the new field type. @@ -426,7 +426,7 @@ See :cpp:func:`OGRFieldDefn::SetUnique`. .. versionadded:: 3.2 Parameters ------------ +---------- bUnique : bool ``True`` if the field must have a unique constraint "; @@ -438,7 +438,7 @@ Set the formatting width for this field in characters. See :cpp:func:`OGRFieldDefn::SetWidth`. Parameters ------------ +---------- width : int the new width "; diff --git a/swig/include/python/docs/ogr_fielddomain_docs.i b/swig/include/python/docs/ogr_fielddomain_docs.i index 3190c6a94386..9a070b22fec1 100644 --- a/swig/include/python/docs/ogr_fielddomain_docs.i +++ b/swig/include/python/docs/ogr_fielddomain_docs.i @@ -20,7 +20,7 @@ See :cpp:func:`OGRFieldDomain::GetDescription`. .. versionadded:: 3.3 Returns --------- +------- str the field domain description (might be empty string). "; @@ -34,7 +34,7 @@ See :cpp:func:`OGRFieldDomain::GetName`. .. versionadded:: 3.3 Returns --------- +------- str the field domain name. "; @@ -48,7 +48,7 @@ See :cpp:func:`OGRFieldDomain::GetDomainType`. .. versionadded:: 3.3 Returns --------- +------- int the type of the field domain. @@ -69,7 +69,7 @@ See :cpp:func:`OGRCodedFieldDomain::GetEnumeration`. .. versionadded:: 3.3 Returns --------- +------- dict Examples @@ -89,7 +89,7 @@ See :cpp:func:`OGRFieldDomain::GetFieldSubType`. .. versionadded:: 3.3 Returns --------- +------- int the field subtype of the field domain. "; @@ -103,7 +103,7 @@ See :cpp:func:`OGRFieldDomain::GetFieldType`. .. versionadded:: 3.3 Returns --------- +------- int the field type of the field domain. "; @@ -117,7 +117,7 @@ See :cpp:func:`OGRGlobFieldDomain::GetGlob`. .. versionadded:: 3.3 Returns --------- +------- str the glob expression, or ``None`` in case of error "; @@ -131,7 +131,7 @@ See :cpp:func:`OGRFieldDomain::GetMergePolicy`. .. versionadded:: 3.3 Returns --------- +------- int the merge policy of the field domain (default = :py:const:`OFDMP_DEFAULT_VALUE`) "; @@ -145,7 +145,7 @@ See :cpp:func:`OGRRangeFieldDomain::GetMax()` .. versionadded:: 3.3 Returns --------- +------- float the maximum value of the range "; @@ -159,7 +159,7 @@ See :cpp:func:`OGRRangeFieldDomain::GetMax()` .. versionadded:: 3.3 Returns --------- +------- str the maximum value of the range "; @@ -173,7 +173,7 @@ See :cpp:func:`OGRRangeFieldDomain::GetMin()` .. versionadded:: 3.3 Returns --------- +------- float the minimum value of the range "; @@ -187,7 +187,7 @@ See :cpp:func:`OGRRangeFieldDomain::GetMin()` .. versionadded:: 3.3 Returns --------- +------- str the minimum value of the range "; @@ -201,7 +201,7 @@ See :cpp:func:`OGRFieldDomain::GetSplitPolicy`. .. versionadded:: 3.3 Returns --------- +------- int the split policy of the field domain (default = :py:const:`OFDSP_DEFAULT_VALUE`) "; @@ -215,7 +215,7 @@ See :cpp:func:`OGRFieldDomain::SetMergePolicy`. .. versionadded:: 3.3 Parameters ------------ +---------- policy : int the merge policy code of the field domain. "; diff --git a/swig/include/python/docs/ogr_geometry_docs.i b/swig/include/python/docs/ogr_geometry_docs.i index 4ba3a1f44c94..096fed707d5c 100644 --- a/swig/include/python/docs/ogr_geometry_docs.i +++ b/swig/include/python/docs/ogr_geometry_docs.i @@ -11,8 +11,8 @@ geometry expressed in a geographic SRS. For more details: :cpp:func:`OGR_G_Area` Returns --------- -float: +------- +float the area of the geometry in square units of the spatial reference system in use, or 0.0 for unsupported geometry types. @@ -25,8 +25,8 @@ ellipsoid of the SRS attached to the geometry. For more details: :cpp:func:`OGR_G_GeodesicArea` Returns --------- -float: +------- +float the area in square meters, or a negative value for unsupported geometry types. "; @@ -41,8 +41,8 @@ geometry expressed in a geographic SRS. For more details: :cpp:func:`OGR_G_Length` Returns --------- -float: +------- +float the length of the geometry in units of the spatial reference system in use, or 0.0 for unsupported geometry types. @@ -55,8 +55,8 @@ ellipsoid of the SRS attached to the geometry. For more details: :cpp:func:`OGR_G_GeodesicLength` Returns --------- -float: +------- +float the area in meters, or a negative value for unsupported geometry types. "; @@ -73,8 +73,8 @@ Assign spatial reference to this object. For more details: :cpp:func:`OGR_G_AssignSpatialReference` Parameters ------------ -reference: SpatialReference +---------- +reference : SpatialReference The new spatial reference system to apply. "; @@ -84,13 +84,13 @@ Determines whether two geometries intersect. For more details: :cpp:func:`OGR_G_Intersects` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry to test against. Returns --------- -int: +------- +int True if the geometries intersect, otherwise False. "; @@ -100,13 +100,13 @@ Transform geometry to new spatial reference system. For more details: :cpp:func:`OGR_G_TransformTo` Parameters ------------ -reference: SpatialReference +---------- +reference : SpatialReference The spatial reference system to apply. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success, or an error code. "; @@ -116,13 +116,13 @@ Apply arbitrary coordinate transformation to geometry. For more details: :cpp:func:`OGR_G_Transform` Parameters ------------ -trans: CoordinateTransform +---------- +trans : CoordinateTransform The transformation to apply. Returns --------- -Geometry: +------- +Geometry The transformed geometry. "; @@ -133,8 +133,8 @@ distance. For more details: :cpp:func:`OGR_G_Segmentize` Parameters ------------ -dfMaxLength: float +---------- +dfMaxLength : float the maximum distance between 2 points after segmentization "; @@ -144,8 +144,8 @@ Get the dimension of this geometry. For more details: :cpp:func:`OGR_G_GetDimension` Returns --------- -int: +------- +int 0 for points, 1 for lines, and 2 for surfaces. "; @@ -158,8 +158,8 @@ For more details: :cpp:func:`OGR_G_GetCoordinateDimension` :py:func:`Is3D`, or :py:func:`IsMeasured`. Returns --------- -int: +------- +int This will return 2 or 3. "; @@ -171,8 +171,8 @@ For more details: :cpp:func:`OGR_G_CoordinateDimension` .. versionadded:: 2.1 Returns --------- -int: +------- +int This will return 2 for XY, 3 for XYZ and XYM, and 4 for XYZM data. "; @@ -184,8 +184,8 @@ For more details: :cpp:func:`OGR_G_Is3D` .. versionadded:: 2.1 Returns --------- -int: +------- +int True if the geometry has Z coordinates. "; @@ -197,8 +197,8 @@ For more details: :cpp:func:`OGR_G_IsMeasured` .. versionadded:: 2.1 Returns --------- -int: +------- +int True if the geometry has M coordinates. "; @@ -210,8 +210,8 @@ For more details: :cpp:func:`OGR_G_SetCoordinateDimension` .. warning:: Deprecated. Use :py:func:`Set3D` or :py:func:`SetMeasured`. Parameters ------------ -dimension: int +---------- +dimension : int New coordinate dimension value, either 2 or 3. "; @@ -223,8 +223,8 @@ For more details: :cpp:func:`OGR_G_Set3D` .. versionadded:: 2.1 Parameters ------------ -bIs3D: bool +---------- +bIs3D : bool Should the geometry have a Z dimension, either True or False. "; @@ -236,8 +236,8 @@ For more details: :cpp:func:`OGR_G_SetMeasured` .. versionadded:: 2.1 Parameters ------------ -bIsMeasured: bool +---------- +bIsMeasured : bool Should the geometry have a M dimension, either True or False. "; @@ -247,13 +247,13 @@ Returns True if two geometries are equivalent. For more details: :cpp:func:`OGR_G_Equals` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry to test against. Returns --------- -int: +------- +int True if equivalent or False otherwise. "; @@ -263,7 +263,7 @@ Returns size of related binary representation. For more details: :cpp:func:`OGR_G_WkbSize` Returns --------- +------- int "; @@ -275,7 +275,7 @@ For more details: :cpp:func:`OGR_G_WkbSizeEx` .. versionadded:: 3.3 Returns --------- +------- int "; @@ -288,11 +288,9 @@ For more details: :cpp:func:`OGR_G_GetEnvelope` .. warning:: Check the return order of the bounds. Returns --------- -minx: float -maxx: float -miny: float -maxy: float +------- +tuple of float + (minx, maxx, miny, maxy) "; %feature("docstring") GetEnvelope3D " @@ -304,13 +302,9 @@ For more details: :cpp:func:`OGR_G_GetEnvelope3D` .. warning:: Check the return order of the bounds. Returns --------- -minx: float -maxx: float -miny: float -maxy: float -minz: float -maxz: float +------- +tuple of float + (minx, maxx, miny, maxy, minz, maxz) "; @@ -320,12 +314,14 @@ Convert a geometry well known binary format. For more details: :cpp:func:`OGR_G_ExportToWkb` Parameters ------------ -byte_order: osgeo.ogr.wkbXDR | osgeo.ogr.wkbNDR, default=osgeo.ogr.wkbNDR - One of wkbXDR or wkbNDR indicating MSB or LSB byte order respectively. +---------- +byte_order : int, optional + One of :py:const:`osgeo.ogr.wkbXDR` or :py:const:`osgeo.ogr.wkbNDR`, + indicating MSB (most significant byte) or LSB (least significant byte) + byte order. Defaults to :py:const:`osgeo.ogr.wkbNDR`. Returns --------- +------- bytes "; @@ -338,12 +334,14 @@ For more details: :cpp:func:`OGR_G_ExportToIsoWkb` .. versionadded:: 2.0 Parameters ------------ -byte_order: osgeo.ogr.wkbXDR | osgeo.ogr.wkbNDR, default=osgeo.ogr.wkbNDR - One of wkbXDR or wkbNDR indicating MSB or LSB byte order respectively. +---------- +byte_order : int, optional + One of :py:const:`osgeo.ogr.wkbXDR` or :py:const:`osgeo.ogr.wkbNDR`, + indicating MSB (most significant byte) or LSB (least significant byte) + byte order. Defaults to :py:const:`osgeo.ogr.wkbNDR`. Returns --------- +------- bytes "; @@ -354,7 +352,7 @@ Convert a geometry into well known text format. For more details: :cpp:func:`OGR_G_ExportToWkt` Returns --------- +------- str "; @@ -367,7 +365,7 @@ For more details: :cpp:func:`OGR_G_ExportToIsoWkt` .. versionadded:: 2.0 Returns --------- +------- str "; @@ -377,8 +375,8 @@ Fetch geometry type. For more details: :cpp:func:`OGR_G_GetGeometryType` Returns --------- -int: +------- +int The geometry type code. The types can be found with 'osgeo.ogr.wkb' prefix. For example :py:const:`osgeo.ogr.wkbPolygon`. "; @@ -391,7 +389,7 @@ For more details: :cpp:func:`OGR_G_GetGeometryName` geometry to get name from. Returns --------- +------- str "; @@ -401,8 +399,8 @@ Make a copy of this object. For more details: :cpp:func:`OGR_G_Clone` Returns --------- -Geometry: +------- +Geometry The copy of the geometry with the same spatial reference system as the original. "; @@ -413,7 +411,7 @@ For more details: :cpp:func:`OGR_G_GetSpatialReference` Returns spatial reference system for geometry. Returns --------- +------- SpatialReference "; @@ -429,8 +427,8 @@ Test if the geometry is empty. For more details: :cpp:func:`OGR_G_IsEmpty` Returns --------- -int: +------- +int True if the geometry has no points, otherwise False. "; @@ -440,8 +438,8 @@ Test if the geometry is valid. For more details: :cpp:func:`OGR_G_IsValid` Returns --------- -int: +------- +int True if the geometry has no points, otherwise False. "; @@ -451,8 +449,8 @@ Returns True if the geometry is simple. For more details: :cpp:func:`OGR_G_IsSimple` Returns --------- -int: +------- +int True if object is simple, otherwise False. "; @@ -462,8 +460,8 @@ Test if the geometry is a ring. For more details: :cpp:func:`OGR_G_IsRing` Returns --------- -int: +------- +int True if the coordinates of the geometry form a ring, by checking length and closure (self-intersection is not checked), otherwise False. "; @@ -481,13 +479,13 @@ Compute distance between two geometries. For more details: :cpp:func:`OGR_G_Distance` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry to compare against. Returns --------- -float: +------- +float The distance between the geometries or -1 if an error occurs. "; @@ -499,13 +497,13 @@ For more details: :cpp:func:`OGR_G_Distance3D` .. versionadded:: 2.2 Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry to compare against. Returns --------- -float: +------- +float The distance between the geometries or -1 if an error occurs. "; @@ -518,13 +516,13 @@ For more details: :cpp:func:`OGR_G_MakeValidEx` .. versionadded:: 3.4 options Parameters ------------ -options: list[str], optional +---------- +options : list[str], optional papszOptions to be passed in. For example: [\"METHOD=STRUCTURE\"]. Returns --------- -Geometry: +------- +Geometry A newly allocated geometry now owned by the caller, or None on failure. "; @@ -538,8 +536,8 @@ For more details: :cpp:func:`OGR_G_Normalize` .. versionadded:: 3.3 Returns --------- -Geometry: +------- +Geometry A newly allocated geometry now owned by the caller, or None on failure. "; @@ -550,8 +548,8 @@ Compute convex hull. For more details: :cpp:func:`OGR_G_ConvexHull` Returns --------- -Geometry: +------- +Geometry a handle to A newly allocated geometry now owned by the caller, or None on failure. "; @@ -562,8 +560,8 @@ Compute boundary. For more details: :cpp:func:`OGR_G_Boundary` Returns --------- -Geometry: +------- +Geometry A new geometry or None on failure. "; @@ -583,20 +581,20 @@ Compute buffer of geometry. For more details: :cpp:func:`OGR_G_Buffer` Parameters ------------ -distance: float +---------- +distance : float The buffer distance to be applied. Should be expressed into the same unit as the coordinates of the geometry. -quadsecs: int, default=30 +quadsecs : int, default=30 The number of segments used to approximate a 90 degree (quadrant) of curvature. -options: list/dict +options : list or dict, optional An optional list of options to control the buffer output. See :cpp:func:`OGR_G_BufferEx`. Returns --------- -Geometry: +------- +Geometry The newly created geometry or None if an error occurs. "; @@ -606,13 +604,13 @@ Compute intersection. For more details: :cpp:func:`OGR_G_Intersection` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry. Returns --------- -Geometry: +------- +Geometry A new geometry representing the intersection or None if there is no intersection or an error occurs. "; @@ -623,24 +621,24 @@ Compute union. For more details: :cpp:func:`OGR_G_Union` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry. Returns --------- -Geometry: +------- +Geometry A new geometry representing the union or None if an error occurs. "; %feature("docstring") UnionCascaded " Compute union using cascading. -For more deails: :cpp:func:`OGR_G_UnionCascaded` +For more details: :cpp:func:`OGR_G_UnionCascaded` Returns --------- -Geometry: +------- +Geometry A new geometry representing the union or None if an error occurs. "; @@ -650,13 +648,13 @@ Compute difference. For more details: :cpp:func:`OGR_G_Difference` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry. Returns --------- -Geometry: +------- +Geometry A new geometry representing the difference or None if the difference is empty or an error occurs. "; @@ -667,13 +665,13 @@ Compute symmetric difference. For more details: :cpp:func:`OGR_G_SymDifference` Parameters ------------ -other: +---------- +other : Geometry the other geometry. Returns --------- -Geometry: +------- +Geometry A new geometry representing the symmetric difference or None if the difference is empty or an error occurs. "; @@ -693,13 +691,13 @@ Test for disjointness. For more details: :cpp:func:`OGR_G_Disjoint` Parameters ------------ -other: Geometry +---------- +other : Geometry The other geometry to compare. Returns --------- -int: +------- +int True if they are disjoint, otherwise False. "; @@ -709,13 +707,13 @@ Test for touching. For more details: :cpp:func:`OGR_G_Touches` Parameters ------------ -other: +---------- +other : Geometry the other geometry to compare. Returns --------- -int: +------- +int True if they are touching, otherwise False. "; @@ -725,13 +723,13 @@ Test for crossing. For more details: :cpp:func:`OGR_G_Crosses` Parameters ------------ -other: Geometry +---------- +other : Geometry the other geometry to compare. Returns --------- -int: +------- +int True if they are crossing, otherwise False. "; @@ -741,13 +739,13 @@ Test for containment. For more details: :cpp:func:`OGR_G_Within` Parameters ------------ -other: Geometry +---------- +other : Geometry the other geometry to compare. Returns --------- -int: +------- +int True if this is within other, otherwise False. "; @@ -757,13 +755,13 @@ Test for containment. For more details: :cpp:func:`OGR_G_Contains` Parameters ------------ -other: Geometry +---------- +other : Geometry the other geometry to compare. Returns --------- -int: +------- +int True if this contains the other geometry, otherwise False. "; @@ -773,13 +771,13 @@ Test for overlap. For more details: :cpp:func:`OGR_G_Overlaps` Parameters ------------ -other: Geometry +---------- +other : Geometry the other geometry to compare. Returns --------- -int: +------- +int True if they are overlapping, otherwise False. "; @@ -795,7 +793,7 @@ Compute the geometry centroid. For more details: :cpp:func:`OGR_G_Centroid` Returns --------- +------- Geometry "; @@ -805,8 +803,8 @@ Returns a point guaranteed to lie on the surface. For more details: :cpp:func:`OGR_G_PointOnSurface` Returns --------- -Geometry: +------- +Geometry A point guaranteed to lie on the surface or None if an error occurred. "; @@ -816,13 +814,13 @@ Compute a simplified geometry. For more details: :cpp:func:`OGR_G_Simplify` Parameters ------------ -tolerance: float +---------- +tolerance : float The distance tolerance for the simplification. Returns --------- -Geometry: +------- +Geometry The simplified geometry or None if an error occurs. "; @@ -832,13 +830,13 @@ Simplify the geometry while preserving topology. For more details: :cpp:func:`OGR_G_SimplifyPreserveTopology` Parameters ------------ -tolerance: float +---------- +tolerance : float The distance tolerance for the simplification. Returns --------- -Geometry: +------- +Geometry The simplified geometry or None if an error occurs. "; @@ -850,16 +848,16 @@ For more details: :cpp:func:`OGR_G_DelaunayTriangulation` .. versionadded:: 2.1 Parameters ------------ -dfTolerance: float +---------- +dfTolerance : float optional snapping tolerance to use for improved robustness -bOnlyEdges: bool +bOnlyEdges : bool If True, will return a MULTILINESTRING, otherwise it will return a GEOMETRYCOLLECTION containing triangular POLYGONs. Returns --------- -Geometry: +------- +Geometry The geometry resulting from the Delaunay triangulation or None if an error occurs. "; @@ -874,8 +872,8 @@ For more details: :cpp:func:`OGR_G_ConstrainedDelaunayTriangulation` .. versionadded:: 3.12 Returns --------- -Geometry: +------- +Geometry The geometry collection resulting from the constrained Delaunay triangulation or None if an error occurs. "; @@ -886,8 +884,8 @@ Polygonizes a set of sparse edges. For more details: :cpp:func:`OGR_G_Polygonize` Returns --------- -Geometry: +------- +Geometry A new geometry or None on failure. "; @@ -897,8 +895,8 @@ Polygonize a linework assuming inner polygons are holes. For more details: :cpp:func:`OGR_G_BuildArea` Returns --------- -Geometry: +------- +Geometry A new geometry or None on failure. "; @@ -925,16 +923,16 @@ use AddPoint_2D. This is the same as :cpp:func:`OGR_G_AddPoint` Parameters ------------ -X: float +---------- +X : float x coordinate of point to add. -Y: float +Y : float y coordinate of point to add. -Z: float +Z : float z coordinate of point to add. Defaults to 0 Examples -------- +-------- >>> pt = ogr.Geometry(ogr.wkbPoint) >>> ogr.GeometryTypeToName(pt.GetGeometryType()) 'Point' @@ -955,10 +953,10 @@ for the added point will be 0. This is the same as :cpp:func:`OGR_G_AddPoint_2D` Parameters ------------ -X: float +---------- +X : float x coordinate of point to add. -Y: float +Y : float y coordinate of point to add. Examples diff --git a/swig/include/python/docs/ogr_layer_docs.i b/swig/include/python/docs/ogr_layer_docs.i index 180845de7738..c5528647d104 100644 --- a/swig/include/python/docs/ogr_layer_docs.i +++ b/swig/include/python/docs/ogr_layer_docs.i @@ -18,14 +18,14 @@ Fetch the feature count in this layer. For more details: :cpp:func:`OGR_L_GetFeatureCount` Parameters ------------ -force: int +---------- +force : int Flag indicating whether the count should be computed even if it is expensive. Returns --------- -int: +------- +int Feature count, -1 if count not known. "; @@ -40,22 +40,20 @@ For more details: .. warning:: Check the return order of the bounds. Parameters ------------ -force: int, default=False +---------- +force : int, default=False Flag indicating whether the extent should be computed even if it is expensive. -can_return_null: int, default=False +can_return_null : int, default=False Whether None can be returned in the response. -geom_field: int, default=0 +geom_field : int, default=0 The index of the geometry field on which to compute the extent. Can be iterated over using :py:func:`range` and :py:func:`GetGeomFieldCount`. Returns --------- -minx: float -maxx: float -miny: float -maxy: float +------- +tuple of float + (minx, maxx, miny, maxy) "; @@ -65,14 +63,14 @@ Set a new attribute query. For more details: :cpp:func:`OGR_L_SetAttributeFilter` Parameters ------------ -filter_string: str +---------- +filter_string : str query in restricted SQL WHERE format, or None to clear the current query. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` if successfully installed, or an error code if the query expression is in error, or some other failure occurs. @@ -91,13 +89,13 @@ Sequential reads (with :py:func:`GetNextFeature`) are generally considered interrupted by a :py:func:`GetFeature` call. Parameters ------------ -fid: int +---------- +fid : int The feature id of the feature to read. Returns --------- -Feature: +------- +Feature A new feature now owned by the caller, or None on failure. The returned feature should be deleted with :py:func:`Destroy`. "; @@ -108,13 +106,13 @@ Move read cursor to the nIndex'th feature in the current resultset. For more details: :cpp:func:`OGR_L_SetNextByIndex` Parameters ------------ -new_index: int +---------- +new_index : int The index indicating how many steps into the result set to seek. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success or an error code. "; @@ -124,8 +122,8 @@ Fetch the next available feature from this layer. For more details: :cpp:func:`OGR_L_GetNextFeature` Returns --------- -Feature: +------- +Feature A feature or None if no more features are available. "; @@ -137,13 +135,13 @@ For more details: :cpp:func:`OGR_L_SetFeature` To set a feature, but create it if it doesn't exist see :py:meth:`.Layer.UpsertFeature`. Parameters ------------ -feature: Feature +---------- +feature : Feature The feature to write. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` if the operation works, otherwise an appropriate error code (e.g :py:const:`osgeo.ogr.OGRERR_NON_EXISTING_FEATURE` if the @@ -158,13 +156,13 @@ For more details: :cpp:func:`OGR_L_CreateFeature` To create a feature, but set it if it exists see :py:meth:`.Layer.UpsertFeature`. Parameters ------------ -feature: Feature +---------- +feature : Feature The feature to write to disk. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -174,13 +172,13 @@ Rewrite an existing feature or create a new feature within a layer. For more details: :cpp:func:`OGR_L_UpsertFeature` Parameters ------------ -feature: Feature +---------- +feature : Feature The feature to write to disk. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -190,16 +188,16 @@ Create a new field on a layer. For more details: :cpp:func:`OGR_L_CreateField` Parameters ------------ -field_def: FieldDefn +---------- +field_def : FieldDefn The field definition to write to disk. -approx_ok: bool, default=True +approx_ok : bool, default=True If True, the field may be created in a slightly different form depending on the limitations of the format driver. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -209,13 +207,13 @@ Delete an existing field on a layer. For more details: :cpp:func:`OGR_L_DeleteField` Parameters ------------ -iField: int +---------- +iField : int index of the field to delete. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -225,15 +223,15 @@ Reorder all the fields of a layer. For more details: :cpp:func:`OGR_L_ReorderFields` Parameters ------------ -nList: list[int] +---------- +nList : list[int] A list of GetLayerDefn().GetFieldCount() elements which is a permutation of [0, GetLayerDefn().GetFieldCount()-1]. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -243,17 +241,17 @@ Reorder an existing field on a layer. For more details: :cpp:func:`OGR_L_ReorderField` Parameters ------------ -iOldFieldPos: int +---------- +iOldFieldPos : int previous position of the field to move. Must be in the range [0,GetFieldCount()-1]. -iNewFieldPos: int +iNewFieldPos : int new position of the field to move. Must be in the range [0,GetFieldCount()-1]. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -263,12 +261,12 @@ Alter the definition of an existing field on a layer. For more details: :cpp:func:`OGR_L_AlterFieldDefn` Parameters ------------ -iField: int +---------- +iField : int index of the field whose definition must be altered. -field_def: FieldDefn +field_def : FieldDefn new field definition -nFlags: int +nFlags : int Combination of :py:const:`osgeo.ogr.ALTER_NAME_FLAG`, :py:const:`osgeo.ogr.ALTER_TYPE_FLAG`, @@ -280,8 +278,8 @@ nFlags: int into account. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -291,16 +289,16 @@ Create a new geometry field on a layer. For more details: :cpp:func:`OGR_L_CreateGeomField` Parameters ------------ -field_def: GeomFieldDefn +---------- +field_def : GeomFieldDefn The geometry field definition to write to disk. -approx_ok: bool, default=True +approx_ok : bool, default=True If True, the field may be created in a slightly different form depending on the limitations of the format driver. Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -310,8 +308,8 @@ For datasources which support transactions, this creates a transaction. For more details: :cpp:func:`OGR_L_StartTransaction` Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -321,8 +319,8 @@ For datasources which support transactions, this commits a transaction. For more details: :cpp:func:`OGR_L_CommitTransaction` Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -332,8 +330,8 @@ Roll back a datasource to its state before the start of the current transaction. For more details: :cpp:func:`OGR_L_RollbackTransaction` Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` on success. "; @@ -343,8 +341,8 @@ Fetch the schema information for this layer. For more details: :cpp:func:`OGR_L_GetLayerDefn` Returns --------- -FeatureDefn: +------- +FeatureDefn The feature definition. "; @@ -354,8 +352,8 @@ Find the index of field in a layer. For more details: :cpp:func:`OGR_L_FindFieldIndex` Returns --------- -int: +------- +int field index, or -1 if the field doesn't exist "; @@ -365,9 +363,9 @@ Fetch the spatial reference system for this layer. For more details: :cpp:func:`OGR_L_GetSpatialRef` Returns --------- -SpatialReference: - spatial reference, or None if there isn't one. +------- +SpatialReference + spatial reference, or ``None`` if there isn't one. "; %feature("docstring") TestCapability " @@ -376,15 +374,15 @@ Test if this layer supported the named capability. For more details: :cpp:func:`OGR_L_TestCapability` Parameters ------------ -cap: str +---------- +cap : str The name of the capability to test. These can be found in the `osgeo.ogr` namespace. For example, :py:const:`osgeo.ogr.OLCRandomRead`. Returns --------- -int: +------- +int True if the layer has the requested capability, or False otherwise. Will return False for any unrecognized capabilities. "; @@ -395,8 +393,8 @@ This function returns the current spatial filter for this layer. For more details: :cpp:func:`OGR_L_GetSpatialFilter` Returns --------- -Geometry: +------- +Geometry The spatial filter geometry. "; @@ -409,10 +407,10 @@ For more details: - :cpp:func:`OGR_L_SetSpatialFilterEx` Parameters ------------ -iGeomField: int, optional +---------- +iGeomField : int, optional index of the geometry field on which the spatial filter operates. -filter: Geometry +filter : Geometry The geometry to use as a filtering region. None may be passed indicating that the current spatial filter should be cleared, but no new one instituted. @@ -428,16 +426,16 @@ For more details: - :cpp:func:`OGR_L_SetSpatialFilterRectEx` Parameters ------------ -iGeomField: int, optional +---------- +iGeomField : int, optional index of the geometry field on which the spatial filter operates. -minx: float +minx : float the minimum X coordinate for the rectangular region. -miny: float +miny : float the minimum Y coordinate for the rectangular region. -maxx: float +maxx : float the maximum X coordinate for the rectangular region. -maxy: float +maxy : float the maximum Y coordinate for the rectangular region. "; @@ -454,8 +452,8 @@ Flush pending changes to disk. For more details: :cpp:func:`OGR_L_SyncToDisk` Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` if no error occurs (even if nothing is done) or an error code. "; @@ -466,13 +464,13 @@ Delete feature from layer. For more details: :cpp:func:`OGR_L_DeleteFeature` Parameters ------------ -fid: int +---------- +fid : int The feature id to be deleted from the layer Returns --------- -int: +------- +int :py:const:`osgeo.ogr.OGRERR_NONE` if the operation works, otherwise an appropriate error code (e.g :py:const:`osgeo.ogr.OGRERR_NON_EXISTING_FEATURE`) @@ -490,8 +488,8 @@ used as the FID column, or \'\' if not supported. For more details: :cpp:func:`OGR_L_GetFIDColumn` Returns --------- -str: +------- +str fid column name. "; @@ -502,8 +500,8 @@ used as the geometry column, or \'\' if not supported. For more details: :cpp:func:`OGR_L_GetGeometryColumn` Returns --------- -str: +------- +str geometry column name. "; @@ -531,8 +529,8 @@ Return the layer name. For more details: :cpp:func:`OGR_L_GetName` Returns --------- -str: +------- +str The layer name "; @@ -542,8 +540,8 @@ Return the layer geometry type. For more details: :cpp:func:`OGR_L_GetGeomType` Returns --------- -int: +------- +int The geometry type code. The types can be found with 'osgeo.ogr.wkb' prefix. For example :py:const:`osgeo.ogr.wkbPolygon`. "; @@ -555,14 +553,14 @@ layer. For more details: :cpp:func:`OGR_L_SetIgnoredFields` Parameters ------------ -options: list[str] +---------- +options : list[str] A list of field names. If an empty list is passed, the ignored list is cleared. Returns ------- -int: +int :py:const:`osgeo.ogr.OGRERR_NONE` if all field names have been resolved (even if the driver does not support this method) "; @@ -574,23 +572,23 @@ Intersection of two layers. For more details: :cpp:func:`OGR_L_Intersection` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -603,23 +601,23 @@ For more details: :cpp:func:`OGR_L_Union` The first geometry field is always used. Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -630,23 +628,23 @@ Symmetrical difference of two layers. For more details: :cpp:func:`OGR_L_SymDifference` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -657,23 +655,23 @@ Identify the features of this layer with the ones from the identity layer. For more details: :cpp:func:`OGR_L_Identity` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -684,23 +682,23 @@ Update this layer with features from the update layer. For more details: :cpp:func:`OGR_L_Update` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : Callable, optional a GDALProgressFunc() compatible callback function for reporting progress or None. -callback_data: +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -711,23 +709,23 @@ Clip off areas that are not covered by the method layer. For more details: :cpp:func:`OGR_L_Clip` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -738,23 +736,23 @@ Remove areas that are covered by the method layer. For more details: :cpp:func:`OGR_L_Erase` Parameters ------------ -method_layer: Layer +---------- +method_layer : Layer the method layer. Should not be None. -result_layer: Layer +result_layer : Layer the layer where the features resulting from the operation are inserted. Should not be None. -options: list[str], optional +options : list[str], optional List of options (empty list is allowed). For example [\"PROMOTE_TO_MULTI=YES\"]. -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for - reporting progress or None. -callback_data: + reporting progress or ``None``. +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -int: +int An error code if there was an error or the execution was interrupted, :py:const:`osgeo.ogr.OGRERR_NONE` otherwise. "; @@ -765,22 +763,22 @@ Get actual geometry types found in features. For more details: :cpp:func:`OGR_L_GetGeometryTypes` Parameters ------------ -geom_field: int, optional +---------- +geom_field : int, optional index of the geometry field -flags: int, optional +flags : int, optional 0, or a combination of :py:const:`osgeo.ogr.GGT_COUNT_NOT_NEEDED`, :py:const:`osgeo.ogr.GGT_STOP_IF_MIXED` and :py:const:`osgeo.ogr.GGT_GEOMCOLLECTIONZ_TINZ` -callback: Callable, optional +callback : callable, optional a GDALProgressFunc() compatible callback function for cancellation or None. -callback_data: +callback_data : any Argument to be passed to 'callback'. May be None. Returns ------- -dict: +dict A dictionary whose keys are :py:const:`osgeo.ogr.wkbXXXX` constants and values the corresponding number of geometries of that type in the layer. "; @@ -792,8 +790,8 @@ For more details: :cpp:func:`OGR_L_GetDataset` Returns ------- -Dataset: - Dataset or None +Dataset or None + A dataset if successful, or ``None`` on failure. "; } diff --git a/swig/include/python/docs/osr_docs.i b/swig/include/python/docs/osr_docs.i index eb139579918d..1352e6b3b06d 100644 --- a/swig/include/python/docs/osr_docs.i +++ b/swig/include/python/docs/osr_docs.i @@ -15,6 +15,5 @@ options : CoordinateTransformationOptions Returns ------- CoordinateTransformation - "; diff --git a/swig/include/python/docs/osr_spatialreference_docs.i b/swig/include/python/docs/osr_spatialreference_docs.i index 19e26f151701..2bb325245592 100644 --- a/swig/include/python/docs/osr_spatialreference_docs.i +++ b/swig/include/python/docs/osr_spatialreference_docs.i @@ -6,7 +6,7 @@ unless exactly one of the following parameters is provided. Parameters ---------- -name : str / dict, optional +name : str or dict, optional SRS description in a format understood by :py:meth:`SetFromUserInput`. epsg : int, optional EPSG CRS code, as understood by :py:meth:`ImportFromEPSG` @@ -77,7 +77,7 @@ See :cpp:func:`OGRSpatialReference::exportToPROJJSON`. Parameters ---------- -options : list/dict +options : list or dict Options to control the format of the output. See :cpp:func:`OGRSpatialReference::exportToPROJJSON`. Returns @@ -117,7 +117,8 @@ target_key : str Returns ------- -str or ``None`` on failure +str or None + Returns a string on success or ``None`` on failure. Examples -------- @@ -808,7 +809,7 @@ See :cpp:func:`OGRSpatialReference::IsSame`. Parameters ---------- rhs : SpatialReference -options : list/dict +options : list or dict Returns ------- @@ -826,7 +827,7 @@ See :cpp:func:`OGRSpatialReference::IsSameGeogCS`. Parameters ---------- rhs : SpatialReference -options : list/dict +options : list or dict Returns ------- @@ -844,7 +845,7 @@ See :cpp:func:`OGRSpatialReference::IsSameVertCS`. Parameters ---------- rhs : SpatialReference -options : list/dict +options : list or dict Returns ------- @@ -877,8 +878,8 @@ See :cpp:func:`OGRSpatialReference::StripVertical`. Returns ------- -OGRErr: - :py:const:`OGRERR_NONE` if the operation succeeds +int + :py:const:`OGRERR_NONE` on success, or an error code on failure "; } diff --git a/swig/include/python/gdal_python.i b/swig/include/python/gdal_python.i index 881ddb765eb5..5cdd53d4840a 100644 --- a/swig/include/python/gdal_python.i +++ b/swig/include/python/gdal_python.i @@ -1130,9 +1130,9 @@ void wrapper_VSIGetMemFileBuffer(const char *utf8_path, GByte **out, vsi_l_offse resample_alg : int, default = :py:const:`gdal.GRIORA_NearestNeighbour`. Specifies the resampling algorithm to use when the size of the read window and the buffer are not equal. - callback : function, optional + callback : callable, optional A progress callback function - callback_data: optional + callback_data : any, optional Optional data to be passed to callback function Returns @@ -1200,14 +1200,14 @@ void wrapper_VSIGetMemFileBuffer(const char *utf8_path, GByte **out, vsi_l_offse be written. This would be zero to start from the top side. resample_alg : int, default = :py:const:`gdal.GRIORA_NearestNeighbour` Resampling algorithm. Placeholder argument, not currently supported. - callback : function, optional + callback : callable, optional A progress callback function - callback_data: optional + callback_data : any, optional Optional data to be passed to callback function Returns ------- - int: + int Error code, or ``gdal.CE_None`` if no error occurred. """ from osgeo import gdal_array @@ -1324,8 +1324,8 @@ void wrapper_VSIGetMemFileBuffer(const char *utf8_path, GByte **out, vsi_l_offse %} %feature("shadow") ComputeStatistics %{ -def ComputeStatistics(self, *args, **kwargs) -> "CPLErr": - """ComputeStatistics(Band self, bool approx_ok, callback=None, callback_data=None) -> CPLErr +def ComputeStatistics(self, *args, **kwargs): + """ComputeStatistics(Band self, bool approx_ok, callback=None, callback_data=None) Compute image statistics. See :cpp:func:`GDALRasterBand::ComputeStatistics`. @@ -1335,9 +1335,9 @@ def ComputeStatistics(self, *args, **kwargs) -> "CPLErr": approx_ok : bool If ``True``, compute statistics based on overviews or a subset of tiles. - callback : function, optional + callback : callable, optional A progress callback function - callback_data: optional + callback_data : any, optional Optional data to be passed to callback function Returns @@ -1382,7 +1382,7 @@ def GetNoDataValue(self): Returns ------- - float/int + float or int The nodata value, or ``None`` if it has not been set. """ @@ -1397,8 +1397,8 @@ def GetNoDataValue(self): %feature("shadow") SetNoDataValue %{ -def SetNoDataValue(self, value) -> "CPLErr": - """SetNoDataValue(Band self, value) -> CPLErr +def SetNoDataValue(self, value): + """SetNoDataValue(Band self, value) Set the nodata value for this band. Unlike :cpp:func:`GDALRasterBand::SetNoDataValue`, this @@ -1406,12 +1406,12 @@ def SetNoDataValue(self, value) -> "CPLErr": Parameters ---------- - value : float/int + value : float or int The nodata value to set Returns ------- - int: + int :py:const:`CE_None` on success or :py:const:`CE_Failure` on failure. """ @@ -1684,9 +1684,9 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize, resample_alg : int, default = :py:const:`gdal.GRIORA_NearestNeighbour`. Specifies the resampling algorithm to use when the size of the read window and the buffer are not equal. - callback : function, optional + callback : callable, optional A progress callback function - callback_data: optional + callback_data : any, optional Optional data to be passed to callback function band_list : list, optional Indexes of bands from which data should be read. By default, @@ -1776,14 +1776,14 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize, ``(ny, nx, nbands)``. resample_alg : int, default = :py:const:`gdal.GRIORA_NearestNeighbour` Resampling algorithm. Placeholder argument, not currently supported. - callback : function, optional + callback : callable, optional A progress callback function - callback_data: optional + callback_data : any, optional Optional data to be passed to callback function Returns ------- - int: + int Error code, or ``gdal.CE_None`` if no error occurred. Examples @@ -2005,12 +2005,13 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize, Parameters ---------- - value : int/str + value : int or str Name or 0-based index of the layer to delete. Returns ------- - ogr.Layer, or ``None`` on error + Layer + A layer if successful, or ``None`` on error. """ _WarnIfUserHasNotSpecifiedIfUsingOgrExceptions() @@ -2028,7 +2029,7 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize, Parameters ---------- - value : int/str + value : int or str Name or 0-based index of the layer to delete. Returns @@ -2059,8 +2060,8 @@ CPLErr ReadRaster1( double xoff, double yoff, double xsize, double ysize, ---------- gcps : list a list of :py:class:`GCP` objects - wkt_or_spatial_ref : str/osr.SpatialReference - spatial reference of the GCPs + wkt_or_spatial_ref : str or SpatialReference + spatial reference of the GCPs as a string, or a :py:class:`osr.SpatialReference` """ if isinstance(wkt_or_spatial_ref, str): @@ -2238,23 +2239,23 @@ def ExecuteSQL(self, statement, spatialFilter=None, dialect="", keep_ref_on_ds=F Parameters ---------- - statement: + statement : str the SQL statement to execute (e.g "SELECT * FROM layer") - spatialFilter: + spatialFilter : any a geometry which represents a spatial filter. Can be None - dialect: + dialect : str allows control of the statement dialect. If set to None or empty string, the OGR SQL engine will be used, except for RDBMS drivers that will use their dedicated SQL engine, unless OGRSQL is explicitly passed as the dialect. The SQLITE dialect can also be used. - keep_ref_on_ds: + keep_ref_on_ds : bool whether the returned layer should keep a (strong) reference on the current dataset. Cf example 2 for a use case. Returns ------- - ogr.Layer: - a ogr.Layer containing the results of the query, that will be + Layer + a layer containing the results of the query, that will be automatically released when the context manager goes out of scope. Examples @@ -2329,7 +2330,7 @@ def ReleaseResultSet(self, sql_lyr): Parameters ---------- - sql_lyr: + sql_lyr : Layer :py:class:`ogr.Layer` got with :py:meth:`ExecuteSQL` """ @@ -2390,7 +2391,7 @@ def ReleaseResultSet(self, sql_lyr): Returns ------- - int: + int Error code, or ``gdal.CE_None`` if no error occurred. """ from osgeo import gdal_array @@ -2889,7 +2890,8 @@ def Open(self, utf8_path, update=False): Returns ------- - Dataset, or None on error + Dataset or None + ``None`` on error """ return OpenEx(utf8_path, OF_VECTOR | (OF_UPDATE if update else 0), @@ -2917,7 +2919,7 @@ def InfoOptions(options=None, format='text', deserialize=True, listMDD=False, showFileList=True, allMetadata=False, extraMDDomains=None, wktFormat=None): """ Create a InfoOptions() object that can be passed to gdal.Info() - options can be be an array of strings, a string or let empty and filled from other keywords.""" + options can be an array of strings, a string or let empty and filled from other keywords.""" options = [] if options is None else options @@ -2978,9 +2980,9 @@ def Info(ds, **kwargs): Parameters ---------- - ds: + ds : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.InfoOptions(), string or array of strings other keywords arguments of gdal.InfoOptions(). If options is provided as a gdal.InfoOptions() object, other keywords are ignored. @@ -3015,31 +3017,31 @@ def VectorInfoOptions(options=None, where=None, wktFormat=None): """ Create a VectorInfoOptions() object that can be passed to gdal.VectorInfo() - options can be be an array of strings, a string or let empty and filled from other keywords. + options can be an array of strings, a string or let empty and filled from other keywords. Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any "text" or "json" - deserialize: + deserialize : any if JSON output should be returned as a Python dictionary. Otherwise as a serialized representation. - SQLStatement: + SQLStatement : str SQL statement to apply to the source dataset - SQLDialect: + SQLDialect : str SQL dialect ('OGRSQL', 'SQLITE', ...) - where: + where : str WHERE clause to apply to source layer(s) - layers: + layers : any list of layers of interest - featureCount: + featureCount : any whether to compute and display the feature count - extent: + extent : any whether to compute and display the layer extent. Can also be set to the string '3D' to request a 3D extent - dumpFeatures: + dumpFeatures : any set to True to get the dump of all features - limit: + limit : int maximum number of features to read per layer """ @@ -3097,9 +3099,9 @@ def VectorInfo(ds, **kwargs): Parameters ---------- - ds: + ds : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.VectorInfoOptions(), string or array of strings other keywords arguments of gdal.VectorInfoOptions(). If options is provided as a gdal.VectorInfoOptions() object, other keywords are ignored. @@ -3123,7 +3125,7 @@ def VectorInfo(ds, **kwargs): def MultiDimInfoOptions(options=None, detailed=False, array=None, arrayoptions=None, limit=None, as_text=False): """ Create a MultiDimInfoOptions() object that can be passed to gdal.MultiDimInfo() - options can be be an array of strings, a string or let empty and filled from other keywords.""" + options can be an array of strings, a string or let empty and filled from other keywords.""" options = [] if options is None else options @@ -3149,9 +3151,9 @@ def MultiDimInfo(ds, **kwargs): Parameters ---------- - ds: + ds : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.MultiDimInfoOptions(), string or array of strings other keywords arguments of gdal.MultiDimInfoOptions(). If options is provided as a gdal.MultiDimInfoOptions() object, other keywords are ignored. @@ -3219,77 +3221,77 @@ def TranslateOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : str output format ("GTiff", etc...) - outputType: + outputType : any output type (gdalconst.GDT_Byte, etc...) - bandList: + bandList : any array of band numbers (index start at 1) - maskBand: + maskBand : any mask band to generate or not ("none", "auto", "mask", 1, ...) - width: + width : int width of the output raster in pixel - height: + height : int height of the output raster in pixel - widthPct: + widthPct : any width of the output raster in percentage (100 = original width) - heightPct: + heightPct : any height of the output raster in percentage (100 = original height) - xRes: + xRes : int output horizontal resolution - yRes: + yRes : int output vertical resolution - creationOptions: + creationOptions : list or dict list or dict of creation options - srcWin: + srcWin : any subwindow in pixels to extract: [left_x, top_y, width, height] - projWin: + projWin : any subwindow in projected coordinates to extract: [ulx, uly, lrx, lry] - projWinSRS: + projWinSRS : any SRS in which projWin is expressed - strict: + strict : any strict mode - unscale: + unscale : any unscale values with scale and offset metadata - scaleParams: + scaleParams : any list of scale parameters, each of the form [src_min,src_max] or [src_min,src_max,dst_min,dst_max] - exponents: + exponents : any list of exponentiation parameters - outputBounds: + outputBounds : any assigned output bounds: [ulx, uly, lrx, lry] - outputGeotransform: + outputGeotransform : any assigned geotransform matrix (array of 6 values) (mutually exclusive with outputBounds) - metadataOptions: + metadataOptions : any list or dict of metadata options - outputSRS: + outputSRS : any assigned output SRS - nogcp: + nogcp : any ignore GCP in the raster - GCPs: + GCPs : any list of GCPs - noData: + noData : any nodata value (or "none" to unset it) - rgbExpand: + rgbExpand : any Color palette expansion mode: "gray", "rgb", "rgba" - stats: + stats : any whether to calculate statistics - rat: + rat : any whether to write source RAT - xmp: + xmp : any whether to copy XMP metadata - resampleAlg: + resampleAlg : any resampling mode - overviewLevel: + overviewLevel : any To specify which overview level of source files must be used - colorInterpretation: + colorInterpretation : any Band color interpretation, as a single value or a list, of the following values ("red", "green", "blue", "alpha", "grey", "undefined", etc.) or their GCI_xxxx symbolic names - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback - domainMetadataOptions: + domainMetadataOptions : any list or dict of domain-specific metadata options errorIfWindowOutsideSource : {True, False, "partially", "completely"}, default=True raise an error if the requested window is partially or completely outside the source dataset. ("True" is a synonym for "partially"). This corresponds to the ``-epo`` and ``-eco`` options of ``gdal_translate``. @@ -3434,11 +3436,11 @@ def Translate(destName, srcDS, **kwargs): Parameters ---------- - destName: + destName : str Output dataset name - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.TranslateOptions(), string or array of strings other keywords arguments of gdal.TranslateOptions(). If options is provided as a gdal.TranslateOptions() object, other keywords are ignored. @@ -3489,96 +3491,96 @@ def WarpOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : str output format ("GTiff", etc...) - srcBands: + srcBands : any list of source band numbers (between 1 and the number of input bands) - dstBands: + dstBands : any list of output band numbers - outputBounds: + outputBounds : any output bounds as (minX, minY, maxX, maxY) in target SRS - outputBoundsSRS: + outputBoundsSRS : any SRS in which output bounds are expressed, in the case they are not expressed in dstSRS - xRes: + xRes : any output resolution in target SRS - yRes: + yRes : any output resolution in target SRS - targetAlignedPixels: + targetAlignedPixels : any whether to force output bounds to be multiple of output resolution - width: + width : int width of the output raster in pixel - height: + height : int height of the output raster in pixel - srcSRS: + srcSRS : any source SRS - dstSRS: + dstSRS : any output SRS - coordinateOperation: + coordinateOperation : any coordinate operation as a PROJ string or WKT string - srcAlpha: + srcAlpha : any whether to force the last band of the input dataset to be considered as an alpha band. If set to False, source alpha warping will be disabled. - dstAlpha: + dstAlpha : any whether to force the creation of an output alpha band - outputType: + outputType : any output type (gdalconst.GDT_Byte, etc...) - workingType: + workingType : any working type (gdalconst.GDT_Byte, etc...) - warpOptions: + warpOptions : any list or dict of warping options. For a list of available options, see :cpp:member:`GDALWarpOptions::papszWarpOptions`. - errorThreshold: + errorThreshold : any error threshold for approximation transformer (in pixels) - warpMemoryLimit: + warpMemoryLimit : any size of working buffer in MB - resampleAlg: + resampleAlg : any resampling mode - creationOptions: + creationOptions : list or dict list or dict of creation options - srcNodata: + srcNodata : any source nodata value(s) - dstNodata: + dstNodata : any output nodata value(s) - multithread: + multithread : any whether to multithread computation and I/O operations - tps: + tps : any whether to use Thin Plate Spline GCP transformer - rpc: + rpc : any whether to use RPC transformer - geoloc: + geoloc : any whether to use GeoLocation array transformer - polynomialOrder: + polynomialOrder : any order of polynomial GCP interpolation - transformerOptions: + transformerOptions : any list or dict of transformer options - cutlineDSName: + cutlineDSName : any cutline dataset name (mutually exclusive with cutlineWKT) - cutlineWKT: + cutlineWKT : any cutline WKT geometry (POLYGON or MULTIPOLYGON) (mutually exclusive with cutlineDSName) - cutlineSRS: + cutlineSRS : any set/override cutline SRS - cutlineLayer: + cutlineLayer : any cutline layer name - cutlineWhere: + cutlineWhere : any cutline WHERE clause - cutlineSQL: + cutlineSQL : any cutline SQL statement - cutlineBlend: + cutlineBlend : any cutline blend distance in pixels - cropToCutline: + cropToCutline : any whether to use cutline extent for output bounds - copyMetadata: + copyMetadata : any whether to copy source metadata - metadataConflictValue: + metadataConflictValue : any metadata data conflict value - setColorInterpretation: + setColorInterpretation : any whether to force color interpretation of input bands to output bands - overviewLevel: + overviewLevel : any To specify which overview level of source files must be used - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ @@ -3733,16 +3735,16 @@ def Warp(destNameOrDestDS, srcDSOrSrcDSTab, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object. If passed as a dataset name, a potentially existing output dataset of the same name will be overwritten. To update an existing output dataset, it must be passed as a dataset object. - srcDSOrSrcDSTab: + srcDSOrSrcDSTab : any an array of Dataset objects or filenames, or a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.WarpOptions(), string or array of strings, other keywords arguments of gdal.WarpOptions(). If options is provided as a gdal.WarpOptions() object, other keywords are ignored. @@ -3821,97 +3823,97 @@ def VectorTranslateOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other + options : any + can be an array of strings, a string or let empty and filled from other keywords. - format: + format : str format ("ESRI Shapefile", etc...) - accessMode: + accessMode : any None for creation, 'update', 'append', 'upsert', 'overwrite' - srcSRS: + srcSRS : any source SRS - dstSRS: + dstSRS : any output SRS (with reprojection if reproject = True) - coordinateOperation: + coordinateOperation : any coordinate operation as a PROJ string or WKT string - coordinateOperationOptions: + coordinateOperationOptions : any list or dict of coordinate operation options (ALLOW_BALLPARK=NO, ONLY_BEST=YES, WARN_ABOUT_DIFFERENT_COORD_OP=NO) - reproject: + reproject : any whether to do reprojection - SQLStatement: + SQLStatement : any SQL statement to apply to the source dataset - SQLDialect: + SQLDialect : any SQL dialect ('OGRSQL', 'SQLITE', ...) - where: + where : any WHERE clause to apply to source layer(s) - selectFields: + selectFields : any list of fields to select - addFields: + addFields : any whether to add new fields found in source layers (to be used with accessMode == 'append' or 'upsert') - relaxedFieldNameMatch: + relaxedFieldNameMatch : any Do field name matching between source and existing target layer in a more relaxed way if the target driver has an implementation for it. - forceNullable: + forceNullable : any whether to drop NOT NULL constraints on newly created fields - emptyStrAsNull: + emptyStrAsNull : any whether to treat empty string values as NULL - spatFilter: + spatFilter : any spatial filter as (minX, minY, maxX, maxY) bounding box - spatSRS: + spatSRS : any SRS in which the spatFilter is expressed. If not specified, it is assumed to be the one of the layer(s) - datasetCreationOptions: + datasetCreationOptions : any list or dict of dataset creation options - layerCreationOptions: + layerCreationOptions : any list or dict of layer creation options - layers: + layers : any list of layers to convert - layerName: + layerName : any output layer name - geometryType: + geometryType : any output layer geometry type ('POINT', ....). May be an array of strings when using a special value like 'PROMOTE_TO_MULTI', 'CONVERT_TO_LINEAR', 'CONVERT_TO_CURVE' combined with another one or a geometry type. - dim: + dim : any output dimension ('XY', 'XYZ', 'XYM', 'XYZM', 'layer_dim') - transactionSize: + transactionSize : any number of features to save per transaction (default 100 000). Increase the value for better performance when writing into DBMS drivers that have transaction support. Set to "unlimited" to load the data into a single transaction. - clipSrc: + clipSrc : any clip geometries to the specified bounding box (expressed in source SRS), WKT geometry (POLYGON or MULTIPOLYGON), from a datasource or to the spatial extent of the -spat option if you use the "spat_extent" keyword. When specifying a datasource, you will generally want to use it in combination with the clipSrcLayer, clipSrcWhere or clipSrcSQL options. - clipSrcSQL: + clipSrcSQL : any select desired geometries using an SQL query instead. - clipSrcLayer: + clipSrcLayer : any select the named layer from the source clip datasource. - clipSrcWhere: + clipSrcWhere : any restrict desired geometries based on attribute query. - clipDst: + clipDst : any clip geometries after reprojection to the specified bounding box (expressed in dest SRS), WKT geometry (POLYGON or MULTIPOLYGON) or from a datasource. When specifying a datasource, you will generally want to use it in combination of the clipDstLayer, clipDstWhere or clipDstSQL options. - clipDstSQL: + clipDstSQL : any select desired geometries using an SQL query instead. - clipDstLayer: + clipDstLayer : any select the named layer from the destination clip datasource. - clipDstWhere: + clipDstWhere : any restrict desired geometries based on attribute query. - simplifyTolerance: + simplifyTolerance : any distance tolerance for simplification. The algorithm used preserves topology per feature, in particular for polygon geometries, but not for a whole layer. - segmentizeMaxDist: + segmentizeMaxDist : any maximum distance between consecutive nodes of a line geometry - makeValid: + makeValid : any run MakeValid() on geometries - skipInvalid: + skipInvalid : any whether to skip features with invalid geometries regarding the rules of the Simple Features specification. - mapFieldType: + mapFieldType : any converts any field of the specified type to another type. Valid types are: Integer, Integer64, Real, String, Date, Time, DateTime, Binary, IntegerList, Integer64List, RealList, StringList. Types can also include subtype between @@ -3920,38 +3922,38 @@ def VectorTranslateOptions(options=None, format=None, the CAST operator of OGR SQL, that may avoid typing a long SQL query. Note that this does not influence the field types used by the source driver, and is only an afterwards conversion. - explodeCollections: + explodeCollections : any produce one feature for each geometry in any kind of geometry collection in the source file, applied after any -sql option. This option is not compatible with preserveFID but a SQLStatement (e.g. SELECT fid AS original_fid, * FROM ...) can be used to store the original FID if needed. - preserveFID: + preserveFID : any Use the FID of the source features instead of letting the output driver automatically assign a new one (for formats that require a FID). If not in append mode, this behavior is the default if the output driver has a FID layer creation option, in which case the name of the source FID column will be used and source feature IDs will be attempted to be preserved. This behavior can be disabled by setting -unsetFid. This option is not compatible with explodeCollections - zField: + zField : any name of field to use to set the Z component of geometries - resolveDomains: + resolveDomains : any whether to create an additional field for each field associated with a coded field domain. - skipFailures: + skipFailures : any whether to skip failures - limit: + limit : int maximum number of features to read per layer - xyRes: + xyRes : any Geometry X,Y coordinate resolution. Numeric value, or numeric value suffixed with " m", " mm" or "deg". - zRes: + zRes : any Geometry Z coordinate resolution. Numeric value, or numeric value suffixed with " m" or " mm". - mRes: + mRes : any Geometry M coordinate resolution. Numeric value. - setCoordPrecision: + setCoordPrecision : any Set to False to unset the geometry coordinate precision. - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ @@ -4168,7 +4170,7 @@ def VectorTranslate(destNameOrDestDS, srcDS, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object If passed as a dataset name, a potentially existing output dataset of @@ -4177,9 +4179,9 @@ def VectorTranslate(destNameOrDestDS, srcDS, **kwargs): also controls, at the layer level, if existing layers must be overwritten or updated. - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.VectorTranslateOptions(), string or array of strings, other keywords arguments of gdal.VectorTranslateOptions(). If options is provided as a gdal.VectorTranslateOptions() object, @@ -4212,51 +4214,51 @@ def DEMProcessingOptions(options=None, colorFilename=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - colorFilename: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + colorFilename : any (mandatory for "color-relief") name of file that contains palette definition for the "color-relief" processing. - format: + format : any output format ("GTiff", etc...) - creationOptions: + creationOptions : any list or dict of creation options - computeEdges: + computeEdges : any whether to compute values at raster edges. - alg: + alg : any 'Horn' (default) or 'ZevenbergenThorne' for hillshade, slope or aspect. 'Wilson' (default) or 'Riley' for TRI - band: + band : any source band number to use - zFactor: + zFactor : any (hillshade only) vertical exaggeration used to pre-multiply the elevations. - scale: + scale : any ratio of vertical units to horizontal. - xscale: + xscale : any Ratio of vertical units to horizontal X axis units. - yscale: + yscale : any Ratio of vertical units to horizontal Y axis units. - azimuth: + azimuth : any (hillshade only) azimuth of the light, in degrees. 0 if it comes from the top of the raster, 90 from the east, ... The default value, 315, should rarely be changed as it is the value generally used to generate shaded maps. - altitude: + altitude : any (hillshade only) altitude of the light, in degrees. 90 if the light comes from above the DEM, 0 if it is raking light. - combined: + combined : any (hillshade only) whether to compute combined shading, a combination of slope and oblique shading. Only one of combined, multiDirectional and igor can be specified. - multiDirectional: + multiDirectional : any (hillshade only) whether to compute multi-directional shading. Only one of combined, multiDirectional and igor can be specified. - igor: + igor : any (hillshade only) whether to use Igor's hillshading from Maperitive. Only one of combined, multiDirectional and igor can be specified. - slopeFormat: + slopeFormat : any (slope only) "degree" or "percent". - trigonometric: + trigonometric : any (aspect only) whether to return trigonometric angle instead of azimuth. Thus 0deg means East, 90deg North, 180deg West, 270deg South. - zeroForFlat: + zeroForFlat : any (aspect only) whether to return 0 for flat areas with slope=0, instead of -9999. - addAlpha: + addAlpha : any adds an alpha band to the output file (only for processing = 'color-relief') - colorSelection: + colorSelection : any (color-relief only) Determines how color entries are selected from an input value. Can be "nearest_color_entry", "exact_color_entry" or "linear_interpolation". Defaults to "linear_interpolation" - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ # Only used for tests @@ -4326,13 +4328,13 @@ def DEMProcessing(destName, srcDS, processing, **kwargs): Parameters ---------- - destName: + destName : any Output dataset name - srcDS: + srcDS : any a Dataset object or a filename - processing: + processing : any one of "hillshade", "slope", "aspect", "color-relief", "TRI", "TPI", "Roughness" - kwargs: + **kwargs : any options: return of gdal.DEMProcessingOptions(), string or array of strings, other keywords arguments of gdal.DEMProcessingOptions(). If options is provided as a gdal.DEMProcessingOptions() object, @@ -4364,29 +4366,29 @@ def NearblackOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("GTiff", etc...) - creationOptions: + creationOptions : any list or dict of creation options - white: + white : any whether to search for nearly white (255) pixels instead of nearly black pixels. - colors: + colors : any list of colors to search for, e.g. ((0,0,0),(255,255,255)). The pixels that are considered as the collar are set to 0 - maxNonBlack: + maxNonBlack : any number of non-black (or other searched colors specified with white / colors) pixels that can be encountered before the giving up search inwards. Defaults to 2. - nearDist: + nearDist : any select how far from black, white or custom colors the pixel values can be and still considered near black, white or custom color. Defaults to 15. - setAlpha: + setAlpha : any adds an alpha band to the output file. - setMask: + setMask : any adds a mask band to the output file. - alg: + alg : any "twopasses" (default), or "floodfill" - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ # Only used for tests @@ -4436,16 +4438,16 @@ def Nearblack(destNameOrDestDS, srcDS, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object If passed as a dataset name, a potentially existing output dataset of the same name will be overwritten. To update an existing output dataset, it must be passed as a dataset object. - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.NearblackOptions(), string or array of strings, other keywords arguments of gdal.NearblackOptions(). If options is provided as a gdal.NearblackOptions() object, other keywords are ignored. @@ -4487,49 +4489,49 @@ def GridOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("GTiff", etc...) - outputType: + outputType : any output type (gdalconst.GDT_Byte, etc...) - width: + width : any width of the output raster in pixel - height: + height : any height of the output raster in pixel - creationOptions: + creationOptions : any list or dict of creation options - outputBounds: + outputBounds : any assigned output bounds: [ulx, uly, lrx, lry] - outputSRS: + outputSRS : any assigned output SRS - noData: + noData : any nodata value - algorithm: + algorithm : any e.g "invdist:power=2.0:smoothing=0.0:radius1=0.0:radius2=0.0:angle=0.0:max_points=0:min_points=0:nodata=0.0" - layers: + layers : any list of layers to convert - SQLStatement: + SQLStatement : any SQL statement to apply to the source dataset - where: + where : any WHERE clause to apply to source layer(s) - spatFilter: + spatFilter : any spatial filter as (minX, minY, maxX, maxY) bounding box - zfield: + zfield : any Identifies an attribute field on the features to be used to get a Z value from. This value overrides Z value read from feature geometry record. - z_increase: + z_increase : any Addition to the attribute field on the features to be used to get a Z value from. The addition should be the same unit as Z value. The result value will be Z value + Z increase value. The default value is 0. - z_multiply: + z_multiply : any Multiplication ratio for Z field. This can be used for shift from e.g. foot to meters or from elevation to deep. The result value will be (Z value + Z increase value) * Z multiply value. The default value is 1. - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ # Only used for tests @@ -4588,11 +4590,11 @@ def Grid(destName, srcDS, **kwargs): Parameters ---------- - destName: + destName : any Output dataset name - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.GridOptions(), string or array of strings, other keywords arguments of gdal.GridOptions() If options is provided as a gdal.GridOptions() object, other keywords are ignored. @@ -4634,51 +4636,51 @@ def ContourOptions( Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("ESRI Shapefile", etc...) - band: + band : any band number to use (default = 1) - elevationName: + elevationName : any name of the attribute in which to put the elevation. If not provided no elevation attribute is attached. Ignored in polygonal contouring (polygonize) mode. - minName: + minName : any name for the attribute in which to put the minimum elevation of contour polygon. If not provided no minimum elevation attribute is attached. Ignored in default line contouring mode. - maxName: + maxName : any name for the attribute in which to put the maximum elevation of contour polygon. If not provided no maximum elevation attribute is attached. Ignored in default line contouring mode. - with3d: + with3d : any Force production of 3D vectors instead of 2D. Includes elevation at every vertex. - srcNodata: + srcNodata : any Input pixel value to treat as "nodata". - offset: + offset : any Offset to apply to the elevation values. - datasetCreationOptions: + datasetCreationOptions : any List or dict of dataset creation options. - layerCreationOptions: + layerCreationOptions : any List or dict of layer creation options. - interval: + interval : any Elevation interval between contours. Must specify either "interval" or "fixedLevels" or "exponentialBase". - fixedLevels: + fixedLevels : any Name one or more "fixed levels" to extract. Must specify either "interval" or "fixedLevels" or "exponentialBase". - exponentialBase: + exponentialBase : any Generate levels on an exponential scale: base ^ k, for k an integer. Must specify either. Must specify either "interval" or "fixedLevels" or "exponentialBase". - layerName: + layerName : any Name for the output vector layer, defaults to "contour". - polygonize: + polygonize : any Produce polygons instead of lines (default = False). - groupTransactions: + groupTransactions : any Group n features per transaction (default 100 000). Increase the value for better performance when writing into DBMS drivers that have transaction support. n can be set to unlimited to load the data into a single transaction. If set to 0, no explicit transaction is done. - callback: + callback : any Callback method. - callback_data: + callback_data : any User data for callback. """ @@ -4749,16 +4751,16 @@ def Contour(destNameOrDestDS, srcDS, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object If passed as a dataset name, a potentially existing output dataset of the same name will be overwritten. To update an existing output dataset, it must be passed as a dataset object. - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.ContourOptions(), string or array of strings, other keywords arguments of gdal.ContourOptions(). If options is provided as a gdal.ContourOptions() object, other keywords are ignored. @@ -4796,70 +4798,72 @@ def RasterizeOptions(options=None, format=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("GTiff", etc...) - outputType: + outputType : any output type (gdalconst.GDT_Byte, etc...) - creationOptions: + creationOptions : any list or dict of creation options - outputBounds: - assigned output bounds: + outputBounds : any + assigned output bounds : any [minx, miny, maxx, maxy] - outputSRS: + outputSRS : any assigned output SRS - transformerOptions: + transformerOptions : any list or dict of transformer options - width: + width : any width of the output raster in pixel - height: + height : any height of the output raster in pixel - xRes, yRes: + xRes : any + output resolution in target SRS + yRes : any output resolution in target SRS - targetAlignedPixels: + targetAlignedPixels : any whether to force output bounds to be multiple of output resolution - noData: + noData : any nodata value - initValues: + initValues : any Value or list of values to pre-initialize the output image bands with. However, it is not marked as the nodata value in the output file. If only one value is given, the same value is used in all the bands. - bands: + bands : any list of output bands to burn values into - inverse: + inverse : any whether to invert rasterization, i.e. burn the fixed burn value, or the burn value associated with the first feature into all parts of the image not inside the provided a polygon. - allTouched: + allTouched : any whether to enable the ALL_TOUCHED rasterization option so that all pixels touched by lines or polygons will be updated, not just those on the line render path, or whose center point is within the polygon. - burnValues: + burnValues : any list of fixed values to burn into each band for all objects. Exclusive with attribute. - attribute: + attribute : any identifies an attribute field on the features to be used for a burn-in value. The value will be burned into all output bands. Exclusive with burnValues. - useZ: + useZ : any whether to indicate that a burn value should be extracted from the "Z" values of the feature. These values are added to the burn value given by burnValues or attribute if provided. As of now, only points and lines are drawn in 3D. - layers: + layers : any list of layers from the datasource that will be used for input features. - SQLStatement: + SQLStatement : any SQL statement to apply to the source dataset - SQLDialect: + SQLDialect : any SQL dialect ('OGRSQL', 'SQLITE', ...) - where: + where : any WHERE clause to apply to source layer(s) - optim: + optim : any optimization mode ('RASTER', 'VECTOR') - add: + add : any set to True to use additive mode instead of replace when burning values - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ @@ -4953,16 +4957,16 @@ def Rasterize(destNameOrDestDS, srcDS, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object. If passed as a dataset name, a potentially existing output dataset of the same name will be overwritten. To update an existing output dataset, it must be passed as a dataset object. - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.RasterizeOptions(), string or array of strings, other keywords arguments of gdal.RasterizeOptions() If options is provided as a gdal.RasterizeOptions() object, other keywords are ignored. @@ -5007,47 +5011,47 @@ def FootprintOptions(options=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("GeoJSON", etc...) - bands: + bands : any list of output bands to burn values into - combineBands: + combineBands : any how to combine bands: "union" (default) or "intersection" - srcNodata: + srcNodata : any source nodata value(s). - ovr: + ovr : any overview index. - targetCoordinateSystem: + targetCoordinateSystem : any "pixel" or "georef" - dstSRS: + dstSRS : any output SRS - datasetCreationOptions: + datasetCreationOptions : any list or dict of dataset creation options - layerCreationOptions: + layerCreationOptions : any list or dict of layer creation options - splitPolys: + splitPolys : any whether to split multipolygons as several polygons - convexHull: + convexHull : any whether to compute the convex hull of polygons/multipolygons - densify: + densify : any tolerance value for polygon densification - simplify: + simplify : any tolerance value for polygon simplification - maxPoints: + maxPoints : any maximum number of points (100 by default, "unlimited" for unlimited) - minRingArea: + minRingArea : any Minimum value for the area of a ring The unit of the area is in square pixels if targetCoordinateSystem equals "pixel", or otherwise in georeferenced units of the target vector dataset. This option is applied after the reprojection implied by dstSRS - locationFieldName: + locationFieldName : any Specifies the name of the field in the resulting vector dataset where the path of the input dataset will be stored. The default field name is "location". Can be set to None to disable creation of such field. - writeAbsolutePath: + writeAbsolutePath : any Enables writing the absolute path of the input dataset. By default, the filename is written in the location field exactly as the dataset name. - layerName: + layerName : any output layer name - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ @@ -5124,16 +5128,16 @@ def Footprint(destNameOrDestDS, srcDS, **kwargs): Parameters ---------- - destNameOrDestDS: + destNameOrDestDS : any Output dataset name or object If passed as a dataset name, a potentially existing output dataset of the same name will be overwritten. To update an existing output dataset, it must be passed as a dataset object. - srcDS: + srcDS : any a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.FootprintOptions(), string or array of strings, other keywords arguments of gdal.FootprintOptions() If options is provided as a gdal.FootprintOptions() object, other keywords are ignored. @@ -5246,54 +5250,54 @@ def BuildVRTOptions(options=None, Parameters ---------- - options:l - can be be an array of strings, a string or let empty and filled from other keywords. - resolution: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + resolution : any 'highest', 'lowest', 'average', 'user'. - outputBounds:l + outputBounds : any output bounds as (minX, minY, maxX, maxY) in target SRS. - xRes: + xRes : any output resolution in target SRS. - yRes: + yRes : any output resolution in target SRS. - targetAlignedPixels: + targetAlignedPixels : any whether to force output bounds to be multiple of output resolution. - separate: + separate : any whether each source file goes into a separate stacked band in the VRT band. - bandList: + bandList : any array of band numbers (index start at 1). - addAlpha: + addAlpha : any whether to add an alpha mask band to the VRT when the source raster have none. - resampleAlg: + resampleAlg : any resampling mode. - outputSRS: + outputSRS : any assigned output SRS. - allowProjectionDifference: + allowProjectionDifference : any whether to accept input datasets have not the same projection. Note: they will *not* be reprojected. - srcNodata: + srcNodata : any source nodata value(s). - VRTNodata: + VRTNodata : any nodata values at the VRT band level. - hideNodata: + hideNodata : any whether to make the VRT band not report the NoData value. - nodataMaxMaskThreshold: + nodataMaxMaskThreshold : any value of the mask band of a source below which the source band values should be replaced by VRTNodata (or 0 if not specified) - strict: + strict : any set to True if warnings should be failures - pixelFunction: str + pixelFunction : any a pixel function to use to calculate output pixel values when multiple sources overlap. For a list of available pixel functions, see :ref:`builtin_pixel_functions`. - pixelFunctionArgs: + pixelFunctionArgs : any list or dict of pixel function arguments - creationOptions: + creationOptions : any list or dict of creation options - writeAbsolutePath: + writeAbsolutePath : any Enables writing the absolute path of the input datasets. By default, input filenames are written in a relative way with respect to the VRT filename (when possible) - callback: + callback : any callback method. - callback_data: + callback_data : any user data for callback. """ @@ -5370,11 +5374,11 @@ def BuildVRT(destName, srcDSOrSrcDSTab, **kwargs): Parameters ---------- - destName: + destName : any Output dataset name. - srcDSOrSrcDSTab: + srcDSOrSrcDSTab : any An array of Dataset objects or filenames, or a Dataset object or a filename. - kwargs: + **kwargs : any options: return of gdal.BuildVRTOptions(), string or array of strings, other keywords arguments of gdal.BuildVRTOptions(). If options is provided as a gdal.BuildVRTOptions() object, @@ -5437,51 +5441,51 @@ def TileIndexOptions(options=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - overwrite: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + overwrite : any Whether to overwrite the existing tile index - recursive: + recursive : any Whether directories specified in source filenames should be explored recursively - filenameFilter: + filenameFilter : any Pattern that the filenames contained in directories pointed by should follow. '*' and '?' wildcard can be used. String or list of strings. - minPixelSize: + minPixelSize : any Minimum pixel size in term of geospatial extent per pixel (resolution) that a raster should have to be selected. - maxPixelSize: + maxPixelSize : any Maximum pixel size in term of geospatial extent per pixel (resolution) that a raster should have to be selected. - format: + format : any output format ("ESRI Shapefile", "GPKG", etc...) - layerName: + layerName : any output layer name - layerCreationOptions: + layerCreationOptions : any list or dict of layer creation options - locationFieldName: + locationFieldName : any Specifies the name of the field in the resulting vector dataset where the path of the input dataset will be stored. The default field name is "location". Can be set to None to disable creation of such field. - outputSRS: + outputSRS : any assigned output SRS - writeAbsolutePath: + writeAbsolutePath : any Enables writing the absolute path of the input dataset. By default, the filename is written in the location field exactly as the dataset name. - skipDifferentProjection: + skipDifferentProjection : any Whether to skip sources that have a different SRS - gtiFilename: + gtiFilename : any Filename of the GDAL XML Tile Index file - xRes: + xRes : any output horizontal resolution - yRes: + yRes : any output vertical resolution - outputBounds: + outputBounds : any output bounds as [minx, miny, maxx, maxy] - colorInterpretation: + colorInterpretation : any Tile color interpretation, as a single value or a list, of the following values ("red", "green", "blue", "alpha", "grey", "undefined", etc.) or their GCI_xxxx symbolic names - noData: + noData : any tile nodata value, as a single value or a list - bandCount: + bandCount : any number of band of tiles in the index - mask: + mask : any whether tiles have a band mask - metadataOptions: + metadataOptions : any list or dict of metadata options - fetchMD: + fetchMD : any Fetch a metadata item from the raster tile and write it as a field in the tile index. Tuple (raster metadata item name, target field name, target field type), or list of such tuples, with target field type in "String", "Integer", "Integer64", "Real", "Date", "DateTime"; @@ -5588,11 +5592,11 @@ def TileIndex(destName, srcFilenames, **kwargs): Parameters ---------- - destName: + destName : any Output dataset name. - srcFilenames: + srcFilenames : any An array of filenames. - kwargs: + **kwargs : any options: return of gdal.TileIndexOptions(), string or array of strings, other keywords arguments of gdal.TileIndexOptions(). If options is provided as a gdal.TileIndexOptions() object, @@ -5626,29 +5630,29 @@ def MultiDimTranslateOptions(options=None, format=None, creationOptions=None, Parameters ---------- - options: - can be be an array of strings, a string or let empty and filled from other keywords. - format: + options : any + can be an array of strings, a string or let empty and filled from other keywords. + format : any output format ("GTiff", etc...) - creationOptions: + creationOptions : any list or dict of creation options - arraySpecs: + arraySpecs : any list of array specifications, each of them being an array name or "name={src_array_name},dstname={dst_name},transpose=[1,0],view=[:,::-1]" - arrayOptions: + arrayOptions : any list of options passed to `GDALGroup.GetMDArrayNames` to filter reported arrays. - groupSpecs: + groupSpecs : any list of group specifications, each of them being a group name or "name={src_array_name},dstname={dst_name},recursive=no" - subsetSpecs: + subsetSpecs : any list of subset specifications, each of them being like "{dim_name}({min_val},{max_val})" or "{dim_name}({slice_va})" - scaleAxesSpecs: + scaleAxesSpecs : any list of dimension scaling specifications, each of them being like "{dim_name}({scale_factor})" - callback: + callback : any callback method - callback_data: + callback_data : any user data for callback """ @@ -5695,11 +5699,11 @@ def MultiDimTranslate(destName, srcDSOrSrcDSTab, **kwargs): Parameters ---------- - destName: + destName : any Output dataset name - srcDSOrSrcDSTab: + srcDSOrSrcDSTab : any an array of Dataset objects or filenames, or a Dataset object or a filename - kwargs: + **kwargs : any options: return of gdal.MultiDimTranslateOptions(), string or array of strings other keywords arguments of gdal.MultiDimTranslateOptions(). If options is provided as a gdal.MultiDimTranslateOptions() object, @@ -5789,18 +5793,19 @@ def config_options(options, thread_local=True): Parameters ---------- - options: dict + options : dict Dictionary of configuration options passed as key, value - thread_local: bool, default=True + thread_local : bool, default=True Whether the configuration options should be only set on the current thread. Returns ------- - A context manager + contextlib.contextmanager + A context manager - Example - ------- + Examples + -------- >>> with gdal.config_options({"GDAL_NUM_THREADS": "ALL_CPUS"}): ... gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326") @@ -5825,20 +5830,21 @@ def config_option(key, value, thread_local=True): Parameters ---------- - key: str + key : str Name of the configuration option - value: str + value : str Value of the configuration option - thread_local: bool, default=True + thread_local : bool, default=True Whether the configuration option should be only set on the current thread. Returns ------- - A context manager + contextlib.contextmanager + A context manager - Example - ------- + Examples + -------- >>> with gdal.config_option("GDAL_NUM_THREADS", "ALL_CPUS"): ... gdal.Warp("out.tif", "in.tif", dstSRS="EPSG:4326") @@ -5853,10 +5859,11 @@ def quiet_errors(): Returns ------- - A context manager + contextlib.contextmanager + A context manager - Example - ------- + Examples + -------- >>> with gdal.ExceptionMgr(useExceptions=False), gdal.quiet_errors(): ... gdal.Error(gdal.CE_Failure, gdal.CPLE_AppDefined, "you will never see me") @@ -5875,10 +5882,11 @@ def quiet_warnings(): Returns ------- - A context manager + contextlib.contextmanager + A context manager - Example - ------- + Examples + -------- >>> with gdal.ExceptionMgr(useExceptions=False), gdal.quiet_warnings(): ... gdal.Error(gdal.CE_Warning, gdal.CPLE_AppDefined, "you will never see me") @@ -5902,13 +5910,13 @@ def Run(*alg, arguments={}, progress=None, **kwargs): Parameters ---------- - alg: str, list[str], tuple[str] or Algorithm + alg : str, list[str], tuple[str] or Algorithm Path to the algorithm or algorithm instance itself. For example "raster info", ["raster", "info"] or "raster", "info". - arguments: dict + arguments : dict Input arguments of the algorithm. For example {"format": "json", "input": "byte.tif"} - progress: callable + progress : callable Progress function whose arguments are a progress ratio, a string and a user data - kwargs: + **kwargs : any Instead of using the ``arguments`` parameter, it is possible to pass algorithm arguments directly as named parameters of gdal.Run(). If the named argument has dash characters in it, the corresponding @@ -6003,11 +6011,17 @@ def InterpolateAtPoint(self, *args, **kwargs): ---------- pixel : float line : float - interpolation : GRIOResampleAlg (nearest, bilinear, cubic, cubicspline) + interpolation : str + Resampling algorithm to use. One of: + + - ``nearest`` + - ``bilinear`` + - ``cubic`` + - ``cubicspline`` Returns ------- - float: + float Interpolated value, or ``None`` if it has any error. """ @@ -6057,17 +6071,23 @@ def InterpolateAtGeolocation(self, *args, **kwargs): Latitude or northing in "natural" CRS if `srs` is None, otherwise consistent with second axis of `srs`, taking into account the data-axis-to-crs-axis mapping - srs : osgeo.osr.SpatialReference - If set, override the natural CRS in which geolocX, geolocY are expressed - interpolation : GRIOResampleAlg (nearest, bilinear, cubic, cubicspline) + srs : object + :py:class:`osr.SpatialReference`. If set, override the natural CRS in which geolocX, geolocY are expressed + interpolation : str + Resampling algorithm to use. One of: + + - ``nearest`` + - ``bilinear`` + - ``cubic`` + - ``cubicspline`` Returns ------- - float: + float Interpolated value, or ``None`` if it has any error. - Example - ------- + Examples + -------- >>> longitude_degree = -117.64 >>> latitude_degree = 33.90 @@ -6110,8 +6130,9 @@ def ComputeMinMaxLocation(self, *args, **kwargs): Returns ------- - a named tuple (min, max, minX, minY, maxX, maxY) or or ``None`` - in case of error or no valid pixel. + tuple or None + a named tuple (min, max, minX, minY, maxX, maxY) or ``None`` + in case of error or no valid pixel. """ ret = $action(self, *args, **kwargs) @@ -6249,8 +6270,8 @@ class VSIFile(BytesIO): Shortcut for self.InstantiateAlg(key) - Example - ------- + Examples + -------- >>> gdal.GetGlobalAlgorithmRegistry()["raster"] > """ @@ -6277,15 +6298,16 @@ class VSIFile(BytesIO): Parameters ---------- - path: str, list[str] or tuple[str] + path : str, list[str] or tuple[str] Path to the algorithm. For example "raster info", ["raster", "info"] or "raster", "info" Returns ------- + any An algorithm - Example - ------- + Examples + -------- >>> alg = gdal.Algorithm("raster", "info") >>> # or alg = gdal.Algorithm(["raster", "info"]) @@ -6364,16 +6386,17 @@ class VSIFile(BytesIO): :py:class:`osgeo.gdal.Dataset` instance. Parameters - ----------- - parse_json: bool, default=True + ---------- + parse_json : bool, default=True Whether a JSON string should be returned as a dict or list (instead of a string). Returns ------- - The single output argument value + any + The single output argument value. - Example - ------- + Examples + -------- >>> with gdal.Run("raster", "info", input="byte.tif") as alg: ... print(alg.Output()["bands"]) [{'band': 1, 'block': [20, 20], 'type': 'Byte', 'colorInterpretation': 'Gray', 'metadata': {}}] @@ -6411,17 +6434,18 @@ class VSIFile(BytesIO): :py:class:`osgeo.gdal.Dataset` instance. Parameters - ----------- - parse_json: bool, default=True + ---------- + parse_json : bool, default=True Whether a JSON string should be returned as a dict or list (instead of a string). Returns ------- - A dict whose keys are arguments that have outputs and whose values - are the argument values. + dict + A dict whose keys are arguments that have outputs and whose values + are the argument values. - Example - ------- + Examples + -------- >>> with gdal.Run("raster", "reproject", input="byte.tif", output_format="MEM", dst_crs="EPSG:4326") as alg: ... print(alg.Outputs()["output"].ReadAsArray()) [[107 123 132 ... 115 99 107]] @@ -6445,14 +6469,14 @@ class VSIFile(BytesIO): or self.InstantiateSubAlgorithm(key) for a non-leaf algorithm Parameters - ----------- - key: str + ---------- + key : str Name of a known argument of the algorithm - value: + value : any Value of the argument - Example - ------- + Examples + -------- >>> alg = gdal.Algorithm("raster convert") >>> alg["output"].GetName() '' @@ -6478,10 +6502,10 @@ class VSIFile(BytesIO): Shortcut for self.GetArg(key).Set(value) Parameters - ----------- - key: str + ---------- + key : str Name of a known argument of the algorithm - value: + value : any Value of the argument Examples diff --git a/swig/include/python/ogr_python.i b/swig/include/python/ogr_python.i index 6dcae674a2a5..2ce64261cdb1 100644 --- a/swig/include/python/ogr_python.i +++ b/swig/include/python/ogr_python.i @@ -197,17 +197,16 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): Parameters ---------- - requested_schema : PyCapsule, default None - The schema to which the stream should be casted, passed as a - PyCapsule containing a C ArrowSchema representation of the - requested schema. - Currently, this is not supported and will raise a - NotImplementedError if the schema is not None + requested_schema : object, optional + The schema to which the stream should be cast. Passed as a PyCapsule + containing a C ``ArrowSchema`` representation of the requested schema. + Currently, this is not supported and will raise a ``NotImplementedError`` + if the schema is not ``None``. Defaults to ``None``. Returns ------- - PyCapsule - A capsule containing a C ArrowArrayStream struct. + object + A PyCapsule containing a C ``ArrowArrayStream`` struct. """ if requested_schema is not None: @@ -223,11 +222,13 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): Parameters ---------- - options : List of strings or dict with options such as INCLUDE_FID=NO, MAX_FEATURES_IN_BATCH=, etc. - + options : list of str or dict, optional + Options such as ``INCLUDE_FID=NO``, ``MAX_FEATURES_IN_BATCH=``, etc. + Returns ------- - a proxy object which implements the __arrow_c_stream__() method + object + A proxy object that implements the ``__arrow_c_stream__()`` method. """ class ArrowArrayStreamInterface: @@ -248,17 +249,16 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): Parameters ---------- - requested_schema : PyCapsule, default None - The schema to which the stream should be casted, passed as a - PyCapsule containing a C ArrowSchema representation of the - requested schema. - Currently, this is not supported and will raise a - NotImplementedError if the schema is not None + requested_schema : object, optional + The schema to which the stream should be cast. Passed as a PyCapsule + containing a C ``ArrowSchema`` representation of the requested schema. + Currently, this is not supported and will raise a ``NotImplementedError`` + if the schema is not ``None``. Defaults to ``None``. Returns ------- - PyCapsule - A capsule containing a C ArrowArrayStream struct. + object + A PyCapsule containing a C ``ArrowArrayStream`` struct. """ if requested_schema is not None: raise NotImplementedError("requested_schema != None not implemented") @@ -422,19 +422,21 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): Parameters ---------- - obj: + obj : object Object implementing the __arrow_c_stream__ or __arrow_c_array__ interface - requested_schema: PyCapsule, object implementing __arrow_c_schema__ or None. Default None - The schema to which the stream should be casted, passed as a - PyCapsule containing a C ArrowSchema representation of the - requested schema, or an object implementing the __arrow_c_schema__ interface. + requested_schema : object, optional + The schema to which the stream should be casted. Passed as a PyCapsule + containing a C ArrowSchema representation of the requested schema, or + as an object implementing the ``__arrow_c_schema__`` interface. + Defaults to ``None``. - createFieldsFromSchema: boolean or None. Default to None - Whether OGRLayer::CreateFieldFromArrowSchema() should be called. If None - specified, it is called if no fields have been created yet + createFieldsFromSchema : bool or None, optional + Whether :py:meth:`Layer.CreateFieldFromArrowSchema` should be called. + If ``None`` is specified, it is called if no fields have been created yet. + Defaults to ``None``. - options: list of strings + options : list[str] Options to pass to OGRLayer::CreateFieldFromArrowSchema() and OGRLayer::WriteArrowBatch() """ @@ -615,7 +617,7 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): Parameters ---------- - fld_index : int / str + fld_index : int or str Field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -682,10 +684,10 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): This function is the same as the C++ method :cpp:func:`OGRFeature::SetField`. Parameters - ----------- - field_index_or_name: + ---------- + field_index_or_name : int or str the field to set, from 0 to GetFieldCount()-1. Or the field name - values: + values : any the data to apply. """ @@ -758,9 +760,8 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): The GetGeometryRef() method is also available as an alias of geometry() Returns - -------- - Geometry: - the geometry, or None. + ------- + Geometry or None """ return self.GetGeometryRef() @@ -780,12 +781,12 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): ---------- as_object : bool, default = False determines whether the returned value should be a Python object instead of a string. - options : dict/str + options : dict or str Options to pass to :py:func:`Geometry.ExportToJson` Returns ------- - str / dict + str or dict """ try: import simplejson @@ -863,13 +864,13 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): used afterwards. Parameters - ----------- + ---------- geom : Geometry geometry to apply to feature. Returns - -------- - int: + ------- + int :py:const:`OGRERR_NONE` if successful, or :py:const:`OGR_UNSUPPORTED_GEOMETRY_TYPE` if the geometry type is illegal for the :py:class:`FeatureDefn` (checking not yet implemented). @@ -892,8 +893,8 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): See :cpp:func:`OGRFeature::SetGeomFieldDirectly`. Parameters - ----------- - fld_index : int / str + ---------- + fld_index : int or str Geometry field name or 0-based numeric index. For repeated access, use of the numeric index avoids a lookup step. @@ -901,8 +902,8 @@ def _WarnIfUserHasNotSpecifiedIfUsingExceptions(): handle to the new geometry to apply to feature. Returns - -------- - int: + ------- + int :py:const:`OGRERR_NONE` if successful, or :py:const:`OGR_UNSUPPORTED_GEOMETRY_TYPE` if the geometry type is illegal for the :py:class:`FeatureDefn` (checking not yet implemented). diff --git a/swig/include/python/typemaps_python.i b/swig/include/python/typemaps_python.i index 6f126bae5969..97fcad450a23 100644 --- a/swig/include/python/typemaps_python.i +++ b/swig/include/python/typemaps_python.i @@ -1692,11 +1692,11 @@ static PyObject *XMLTreeToPyList( CPLXMLNode *psTree ) if( psXMLTree != NULL && psXMLTree->psNext != NULL ) { - CPLXMLNode *psFirst = psXMLTree; + CPLXMLNode *psFirst = psXMLTree; - /* create a "pseudo" root if we have multiple elements */ + /* create a "pseudo" root if we have multiple elements */ psXMLTree = CPLCreateXMLNode( NULL, CXT_Element, "" ); - psXMLTree->psChild = psFirst; + psXMLTree->psChild = psFirst; bFakeRoot = TRUE; } @@ -1715,7 +1715,7 @@ static PyObject *XMLTreeToPyList( CPLXMLNode *psTree ) } /* ==================================================================== */ -/* Support function for progress callbacks to python. */ +/* Support function for progress callbacks to python. */ /* ==================================================================== */ /* The following scary, scary, voodoo -- hobu */ @@ -1855,7 +1855,7 @@ static PyObject *XMLTreeToPyList( CPLXMLNode *psTree ) { /* %typemap(out) ( GUInt32 ) */ - $1 = 0; + $1 = 0; } @@ -1863,7 +1863,7 @@ static PyObject *XMLTreeToPyList( CPLXMLNode *psTree ) { /* %typemap(out) ( GUInt32 ) */ - $result = PyLong_FromUnsignedLong($1); + $result = PyLong_FromUnsignedLong($1); } @@ -1872,8 +1872,8 @@ static PyObject *XMLTreeToPyList( CPLXMLNode *psTree ) /* %typemap(in) ( GUInt32 ) */ if (PyLong_Check($input) || PyInt_Check($input)) { - $1 = PyLong_AsUnsignedLong($input); - } + $1 = PyLong_AsUnsignedLong($input); + } } diff --git a/swig/python/pyproject.toml b/swig/python/pyproject.toml index 07ce63e756b7..dcd09d668e91 100644 --- a/swig/python/pyproject.toml +++ b/swig/python/pyproject.toml @@ -43,3 +43,16 @@ Documentation = "https://gdal.org" Repository = "https://github.com/OSGeo/GDAL.git" Changelog = "https://github.com/OSGeo/gdal/blob/master/NEWS.md" Issues = "https://github.com/OSGeo/gdal/issues" + +[tool.docstub.types] +CoordinateTransform = "osgeo.osr.CoordinateTransform" +Dataset = "osgeo.gdal.Dataset" +Driver = "osgeo.gdal.Driver" +Feature = "osgeo.ogr.Feature" +FieldDomain = "osgeo.ogr.FieldDomain" +GeomFieldDefn = "osgeo.ogr.GeomFieldDefn" +Layer = "osgeo.ogr.Layer" +StyleTable = "osgeo.ogr.StyleTable" +SpatialReference = "osgeo.osr.SpatialReference" +Transformer = "osgeo.gdal.Transformer" + From d4edb84c0f8536b511db87da4f301945955e99a5 Mon Sep 17 00:00:00 2001 From: sethg Date: Thu, 9 Oct 2025 22:21:57 +0200 Subject: [PATCH 2/3] Update spelling_wordlist.txt --- doc/source/spelling_wordlist.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/source/spelling_wordlist.txt b/doc/source/spelling_wordlist.txt index ed06d5846fa5..060c05b4abbf 100644 --- a/doc/source/spelling_wordlist.txt +++ b/doc/source/spelling_wordlist.txt @@ -461,6 +461,8 @@ connectedness const constexpr contensts +contextlib +contextmanager ContourOptions Contrarty conv @@ -1787,6 +1789,7 @@ MaxX maxy maxY MaxY +maxz MaxZ mbtiles mbtowc @@ -1837,6 +1840,7 @@ minX miny minY MinY +minz MinZ Mipmaps MiraD From 18a9c2dba54e99f4dd5c9be955313e734106bb42 Mon Sep 17 00:00:00 2001 From: Seth G Date: Fri, 10 Oct 2025 22:23:18 +0200 Subject: [PATCH 3/3] Update swig/include/python/docs/ogr_fielddef_docs.i Co-authored-by: Dan Baston --- swig/include/python/docs/ogr_fielddef_docs.i | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/swig/include/python/docs/ogr_fielddef_docs.i b/swig/include/python/docs/ogr_fielddef_docs.i index 6a9570fe9449..86920a9bdf07 100644 --- a/swig/include/python/docs/ogr_fielddef_docs.i +++ b/swig/include/python/docs/ogr_fielddef_docs.i @@ -89,7 +89,7 @@ Note: no driver is know to use the concept of field justification. Returns ------- -object +int the justification. ";