diff --git a/doc/source/api/python/osgeo.ogr.rst b/doc/source/api/python/osgeo.ogr.rst index 96df1c2d8c50..69650295d85f 100644 --- a/doc/source/api/python/osgeo.ogr.rst +++ b/doc/source/api/python/osgeo.ogr.rst @@ -5,3 +5,5 @@ osgeo.ogr module :members: :undoc-members: :show-inheritance: + :special-members: __init__ + :exclude-members: thisown diff --git a/swig/include/python/docs/ogr_feature_docs.i b/swig/include/python/docs/ogr_feature_docs.i index d0f4f9167f59..6e73d15d1619 100644 --- a/swig/include/python/docs/ogr_feature_docs.i +++ b/swig/include/python/docs/ogr_feature_docs.i @@ -1,1712 +1,1039 @@ -%extend OGRFeatureShadow { -// File: ogrfeature_8cpp.xml -%feature("docstring") Create "OGRFeatureH -OGR_F_Create(OGRFeatureDefnH hDefn) - -Feature factory. - -Note that the OGRFeature will increment the reference count of its -defining OGRFeatureDefn. Destruction of the OGRFeatureDefn before -destruction of all OGRFeatures that depend on it is likely to result -in a crash. +%feature("docstring") OGRFeatureShadow " +Python proxy of an :cpp:class:`OGRFeature`. +"; -This function is the same as the C++ method OGRFeature::OGRFeature(). +%extend OGRFeatureShadow { +%feature("docstring") OGRFeatureShadow " Parameters ----------- -hDefn: - handle to the feature class (layer) definition to which the - feature will adhere. +feature_def: + :py:class:`FeatureDefn` to which the feature will adhere. +"; + +%feature("docstring") Clone " +Duplicate a Feature. +See :cpp:func:`OGRFeature::Clone`. Returns -------- -OGRFeatureH: - a handle to the new feature object with null fields and no geometry, - or, starting with GDAL 2.1, NULL in case out of memory situation. +Feature "; -%feature("docstring") Destroy "void OGR_F_Destroy(OGRFeatureH hFeat) +%feature("docstring") DumpReadable " -Destroy feature. +Print this feature in a human readable form. -The feature is deleted, but within the context of the GDAL/OGR heap. -This is necessary when higher level applications use GDAL/OGR from a -DLL and they want to delete a feature created within the DLL. If the -delete is done in the calling application the memory will be freed -onto the application heap which is inappropriate. +This dumps the attributes and geometry. It doesn't include +definition information other than field types and names nor does it +report the geometry spatial reference system. -This function is the same as the C++ method -OGRFeature::DestroyFeature(). +See :cpp:func:`OGRFeature::DumpReadable`. -Parameters ------------ -hFeat: - handle to the feature to destroy. +Examples +-------- +>>> with gdal.OpenEx('data/poly.shp') as ds: +... lyr = ds.GetLayer(0) +... feature = lyr.GetNextFeature() +... feature.DumpReadable() +... +OGRFeature(poly):0 + AREA (Real) = 215229.266 + EAS_ID (Integer64) = 168 + PRFEDEA (String) = 35043411 + POLYGON ((479819.84375 4765180.5,479690.1875 4765259.5,479647.0 4765369.5,479730.375 4765400.5,480039.03125 4765539.5,480035.34375 4765558.5,480159.78125 4765610.5,480202.28125 4765482.0,480365.0 4765015.5,480389.6875 4764950.0,480133.96875 4764856.5,480080.28125 4764979.5,480082.96875 4765049.5,480088.8125 4765139.5,480059.90625 4765239.5,480019.71875 4765319.5,479980.21875 4765409.5,479909.875 4765370.0,479859.875 4765270.0,479819.84375 4765180.5)) "; -%feature("docstring") GetDefnRef " -OGRFeatureDefnH OGR_F_GetDefnRef(OGRFeatureH hFeat) - -Fetch feature definition. - -This function is the same as the C++ method OGRFeature::GetDefnRef(). +%feature("docstring") DumpReadableAsString " -Parameters ------------ -hFeat: - handle to the feature to get the feature definition from. +Return feature information in a human-readable form. +Returns the text printed by :py:func:`Feature.DumpReadable`. Returns --------- -OGRFeatureDefnH: - a handle to the feature definition object on which feature depends. +------- +str "; -%feature("docstring") SetGeometryDirectly " -OGRErr OGR_F_SetGeometryDirectly(OGRFeatureH hFeat, OGRGeometryH hGeom) +%feature("docstring") Equal " -Set feature geometry. - -This function updates the features geometry, and operate exactly as -SetGeometry(), except that this function assumes ownership of the -passed geometry (even in case of failure of that function). +Test if two features are the same. -This function is the same as the C++ method -OGRFeature::SetGeometryDirectly. +Two features are considered equal if they reference the +same :py:class:`FeatureDefn`, have the same field values, and the same geometry +(as tested by :py:func:`Geometry.Equal`) as well as the same feature id. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +See :cpp:func:`OGRFeature::Equal`. Parameters ----------- -hFeat: - handle to the feature on which to apply the geometry. -hGeom: - handle to the new geometry to apply to feature. - +feature : Feature + feature to test this one against Returns -------- -OGRErr: - OGRERR_NONE if successful, or OGR_UNSUPPORTED_GEOMETRY_TYPE if the - geometry type is illegal for the OGRFeatureDefn (checking not yet - implemented). +bool "; -%feature("docstring") SetGeometry " -OGRErr OGR_F_SetGeometry(OGRFeatureH hFeat, OGRGeometryH hGeom) - -Set feature geometry. - -This function updates the features geometry, and operate exactly as -SetGeometryDirectly(), except that this function does not assume -ownership of the passed geometry, but instead makes a copy of it. +%feature("docstring") FillUnsetWithDefault " -This function is the same as the C++ OGRFeature::SetGeometry(). +Fill unset fields with default values that might be defined. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +See :cpp:func:`OGRFeature::FillUnsetWithDefault`. Parameters ----------- -hFeat: - handle to the feature on which new geometry is applied to. -hGeom: - handle to the new geometry to apply to feature. - -Returns --------- -OGRErr: - OGRERR_NONE if successful, or OGR_UNSUPPORTED_GEOMETRY_TYPE if the - geometry type is illegal for the OGRFeatureDefn (checking not yet - implemented). +bNotNullableOnly : bool + if we should fill only unset fields with a not-null + constraint. +options : dict + unused currently. "; -%feature("docstring") StealGeometry " -OGRGeometryH OGR_F_StealGeometry(OGRFeatureH hFeat) - -Take away ownership of geometry. - -Fetch the geometry from this feature, and clear the reference to the -geometry on the feature. This is a mechanism for the application to -take over ownership of the geometry from the feature without copying. -Sort of an inverse to OGR_FSetGeometryDirectly(). - -After this call the OGRFeature will have a NULL geometry. - -the pointer to the geometry. "; - -%feature("docstring") GetGeometryRef " -Return the feature geometry - -The lifetime of the returned geometry is bound to the one of its belonging -feature. +%feature("docstring") GetDefnRef " -For more details: :cpp:func:`OGR_F_GetGeometryRef` +Fetch the :py:class:`FeatureDefn` associated with this Feature. -The geometry() method is also available as an alias of GetGeometryRef() +See :cpp:func:`OGRFeature::GetDefnRef()`. Returns -------- -Geometry: - the geometry, or None. +FeatureDefn "; -%feature("docstring") GetGeomFieldRef "OGRGeometryH -OGR_F_GetGeomFieldRef(OGRFeatureH hFeat, int iField) - -Fetch a handle to feature geometry. - -This function is the same as the C++ method -OGRFeature::GetGeomFieldRef(). - -Parameters ------------ -hFeat: - handle to the feature to get geometry from. -iField: - geometry field to get. +%feature("docstring") GetFID " -a handle to internal feature geometry. This object should not be -modified. +Get feature identifier. +See :cpp:func:`OGRFeature::GetFID` -GDAL 1.11 "; +Returns +------- +int: + feature id or :py:const:`NullFID` if none has been assigned. +"; -%feature("docstring") SetGeomFieldDirectly " -OGRErr OGR_F_SetGeomFieldDirectly(OGRFeatureH hFeat, int iField, OGRGeometryH hGeom) +// GetField documented inline -Set feature geometry of a specified geometry field. +%feature("docstring") GetFieldAsBinary " -This function updates the features geometry, and operate exactly as -SetGeomField(), except that this function assumes ownership of the -passed geometry (even in case of failure of that function). +Fetch field value as binary. -This function is the same as the C++ method -OGRFeature::SetGeomFieldDirectly. +This method only works for :py:const:`OFTBinary` and :py:const:`OFTString` fields. -.. versionadded:: 1.11 +See :cpp:func:`OGRFeature::GetFieldAsBinary`. Parameters ----------- -hFeat: - handle to the feature on which to apply the geometry. -iField: - geometry field to set. -hGeom: - handle to the new geometry to apply to feature. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -OGRErr: - OGRERR_NONE if successful, or OGRERR_FAILURE if the index is invalid, - or OGR_UNSUPPORTED_GEOMETRY_TYPE if the geometry type is illegal for - the OGRFeatureDefn (checking not yet implemented). - "; +bytearray +"; -%feature("docstring") SetGeomField "OGRErr -OGR_F_SetGeomField(OGRFeatureH hFeat, int iField, OGRGeometryH hGeom) +%feature("docstring") GetFieldAsDateTime " -Set feature geometry of a specified geometry field. +Fetch field value as date and time. -This function updates the features geometry, and operate exactly as -SetGeometryDirectly(), except that this function does not assume -ownership of the passed geometry, but instead makes a copy of it. +Currently this method only works for :py:const:`OFTDate`, :py:const:`OFTTime` +and :py:const:`OFTDateTime` fields. -This function is the same as the C++ OGRFeature::SetGeomField(). +See :cpp:func:`OGRFeature::GetFieldAsDateTime`. Parameters ----------- -hFeat: - handle to the feature on which new geometry is applied to. -iField: - geometry field to set. -hGeom: - handle to the new geometry to apply to feature. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -OGRErr: - OGRERR_NONE if successful, or OGR_UNSUPPORTED_GEOMETRY_TYPE if the - geometry type is illegal for the OGRFeatureDefn (checking not yet - implemented). -"; +list + list containing [ year, month, day, hour, minute, second, timezone flag ] -%feature("docstring") Clone " -OGRFeatureH OGR_F_Clone(OGRFeatureH hFeat) +Examples +-------- +>>> from datetime import datetime +>>> from zoneinfo import ZoneInfo +>>> defn = ogr.FeatureDefn() +>>> defn.AddFieldDefn(ogr.FieldDefn('unknown', ogr.OFTDateTime)) +>>> defn.AddFieldDefn(ogr.FieldDefn('local', ogr.OFTDateTime)) +>>> defn.AddFieldDefn(ogr.FieldDefn('utc', ogr.OFTDateTime)) +>>> feature = ogr.Feature(defn) +>>> feature['unknown'] = datetime.now() +>>> feature['local'] = datetime.now(ZoneInfo('Canada/Eastern')) +>>> feature['utc'] = datetime.now(ZoneInfo('UTC')) +>>> feature.GetFieldAsDateTime('unknown') +[2024, 3, 15, 20, 34, 52.594173431396484, 0] +>>> feature.GetFieldAsDateTime('local') +[2024, 3, 15, 20, 34, 52.59502410888672, 84] +>>> feature.GetFieldAsDateTime('utc') +[2024, 3, 16, 0, 34, 52.59580993652344, 100] + +See Also +-------- +:py:func:`Feature.GetFieldAsISO8601DateTime` +"; -Duplicate feature. +%feature("docstring") GetFieldAsDouble " +Fetch field value as a double. -The newly created feature is owned by the caller, and will have its -own reference to the OGRFeatureDefn. +:py:const:`OFTString` features will be translated using :cpp:func:`CPLAtof`. :py:const:`OFTInteger` +fields will be cast to double. Other field types, or errors will +result in a return value of zero. -This function is the same as the C++ method OGRFeature::Clone(). +See :cpp:func:`OGRFeature::GetFieldAsDouble`. Parameters ----------- -hFeat: - handle to the feature to clone. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -OGRFeatureH: - a handle to the new feature, exactly matching this feature. +float: + the field value. "; -%feature("docstring") GetFieldCount " -int OGR_F_GetFieldCount(OGRFeatureH hFeat) +%feature("docstring") GetFieldAsDoubleList " -Fetch number of fields on this feature This will always be the same as -the field count for the OGRFeatureDefn. +Fetch field value as a list of doubles. -This function is the same as the C++ method -OGRFeature::GetFieldCount(). +Currently this function only works for :py:const:`OFTRealList` fields. + +See :cpp:func:`OGRFeature::GetFieldAsDoubleList`. Parameters ----------- -hFeat: - handle to the feature to get the fields count from. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns +------- +list + +Examples -------- -int: - count of fields. +>>> defn = ogr.FeatureDefn() +>>> defn.AddFieldDefn(ogr.FieldDefn('list', ogr.OFTRealList)) +>>> feature = ogr.Feature(defn) +>>> feature['list'] = [1.1, 2.2, 3.3] +>>> feature.GetFieldAsDoubleList('list') +[1.1, 2.2, 3.3] "; -%feature("docstring") GetFieldDefnRef " -OGRFieldDefnH OGR_F_GetFieldDefnRef(OGRFeatureH hFeat, int i) +%feature("docstring") GetFieldAsISO8601DateTime " -Fetch definition for this field. +Fetch :py:const:`OFTDateTime` field value as a ISO8601 representation. -This function is the same as the C++ method -OGRFeature::GetFieldDefnRef(). +Return a string like 'YYYY-MM-DDTHH:MM:SS(.sss)?(Z|([+|-]HH:MM))?' +Milliseconds are omitted if equal to zero. +Other field types, or errors will result in a return of an empty string. + +See :cpp:func:`OGRFeature::GetFieldAsISO8601DateTime`. + +.. versionadded:: 3.7 Parameters ----------- -hFeat: - handle to the feature on which the field is found. -i: - the field to fetch, from 0 to GetFieldCount()-1. - -Returns --------- -OGRFieldDefnH: - a handle to the field definition (from the OGRFeatureDefn). This is an - internal reference, and should not be deleted or modified. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. +options : dict / str + Not currently used. "; -%feature("docstring") GetFieldIndex " -int OGR_F_GetFieldIndex(OGRFeatureH hFeat, const char \\*pszName) +%feature("docstring") GetFieldAsInteger " -Fetch the field index given field name. +Fetch field value as a 32-bit integer. -This is a cover for the OGRFeatureDefn::GetFieldIndex() method. +:py:const:`OFTString` features will be translated using atoi(). +:py:const:`OFTReal` fields will be cast to integer. Other field types, or +errors will result in a return value of zero. -This function is the same as the C++ method -OGRFeature::GetFieldIndex(). +See :cpp:func:`GetFieldAsInteger`. Parameters ----------- -hFeat: - handle to the feature on which the field is found. -pszName: - the name of the field to search for. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- int: - the field index, or -1 if no matching field is found. + the field value. + +Examples +-------- +>>> defn = ogr.FeatureDefn() +>>> defn.AddFieldDefn(ogr.FieldDefn('my_int', ogr.OFTInteger64)) +>>> feature = ogr.Feature(defn) +>>> feature['my_int'] = 2**32 + 1 +>>> feature.GetFieldAsInteger('my_int') +Warning 1: Integer overflow occurred when trying to return 64bit integer. Use GetFieldAsInteger64() instead +2147483647 +>>> feature.GetFieldAsInteger64('my_int') +4294967297 +>>> feature.GetField('my_int') +4294967297 "; -%feature("docstring") GetGeomFieldCount " -int OGR_F_GetGeomFieldCount(OGRFeatureH hFeat) +%feature("docstring") GetFieldAsInteger64 " -Fetch number of geometry fields on this feature This will always be -the same as the geometry field count for the OGRFeatureDefn. +Fetch field value as integer 64 bit. -This function is the same as the C++ method -OGRFeature::GetGeomFieldCount(). +:py:const:`OFTInteger` are promoted to 64 bit. :py:const:`OFTString` features +will be translated using :cpp:func:`CPLAtoGIntBig`. :py:const:`OFTReal` fields +will be cast to integer. Other field types, or errors will result in a return +value of zero. -.. versionadded:: 1.11 +See :cpp:func:`OGRFeature::GetFieldAsInteger64`. Parameters ----------- -hFeat: - handle to the feature to get the geometry fields count from. - +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- int: - count of geometry fields. + the field value. "; -%feature("docstring") GetGeomFieldDefnRef " -OGRGeomFieldDefnH OGR_F_GetGeomFieldDefnRef(OGRFeatureH hFeat, int i) - -Fetch definition for this geometry field. +%feature("docstring") GetFieldAsInteger64List " +Fetch field value as a list of 64 bit integers. -This function is the same as the C++ method -OGRFeature::GetGeomFieldDefnRef(). +Currently this function only works for :py:const:`OFTInteger64List` fields. -.. versionadded:: 1.11 +See :cpp:func:`OGRFeature::GetFieldAsInteger64List`. Parameters ----------- -hFeat: - handle to the feature on which the field is found. -i: - the field to fetch, from 0 to GetGeomFieldCount()-1. - +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -OGRGeomFieldDefnH: - a handle to the field definition (from the OGRFeatureDefn). This is an - internal reference, and should not be deleted or modified. +list: + the field value. "; -%feature("docstring") GetGeomFieldIndex " -int OGR_F_GetGeomFieldIndex(OGRFeatureH hFeat, const char \\*pszName) +%feature("docstring") GetFieldAsIntegerList " -Fetch the geometry field index given geometry field name. +Fetch field value as a list of integers. -This is a cover for the OGRFeatureDefn::GetGeomFieldIndex() method. +Currently this function only works for :py:const:`OFTIntegerList` fields. This function is the same as the C++ method -OGRFeature::GetGeomFieldIndex(). - -.. versionadded:: 1.11 +:cpp:func:`OGRFeature::GetFieldAsIntegerList`. Parameters ----------- -hFeat: - handle to the feature on which the geometry field is found. -pszName: - the name of the geometry field to search for. - +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - the geometry field index, or -1 if no matching geometry field is found. +list: + the field value. "; -%feature("docstring") IsFieldSet " -int OGR_F_IsFieldSet(OGRFeatureH hFeat, int iField) +%feature("docstring") GetFieldAsString " -Test if a field has ever been assigned a value or not. +:py:const:`OFTReal` and :py:const:`OFTInteger` fields will be translated to string using +sprintf(), but not necessarily using the established formatting rules. +Other field types, or errors will result in a return value of zero. -This function is the same as the C++ method OGRFeature::IsFieldSet(). +See :cpp:func:`OGRFeature::GetFieldAsString`. Parameters ----------- -hFeat: - handle to the feature on which the field is. -iField: - the field to test. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - TRUE if the field has been set, otherwise false. -"; - -%feature("docstring") UnsetField " -void OGR_F_UnsetField(OGRFeatureH hFeat, int iField) - -Clear a field, marking it as unset. - -This function is the same as the C++ method OGRFeature::UnsetField(). - -Parameters ------------ -hFeat: - handle to the feature on which the field is. -iField: - the field to unset. +str: + the field value. "; -%feature("docstring") IsFieldNull " -int OGR_F_IsFieldNull(OGRFeatureH hFeat, int iField) +%feature("docstring") GetFieldAsStringList " -Test if a field is null. +Fetch field value as a list of strings. -This function is the same as the C++ method OGRFeature::IsFieldNull(). +Currently this method only works for :py:const:`OFTStringList` fields. -.. versionadded:: 2.2 +See :cpp:func:`OGRFeature::GetFieldAsStringList`. Parameters ----------- -hFeat: - handle to the feature on which the field is. -iField: - the field to test. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - TRUE if the field is null, otherwise false. +list: + the field value. "; -%feature("docstring") IsFieldSetAndNotNull " -int OGR_F_IsFieldSetAndNotNull(OGRFeatureH hFeat, int iField) - -Test if a field is set and not null. - -This function is the same as the C++ method -OGRFeature::IsFieldSetAndNotNull(). +%feature("docstring") GetFieldCount " -.. versionadded:: 2.2 +Fetch number of fields on this feature This will always be the same as +the field count for the :py:class:`FeatureDefn`. -Parameters ------------ -hFeat: - handle to the feature on which the field is. -iField: - the field to test. +See :cpp:func:`OGRFeature::GetFieldCount`. Returns -------- int: - TRUE if the field is set and not null, otherwise false. + count of fields. "; -%feature("docstring") SetFieldNull " -void OGR_F_SetFieldNull(OGRFeatureH hFeat, int iField) - -Clear a field, marking it as null. +%feature("docstring") GetFieldDefnRef " -This function is the same as the C++ method -OGRFeature::SetFieldNull(). +Fetch definition for this field. -.. versionadded:: 2.2 +See :cpp:func:`OGRFeature::GetFieldDefnRef`. Parameters ----------- -hFeat: - handle to the feature on which the field is. -iField: - the field to set to null. +fld_index : int / 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. "; -%feature("docstring") GetRawFieldRef " -OGRField\\* OGR_F_GetRawFieldRef(OGRFeatureH hFeat, int iField) +%feature("docstring") GetFieldIndex " -Fetch a handle to the internal field value given the index. +Fetch the field index given field name. -This function is the same as the C++ method -OGRFeature::GetRawFieldRef(). +See :cpp:func:`OGRFeature::GetFieldIndex`. Parameters ----------- -hFeat: - handle to the feature on which field is found. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +field_name: + the name of the field to search for. Returns -------- -OGRField: - the returned handle is to an internal data structure, and should not - be freed, or modified. +int: + the field index, or -1 if no matching field is found. "; -%feature("docstring") GetFieldAsInteger " -int OGR_F_GetFieldAsInteger(OGRFeatureH hFeat, int iField) - -Fetch field value as integer. - -OFTString features will be translated using atoi(). OFTReal fields -will be cast to integer. Other field types, or errors will result in a -return value of zero. +%feature("docstring") GetFieldType " -This function is the same as the C++ method -OGRFeature::GetFieldAsInteger(). +Return the type of the given field. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - the field value. +int + field type code (e.g., :py:const:`OFTInteger`) "; -%feature("docstring") GetFieldAsInteger64 " -GIntBig OGR_F_GetFieldAsInteger64(OGRFeatureH hFeat, int iField) - -Fetch field value as integer 64 bit. - -OFTInteger are promoted to 64 bit. OFTString features will be -translated using CPLAtoGIntBig(). OFTReal fields will be cast to -integer. Other field types, or errors will result in a return value of -zero. - -This function is the same as the C++ method -OGRFeature::GetFieldAsInteger64(). +%feature("docstring") GetGeomFieldCount " -.. versionadded:: 2.0 +Fetch number of geometry fields on this feature This will always be +the same as the geometry field count for the :py:class:`FeatureDefn`. -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +See :cpp:func:`OGRFeature::GetGeomFieldCount`. Returns -------- int: - the field value. + count of geometry fields. "; -%feature("docstring") GetFieldAsDouble " -double OGR_F_GetFieldAsDouble(OGRFeatureH hFeat, int iField) - -Fetch field value as a double. +%feature("docstring") GetGeomFieldDefnRef " -OFTString features will be translated using CPLAtof(). OFTInteger -fields will be cast to double. Other field types, or errors will -result in a return value of zero. +Fetch definition for this geometry field. -This function is the same as the C++ method -OGRFeature::GetFieldAsDouble(). +See :cpp:func:`OGRFeature::GetGeomFieldDefnRef`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -float: - the field value. +GeomFieldDefn: + a reference to the field definition. + Should not be deleted or modified. "; -%feature("docstring") OGRFeatureFormatDateTimeBuffer " -static void OGRFeatureFormatDateTimeBuffer(char \\*szTempBuffer, size_t nMaxSize, -int nYear, int nMonth, int nDay, int nHour, int nMinute, float -fSecond, int nTZFlag) "; - -%feature("docstring") GetFieldAsString " -const char\\* OGR_F_GetFieldAsString(OGRFeatureH hFeat, int iField) - -Fetch field value as a string. +%feature("docstring") GetGeomFieldIndex " -OFTReal and OFTInteger fields will be translated to string using -sprintf(), but not necessarily using the established formatting rules. -Other field types, or errors will result in a return value of zero. +Fetch the geometry field index given geometry field name. -This function is the same as the C++ method -OGRFeature::GetFieldAsString(). +See :cpp:func:`OGRFeature::GetGeomFieldIndex`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +field_name: + the name of the geometry field to search for. Returns -------- -str: - the field value. This string is internal, and should not be modified, - or freed. Its lifetime may be very brief. +int: + the geometry field index, or -1 if no matching geometry field is found. "; -%feature("docstring") GetFieldAsIntegerList " -const int\\* OGR_F_GetFieldAsIntegerList(OGRFeatureH hFeat, int iField, int -\\*pnCount) - -Fetch field value as a list of integers. +%feature("docstring") GetGeomFieldRef " -Currently this function only works for OFTIntegerList fields. +Fetch a feature :py:class:`Geometry`. -This function is the same as the C++ method -OGRFeature::GetFieldAsIntegerList(). +See :cpp:func:`OGRFeature::GetGeomFieldRef`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnCount: - an integer to put the list count (number of integers) into. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns --------- -list[int]: - the field value. This list is internal, and should not be modified, or - freed. Its lifetime may be very brief. If \\*pnCount is zero on return - the returned pointer may be NULL or non-NULL. -"; - -%feature("docstring") GetFieldAsInteger64List "const GIntBig\\* -OGR_F_GetFieldAsInteger64List(OGRFeatureH hFeat, int iField, int -\\*pnCount) +------- +Geometry -Fetch field value as a list of 64 bit integers. +"; -Currently this function only works for OFTInteger64List fields. +%feature("docstring") GetGeometryRef " +Return the feature geometry -This function is the same as the C++ method -OGRFeature::GetFieldAsInteger64List(). +The lifetime of the returned geometry is bound to the one of its belonging +feature. -.. versionadded:: 2.0 +See :cpp:func:`OGRFeature::GetGeometryRef` -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnCount: - an integer to put the list count (number of integers) into. +The :py:func:`Feature.geometry` method is also available as an alias of :py:func:`Feature.GetGeometryRef`. Returns -------- -list[int]: - the field value. This list is internal, and should not be modified, or - freed. Its lifetime may be very brief. If \\*pnCount is zero on return - the returned pointer may be NULL or non-NULL. +Geometry: + the geometry, or None. "; -%feature("docstring") GetFieldAsDoubleList "const double\\* -OGR_F_GetFieldAsDoubleList(OGRFeatureH hFeat, int iField, int -\\*pnCount) +%feature("docstring") GetNativeData " -Fetch field value as a list of doubles. - -Currently this function only works for OFTRealList fields. +Returns the native data for the feature. -This function is the same as the C++ method -OGRFeature::GetFieldAsDoubleList(). +The native data is the representation in a \"natural\" form that comes +from the driver that created this feature, or that is aimed at an +output driver. The native data may be in different format, which is +indicated by :py:func:`GetNativeMediaType`. -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnCount: - an integer to put the list count (number of doubles) into. +Note that most drivers do not support storing the native data in the +feature object, and if they do, generally the ``NATIVE_DATA`` open option +must be passed at dataset opening. -Returns --------- -list[float]: - the field value. This list is internal, and should not be modified, or - freed. Its lifetime may be very brief. If \\*pnCount is zero on return - the returned pointer may be NULL or non-NULL. -"; +The \"native data\" does not imply it is something more performant or +powerful than what can be obtained with the rest of the API, but it +may be useful in round-tripping scenarios where some characteristics +of the underlying format are not captured otherwise by the OGR +abstraction. -%feature("docstring") GetFieldAsStringList "char\\*\\* -OGR_F_GetFieldAsStringList(OGRFeatureH hFeat, int iField) +See :cpp:func:`OGRFeature::GetNativeData` and :ref:`rfc-60`. -Fetch field value as a list of strings. +Returns +------- +str: + a string with the native data, or ``None``. +"; -Currently this method only works for OFTStringList fields. +%feature("docstring") GetNativeMediaType " -The returned list is terminated by a NULL pointer. The number of -elements can also be calculated using CSLCount(). +Returns the native media type for the feature. -This function is the same as the C++ method -OGRFeature::GetFieldAsStringList(). +The native media type is the identifier for the format of the native +data. It follows the IANA RFC 2045 +(seehttps://en.wikipedia.org/wiki/Media_type), e.g. +\"application/vnd.geo+json\" for JSon. -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. +See :cpp:func:`OGRFeature::GetNativeMediaType` and :ref:`rfc-60`. Returns -------- -list[str]: - the field value. This list is internal, and should not be modified, or - freed. Its lifetime may be very brief. +str: + a string with the native media type, or ``None``. "; -%feature("docstring") GetFieldAsBinary "GByte\\* -OGR_F_GetFieldAsBinary(OGRFeatureH hFeat, int iField, int \\*pnBytes) - -Fetch field value as binary. - -This method only works for OFTBinary and OFTString fields. +%feature("docstring") GetStyleString " -This function is the same as the C++ method -OGRFeature::GetFieldAsBinary(). +Fetch style string for this feature. -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnBytes: - location to place count of bytes returned. +Set the OGR Feature Style Specification for details on the format of +this string, and :source_file:`ogr/ogr_featurestyle.h` for services available to parse +it. +See :cpp:func:`OGRFeature::GetStyleString`. Returns -------- -list: - the field value. This list is internal, and should not be modified, or - freed. Its lifetime may be very brief. +str or None "; -%feature("docstring") GetFieldAsDateTime "int -OGR_F_GetFieldAsDateTime(OGRFeatureH hFeat, int iField, int \\*pnYear, -int \\*pnMonth, int \\*pnDay, int \\*pnHour, int \\*pnMinute, int \\*pnSecond, -int \\*pnTZFlag) - -Fetch field value as date and time. - -Currently this method only works for OFTDate, OFTTime and OFTDateTime -fields. +%feature("docstring") IsFieldNull " -This function is the same as the C++ method -OGRFeature::GetFieldAsDateTime(). +Test if a field is null. -.. note:: Use OGR_F_GetFieldAsDateTimeEx() for second with millisecond accuracy. +See :cpp:func:OGRFeature::`IsFieldNull`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnYear: - (including century) -pnMonth: - (1-12) -pnDay: - (1-31) -pnHour: - (0-23) -pnMinute: - (0-59) -pnSecond: - (0-59) -pnTZFlag: - (0=unknown, 1=localtime, 100=GMT, see data model for -details) +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - TRUE on success or FALSE on failure. +bool: + ``True`` if the field is null, otherwise ``False`` "; -%feature("docstring") GetFieldAsDateTimeEx "int -OGR_F_GetFieldAsDateTimeEx(OGRFeatureH hFeat, int iField, int \\*pnYear, -int \\*pnMonth, int \\*pnDay, int \\*pnHour, int \\*pnMinute, float \\*pfSecond, -int \\*pnTZFlag) - -Fetch field value as date and time. - -Currently this method only works for OFTDate, OFTTime and OFTDateTime -fields. +%feature("docstring") IsFieldSet " -This function is the same as the C++ method -OGRFeature::GetFieldAsDateTime(). +Test if a field has ever been assigned a value or not. -.. versionadded:: 2.0 +See :cpp:func:`OGRFeature::IsFieldSet`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pnYear: - (including century) -pnMonth: - (1-12) -pnDay: - (1-31) -pnHour: - (0-23) -pnMinute: - (0-59) -pfSecond: - (0-59 with millisecond accuracy) -pnTZFlag: - (0=unknown, 1=localtime, 100=GMT, see data model for -details) +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. Returns -------- -int: - TRUE on success or FALSE on failure. +bool: + ``True`` if the field has been set, otherwise ``False``. "; -%feature("docstring") OGRFeatureGetIntegerValue "static int -OGRFeatureGetIntegerValue(OGRFieldDefn \\*poFDefn, int nValue) "; - -%feature("docstring") SetFieldInteger "void -OGR_F_SetFieldInteger(OGRFeatureH hFeat, int iField, int nValue) - -Set field to integer value. - -OFTInteger, OFTInteger64 and OFTReal fields will be set directly. -OFTString fields will be assigned a string representation of the -value, but not necessarily taking into account formatting constraints -on this field. Other field types may be unaffected. +%feature("docstring") IsFieldSetAndNotNull " -This function is the same as the C++ method OGRFeature::SetField(). +Test if a field is set and not null. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +See :cpp:func:`OGRFeature::IsFieldSetAndNotNull`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -nValue: - the value to assign. -"; +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. -%feature("docstring") SetFieldInteger64 "void -OGR_F_SetFieldInteger64(OGRFeatureH hFeat, int iField, GIntBig nValue) - -Set field to 64 bit integer value. - -OFTInteger, OFTInteger64 and OFTReal fields will be set directly. -OFTString fields will be assigned a string representation of the -value, but not necessarily taking into account formatting constraints -on this field. Other field types may be unaffected. - -This function is the same as the C++ method OGRFeature::SetField(). - -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. - -.. versionadded:: 2.0 - -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -nValue: - the value to assign. +Returns +-------- +bool: + ``True`` if the field is set and not null, otherwise ``False``. "; -%feature("docstring") SetFieldDouble "void -OGR_F_SetFieldDouble(OGRFeatureH hFeat, int iField, double dfValue) +%feature("docstring") SetFID " -Set field to double value. - -OFTInteger, OFTInteger64 and OFTReal fields will be set directly. -OFTString fields will be assigned a string representation of the -value, but not necessarily taking into account formatting constraints -on this field. Other field types may be unaffected. +Set the feature identifier. -This function is the same as the C++ method OGRFeature::SetField(). +For specific types of features this operation may fail on illegal +features ids. Generally it always succeeds. Feature ids should be +greater than or equal to zero, with the exception of :py:const:NullFID` (-1) +indicating that the feature id is unknown. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +See :cpp:func:`OGRFeature::SetFID`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -dfValue: - the value to assign. -"; - -%feature("docstring") SetFieldString "void -OGR_F_SetFieldString(OGRFeatureH hFeat, int iField, const char -\\*pszValue) - -Set field to string value. - -OFTInteger fields will be set based on an atoi() conversion of the -string. OFTInteger64 fields will be set based on an CPLAtoGIntBig() -conversion of the string. OFTReal fields will be set based on an -CPLAtof() conversion of the string. Other field types may be -unaffected. - -This function is the same as the C++ method OGRFeature::SetField(). - -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +fid: + the new feature identifier value to assign. -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -pszValue: - the value to assign. +Returns +-------- +int: + :py:const:`OGRERR_NONE` on success, or some other value on failure. "; -%feature("docstring") SetFieldIntegerList "void -OGR_F_SetFieldIntegerList(OGRFeatureH hFeat, int iField, int nCount, -const int \\*panValues) +// SetFieldBinary documented inline -Set field to list of integers value. +%feature("docstring") SetFieldDoubleList " -This function currently on has an effect of OFTIntegerList, -OFTInteger64List and OFTRealList fields. +Set field to list of double values. -This function is the same as the C++ method OGRFeature::SetField(). +This function currently on has an effect of :py:const:`OFTIntegerList`, +:py:const:`OFTInteger64List`, :py:const:`OFTRealList` fields. + +See :cpp:func:`OGRFeature::SetField`. This method has only an effect on the in-memory feature object. If this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nCount: - the number of values in the list being assigned. -panValues: +id : int + the field to set, from 0 to :py:meth:`GetFieldCount`-1. +nList : list the values to assign. "; %feature("docstring") SetFieldInteger64List "void -OGR_F_SetFieldInteger64List(OGRFeatureH hFeat, int iField, int nCount, -const GIntBig \\*panValues) -Set field to list of 64 bit integers value. +Set field to list of 64 bit integer values. -This function currently on has an effect of OFTIntegerList, -OFTInteger64List and OFTRealList fields. +This function currently on has an effect of :py:const:`OFTIntegerList`, +:py:const:`OFTInteger64List`, :py:const:`OFTRealList` fields. -This function is the same as the C++ method OGRFeature::SetField(). +See :cpp:func:`OGRFeature::SetField`. This method has only an effect on the in-memory feature object. If this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. -.. versionadded:: 2.0 - Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nCount: - the number of values in the list being assigned. -panValues: +id : int + the field to set, from 0 to :py:meth:`GetFieldCount`-1. +nList : list the values to assign. "; -%feature("docstring") SetFieldDoubleList "void -OGR_F_SetFieldDoubleList(OGRFeatureH hFeat, int iField, int nCount, -const double \\*padfValues) +%feature("docstring") SetFieldIntegerList "void -Set field to list of doubles value. +Set field to list of integer values. -This function currently on has an effect of OFTIntegerList, -OFTInteger64List, OFTRealList fields. +This function currently on has an effect of :py:const:`OFTIntegerList`, +:py:const:`OFTInteger64List`, :py:const:`OFTRealList` fields. -This function is the same as the C++ method OGRFeature::SetField(). +See :cpp:func:`OGRFeature::SetField`. This method has only an effect on the in-memory feature object. If this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nCount: - the number of values in the list being assigned. -padfValues: +id : int + the field to set, from 0 to :py:meth:`GetFieldCount`-1. +nList : list the values to assign. "; -%feature("docstring") SetFieldStringList "void -OGR_F_SetFieldStringList(OGRFeatureH hFeat, int iField, CSLConstList -papszValues) - -Set field to list of strings value. - -This function currently on has an effect of OFTStringList fields. +%feature("docstring") SetFieldNull " -This function is the same as the C++ method OGRFeature::SetField(). +Clear a field, marking it as null. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. +See :cpp:func:`OGRFeature::SetFieldNull`. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -papszValues: - the values to assign. List of NUL-terminated string, -ending with a NULL pointer. -"; - -%feature("docstring") SetFieldBinary "void -OGR_F_SetFieldBinary(OGRFeatureH hFeat, int iField, int nBytes, const -void \\*pabyData) - -Set field to binary data. - -This function currently on has an effect of OFTBinary fields. - -This function is the same as the C++ method OGRFeature::SetField(). +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. - -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nBytes: - the number of bytes in pabyData array. -pabyData: - the data to apply. "; -%feature("docstring") SetFieldDateTime "void -OGR_F_SetFieldDateTime(OGRFeatureH hFeat, int iField, int nYear, int -nMonth, int nDay, int nHour, int nMinute, int nSecond, int nTZFlag) - -Set field to datetime. - -This method currently only has an effect for OFTDate, OFTTime and -OFTDateTime fields. +%feature("docstring") SetFieldString " -This method has only an effect on the in-memory feature object. If -this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be -used afterwards. - -.. note:: Use OGR_F_SetFieldDateTimeEx() for second with millisecond accuracy. - -Parameters ------------ -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nYear: - (including century) -nMonth: - (1-12) -nDay: - (1-31) -nHour: - (0-23) -nMinute: - (0-59) -nSecond: - (0-59) -nTZFlag: - (0=unknown, 1=localtime, 100=GMT, see data model for -details) -"; - -%feature("docstring") SetFieldDateTimeEx "void -OGR_F_SetFieldDateTimeEx(OGRFeatureH hFeat, int iField, int nYear, int -nMonth, int nDay, int nHour, int nMinute, float fSecond, int nTZFlag) +Set field to string value. -Set field to datetime. +:py:const:`OFTInteger` fields will be set based on an atoi() conversion of the +string. :py:const:`OFTInteger64` fields will be set based on an :cpp:func:`CPLAtoGIntBig` +conversion of the string. :py:const:`OFTReal` fields will be set based on an +:cpp:func:`CPLAtof` conversion of the string. Other field types may be +unaffected. -This method currently only has an effect for OFTDate, OFTTime and -OFTDateTime fields. +See :cpp:func:`OGRFeature::SetField`. This method has only an effect on the in-memory feature object. If this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. -.. versionadded:: 2.0 - Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to set, from 0 to GetFieldCount()-1. -nYear: - (including century) -nMonth: - (1-12) -nDay: - (1-31) -nHour: - (0-23) -nMinute: - (0-59) -fSecond: - (0-59, with millisecond accuracy) -nTZFlag: - (0=unknown, 1=localtime, 100=GMT, see data model for -details) +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. +value: + the value to assign. "; -%feature("docstring") SetFieldRaw "void -OGR_F_SetFieldRaw(OGRFeatureH hFeat, int iField, OGRField \\*psValue) +%feature("docstring") SetFieldStringList " -Set field. +Set field to list of strings value. -The passed value OGRField must be of exactly the same type as the -target field, or an application crash may occur. The passed value is -copied, and will not be affected. It remains the responsibility of the -caller. +This function currently only has an effect of :py:const:`OFTStringList` fields. -This function is the same as the C++ method OGRFeature::SetField(). +See :cpp:func:`OGRFeature::SetField`. This method has only an effect on the in-memory feature object. If this object comes from a layer and the modifications must be -serialized back to the datasource, OGR_L_SetFeature() must be used -afterwards. Or if this is a new feature, OGR_L_CreateFeature() must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be used afterwards. Parameters ----------- -hFeat: - handle to the feature that owned the field. -iField: - the field to fetch, from 0 to GetFieldCount()-1. -psValue: - handle on the value to assign. -"; - -%feature("docstring") DumpReadable "void -OGR_F_DumpReadable(OGRFeatureH hFeat, FILE \\*fpOut) - -Dump this feature in a human readable form. - -This dumps the attributes, and geometry; however, it doesn't -definition information (other than field types and names), nor does it -report the geometry spatial reference system. - -This function is the same as the C++ method -OGRFeature::DumpReadable(). - -Parameters ------------ -hFeat: - handle to the feature to dump. -fpOut: - the stream to write to, such as strout. -"; - -%feature("docstring") GetFID "GIntBig OGR_F_GetFID(OGRFeatureH -hFeat) - -Get feature identifier. - -This function is the same as the C++ method OGRFeature::GetFID(). -Note: since GDAL 2.0, this method returns a GIntBig (previously a -long) - -Parameters ------------ -hFeat: - handle to the feature from which to get the feature -identifier. - -Returns -------- -int: - feature id or OGRNullFID if none has been assigned. -"; - -%feature("docstring") SetFID "OGRErr OGR_F_SetFID(OGRFeatureH hFeat, -GIntBig nFID) - -Set the feature identifier. - -For specific types of features this operation may fail on illegal -features ids. Generally it always succeeds. Feature ids should be -greater than or equal to zero, with the exception of OGRNullFID (-1) -indicating that the feature id is unknown. - -This function is the same as the C++ method OGRFeature::SetFID(). - -Parameters ------------ -hFeat: - handle to the feature to set the feature id to. -nFID: - the new feature identifier value to assign. - -Returns --------- -OGRErr: - On success OGRERR_NONE, or on failure some other value. -"; - -%feature("docstring") Equal "int OGR_F_Equal(OGRFeatureH hFeat, -OGRFeatureH hOtherFeat) - -Test if two features are the same. - -Two features are considered equal if the share them (handle equality) -same OGRFeatureDefn, have the same field values, and the same geometry -(as tested by OGR_G_Equal()) as well as the same feature id. - -This function is the same as the C++ method OGRFeature::Equal(). - -Parameters ------------ -hFeat: - handle to one of the feature. -hOtherFeat: - handle to the other feature to test this one against. - -Returns --------- -int: - TRUE if they are equal, otherwise FALSE. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. +value: + the value to assign. "; -%feature("docstring") SetFrom "OGRErr OGR_F_SetFrom(OGRFeatureH -hFeat, OGRFeatureH hOtherFeat, int bForgiving) - +%feature("docstring") SetFrom " Set one feature from another. Overwrite the contents of this feature from the geometry and -attributes of another. The hOtherFeature does not need to have the -same OGRFeatureDefn. Field values are copied by corresponding field +attributes of another. The other feature does not need to have the +same :py:class:`FeatureDefn`. Field values are copied by corresponding field names. Field types do not have to exactly match. OGR_F_SetField\\*() function conversion rules will be applied as needed. -This function is the same as the C++ method OGRFeature::SetFrom(). +See :cpp:func:`OGRFeature::SetFrom`. Parameters ----------- -hFeat: - handle to the feature to set to. -hOtherFeat: - handle to the feature from which geometry, and field - values will be copied. -bForgiving: - TRUE if the operation should continue despite lacking +other : Feature + feature from which geometry and field values will be copied. +forgiving : bool, default = True + ``True`` if the operation should continue despite lacking output fields matching some of the source fields. Returns -------- -OGRErr: - OGRERR_NONE if the operation succeeds, even if some values are not +int: + :py:const:`OGRERR_NONE` if the operation succeeds, even if some values are not transferred, otherwise an error code. "; -%feature("docstring") SetFromWithMap "OGRErr -OGR_F_SetFromWithMap(OGRFeatureH hFeat, OGRFeatureH hOtherFeat, int -bForgiving, const int \\*panMap) +%feature("docstring") SetFromWithMap " Set one feature from another. Overwrite the contents of this feature from the geometry and -attributes of another. The hOtherFeature does not need to have the -same OGRFeatureDefn. Field values are copied according to the provided +attributes of another. The other feature does not need to have the +same :py:class:`FeatureDefn`. Field values are copied according to the provided indices map. Field types do not have to exactly match. OGR_F_SetField\\*() function conversion rules will be applied as needed. -This is more efficient than OGR_F_SetFrom() in that this doesn't +This is more efficient than :py:meth:SetFrom` in that this doesn't lookup the fields by their names. Particularly useful when the field names don't match. -This function is the same as the C++ method OGRFeature::SetFrom(). +See :cpp:func:`OGRFeature::SetFrom`. Parameters ----------- -hFeat: - handle to the feature to set to. -hOtherFeat: +other : Feature handle to the feature from which geometry, and field values will be copied. -panMap: +forgiving : bool + ``True`` if the operation should continue despite lacking + output fields matching some of the source fields. +nList : list Array of the indices of the destination feature's fields stored at the corresponding index of the source feature's fields. A value of -1 should be used to ignore the source's field. The array should not be NULL and be as long as the number of fields in the source feature. -bForgiving: - TRUE if the operation should continue despite lacking - output fields matching some of the source fields. Returns -------- OGRErr: - OGRERR_NONE if the operation succeeds, even if some values are not + :py:const:`OGRERR_NONE` if the operation succeeds, even if some values are not transferred, otherwise an error code. "; -%feature("docstring") GetStyleString "const char\\* -OGR_F_GetStyleString(OGRFeatureH hFeat) +%feature("docstring") SetGeomField " -Fetch style string for this feature. +Set feature geometry of a specified geometry field. -Set the OGR Feature Style Specification for details on the format of -this string, and ogr_featurestyle.h for services available to parse -it. +This function updates the features geometry, and operates exactly as +:py:meth:`SetGeomFieldDirectly`, except that this function does not assume +ownership of the passed geometry, but instead makes a copy of it. -This function is the same as the C++ method -OGRFeature::GetStyleString(). +See :cpp:func:`OGRFeature::SetGeomField`. Parameters ----------- -hFeat: - handle to the feature to get the style from. +fld_index : int / str + Geometry field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. +geom : Geometry + handle to the new geometry to apply to feature. Returns -------- -str: - a reference to a representation in string format, or NULL if there - isn't one. -"; - -%feature("docstring") SetStyleString "void -OGR_F_SetStyleString(OGRFeatureH hFeat, const char \\*pszStyle) - -Set feature style string. - -This method operate exactly as OGR_F_SetStyleStringDirectly() except -that it does not assume ownership of the passed string, but instead -makes a copy of it. - -This function is the same as the C++ method -OGRFeature::SetStyleString(). - -Parameters ------------ -hFeat: - handle to the feature to set style to. -pszStyle: - the style string to apply to this feature, cannot be NULL. -"; - -%feature("docstring") SetStyleStringDirectly "void -OGR_F_SetStyleStringDirectly(OGRFeatureH hFeat, char \\*pszStyle) - -Set feature style string. - -This method operate exactly as OGR_F_SetStyleString() except that it -assumes ownership of the passed string. - -This function is the same as the C++ method -OGRFeature::SetStyleStringDirectly(). - -Parameters ------------ -hFeat: - handle to the feature to set style to. -pszStyle: - the style string to apply to this feature, cannot be NULL. -"; - -%feature("docstring") GetStyleTable "OGRStyleTableH -OGR_F_GetStyleTable(OGRFeatureH hFeat) - -Return style table. "; - -%feature("docstring") SetStyleTableDirectly "void -OGR_F_SetStyleTableDirectly(OGRFeatureH hFeat, OGRStyleTableH -hStyleTable) - -Set style table and take ownership. "; - -%feature("docstring") SetStyleTable "void -OGR_F_SetStyleTable(OGRFeatureH hFeat, OGRStyleTableH hStyleTable) - -Set style table. "; - -%feature("docstring") FillUnsetWithDefault "void -OGR_F_FillUnsetWithDefault(OGRFeatureH hFeat, int bNotNullableOnly, -char \\*\\*papszOptions) - -Fill unset fields with default values that might be defined. - -This function is the same as the C++ method -OGRFeature::FillUnsetWithDefault(). - -.. versionadded:: 2.0 - -Parameters ------------ -hFeat: - handle to the feature. -bNotNullableOnly: - if we should fill only unset fields with a not-null - constraint. -papszOptions: - unused currently. Must be set to NULL. -"; - -%feature("docstring") Validate "int OGR_F_Validate(OGRFeatureH -hFeat, int nValidateFlags, int bEmitError) - -Validate that a feature meets constraints of its schema. - -The scope of test is specified with the nValidateFlags parameter. - -Regarding OGR_F_VAL_WIDTH, the test is done assuming the string width -must be interpreted as the number of UTF-8 characters. Some drivers -might interpret the width as the number of bytes instead. So this test -is rather conservative (if it fails, then it will fail for all -interpretations). - -This function is the same as the C++ method OGRFeature::Validate(). - -.. versionadded:: 2.0 - -Parameters ------------ -hFeat: - handle to the feature to validate. -nValidateFlags: - OGR_F_VAL_ALL or combination of OGR_F_VAL_NULL, - OGR_F_VAL_GEOM_TYPE, OGR_F_VAL_WIDTH and - OGR_F_VAL_ALLOW_NULL_WHEN_DEFAULT with '|' operator -bEmitError: - TRUE if a CPLError() must be emitted when a check fails - -Returns -------- int: - TRUE if all enabled validation tests pass. -"; - -%feature("docstring") GetNativeData "const char\\* -OGR_F_GetNativeData(OGRFeatureH hFeat) - -Returns the native data for the feature. - -The native data is the representation in a \"natural\" form that comes -from the driver that created this feature, or that is aimed at an -output driver. The native data may be in different format, which is -indicated by OGR_F_GetNativeMediaType(). - -Note that most drivers do not support storing the native data in the -feature object, and if they do, generally the NATIVE_DATA open option -must be passed at dataset opening. - -The \"native data\" does not imply it is something more performant or -powerful than what can be obtained with the rest of the API, but it -may be useful in round-tripping scenarios where some characteristics -of the underlying format are not captured otherwise by the OGR -abstraction. - -This function is the same as the C++ method -OGRFeature::GetNativeData(). - -.. note:: See https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr - -.. versionadded:: 2.1 - -Parameters ------------ -hFeat: - handle to the feature. - -Returns -------- -str: - a string with the native data, or NULL if there is none. + :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). "; -%feature("docstring") GetNativeMediaType "const char\\* -OGR_F_GetNativeMediaType(OGRFeatureH hFeat) +// SetGeomFieldDirectly : documented inline -Returns the native media type for the feature. +%feature("docstring") SetGeometry " -The native media type is the identifier for the format of the native -data. It follows the IANA RFC 2045 -(seehttps://en.wikipedia.org/wiki/Media_type), e.g. -\"application/vnd.geo+json\" for JSon. +Set feature geometry. -This function is the same as the C function -OGR_F_GetNativeMediaType(). +This function updates the features geometry, and operates exactly as +:py:meth:`SetGeometryDirectly`, except that this function does not assume +ownership of the passed geometry, but instead makes a copy of it. -.. note:: See https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr +See :cpp:func:`OGRFeature::SetGeometry`. -.. versionadded:: 2.1 +This method has only an effect on the in-memory feature object. If +this object comes from a layer and the modifications must be +serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used +afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be +used afterwards. Parameters ----------- -hFeat: - handle to the feature. - +geom : Geometry + new geometry to apply to feature. Returns -------- -str: - a string with the native media type, or NULL if there is none. +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). "; -%feature("docstring") SetNativeData "void -OGR_F_SetNativeData(OGRFeatureH hFeat, const char \\*pszNativeData) +// SetGeometryDirectly : documented inline + +%feature("docstring") SetNativeData " Sets the native data for the feature. The native data is the representation in a \"natural\" form that comes from the driver that created this feature, or that is aimed at an output driver. The native data may be in different format, which is -indicated by OGR_F_GetNativeMediaType(). - -This function is the same as the C++ method -OGRFeature::SetNativeData(). +indicated by :py:meth:`GetNativeMediaType`. -.. note:: See https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr - -.. versionadded:: 2.1 +See :cpp:func:`OGRFeature::SetNativeData` and :ref:`rfc-60`. Parameters ----------- -hFeat: - handle to the feature. -pszNativeData: - a string with the native data, or NULL if there is none. +nativeData : str + a string with the native data, or ``None`` "; -%feature("docstring") SetNativeMediaType "void -OGR_F_SetNativeMediaType(OGRFeatureH hFeat, const char -\\*pszNativeMediaType) +%feature("docstring") SetNativeMediaType " Sets the native media type for the feature. The native media type is the identifier for the format of the native data. It follows the IANA RFC 2045 -(seehttps://en.wikipedia.org/wiki/Media_type), e.g. +(see https://en.wikipedia.org/wiki/Media_type), e.g. \"application/vnd.geo+json\" for JSon. -This function is the same as the C++ method -OGRFeature::SetNativeMediaType(). - -.. note:: See https://trac.osgeo.org/gdal/wiki/rfc60_improved_roundtripping_in_ogr - -.. versionadded:: 2.1 - +See :cpp:func:`OGRFeature::SetNativeMediaType` and :ref:`rfc-60`. Parameters ----------- -hFeat: - handle to the feature. -pszNativeMediaType: - a string with the native media type, or NULL if there is none. +nativeMediaType : str + a string with the native media type, or ``None`` "; -%feature("docstring") OGR_RawField_IsUnset "int -OGR_RawField_IsUnset(const OGRField \\*puField) - -Returns whether a raw field is unset. +%feature("docstring") SetStyleString " -Note: this function is rather low-level and should be rarely used in -client code. Use instead OGR_F_IsFieldSet(). +Set feature style string. -.. versionadded:: 2.2 +See :cpp:func:`OGRFeature::SetStyleString`. Parameters ----------- -puField: - pointer to raw field. +the_string : str + the style string to apply to this feature "; -%feature("docstring") OGR_RawField_IsNull "int -OGR_RawField_IsNull(const OGRField \\*puField) - -Returns whether a raw field is null. +%feature("docstring") UnsetField " -Note: this function is rather low-level and should be rarely used in -client code. Use instead OGR_F_IsFieldNull(). +Clear a field, marking it as unset. -.. versionadded:: 2.2 +See :cpp:func:`OGRFeature::UnsetField`. Parameters ----------- -puField: - pointer to raw field. +fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. "; -%feature("docstring") OGR_RawField_SetUnset "void -OGR_RawField_SetUnset(OGRField \\*puField) +%feature("docstring") Validate " -Mark a raw field as unset. +Validate that a feature meets constraints of its schema. -This should be called on a un-initialized field. In particular this -will not free any memory dynamically allocated. +The scope of test is specified with the ``flags`` parameter. -Note: this function is rather low-level and should be rarely used in -client code. Use instead OGR_F_UnsetField(). +Regarding :py:const:`OGR_F_VAL_WIDTH`, the test is done assuming the string +width must be interpreted as the number of UTF-8 characters. Some drivers might +interpret the width as the number of bytes instead. So this test is rather +conservative (if it fails, then it will fail for all interpretations). -.. versionadded:: 2.2 +See :cpp:func:`OGRFeature::Validate`. Parameters ----------- -puField: - pointer to raw field. -"; - -%feature("docstring") OGR_RawField_SetNull "void -OGR_RawField_SetNull(OGRField \\*puField) - -Mark a raw field as null. - -This should be called on a un-initialized field. In particular this -will not free any memory dynamically allocated. - -Note: this function is rather low-level and should be rarely used in -client code. Use instead OGR_F_SetFieldNull(). - -.. versionadded:: 2.2 +flags : int, default = :py:const:`F_VAL_ALL` + One ore more of :py:const:`OGR_F_VAL_NULL`, + :py:const:`OGR_F_VAL_GEOM_TYPE`, py:const:`OGR_F_VAL_WIDTH` and + :py:const:`OGR_F_VAL_ALLOW_NULL_WHEN_DEFAULT` combined with + the with ``|`` operator +bEmitError : bool, default = True + TRUE if a CPLError() must be emitted when a check fails -Parameters ------------ -puField: - pointer to raw field. +Returns +------- +int: + TRUE if all enabled validation tests pass. "; } diff --git a/swig/include/python/ogr_python.i b/swig/include/python/ogr_python.i index 35b10f57a9a0..efbcae5647ab 100644 --- a/swig/include/python/ogr_python.i +++ b/swig/include/python/ogr_python.i @@ -830,6 +830,36 @@ def ReleaseResultSet(self, sql_lyr): return self._SetField2(fld_index, value) def GetField(self, fld_index): + """ + Get the value of a field in its native type. + + Alternatively, the ``[]`` operator may be used. + + Parameters + ---------- + fld_index : int / str + Field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. + + Examples + -------- + >>> with gdal.OpenEx("data/poly.shp") as ds: + ... lyr = ds.GetLayer(0) + ... feature = lyr.GetNextFeature() + ... # name-based access + ... feature.GetField("EAS_ID") + ... feature["EAS_ID"] + ... # index-based access + ... index = feature.GetFieldIndex("EAS_ID") + ... feature.GetField(index) + ... feature[index] + ... + 168 + 168 + 168 + 168 + """ if isinstance(fld_index, str): fld_index = self._getfieldindex(fld_index) if (fld_index < 0) or (fld_index > self.GetFieldCount()): @@ -870,8 +900,8 @@ def ReleaseResultSet(self, sql_lyr): SetFieldBinary(Feature self, field_index_or_name: int | str, value: bytes) Set field to binary data. - This function currently only has an effect on OFTBinary fields. - This function is the same as the C++ method OGRFeature::SetField(). + This function currently only has an effect on :py:const:`OFTBinary` fields. + This function is the same as the C++ method :cpp:func:`OGRFeature::SetField`. Parameters ----------- @@ -965,11 +995,20 @@ def ReleaseResultSet(self, sql_lyr): def ExportToJson(self, as_object=False, options=None): - """Exports a GeoJSON object which represents the Feature. The - as_object parameter determines whether the returned value - should be a Python object instead of a string. Defaults to False. - The options parameter is passed to Geometry.ExportToJson()""" + """ + Export a GeoJSON object which represents the Feature. + Parameters + ---------- + as_object : bool, default = False + determines whether the returned value should be a Python object instead of a string. + options : dict/str + Options to pass to :py:func:`Geometry.ExportToJson` + + Returns + ------- + str / dict + """ try: import simplejson except ImportError: @@ -1030,6 +1069,33 @@ def ReleaseResultSet(self, sql_lyr): %feature("shadow") SetGeometryDirectly %{ def SetGeometryDirectly(self, geom): + """ + Set feature geometry. + + This function updates the features geometry, and operates exactly as + :py:meth:`SetGeometry`, except that this function assumes ownership of the + passed geometry (even in case of failure of that function). + + See :cpp:func:`OGRFeature::SetGeometryDirectly`. + + This method has only an effect on the in-memory feature object. If + this object comes from a layer and the modifications must be + serialized back to the datasource, :py:meth:`Layer.SetFeature` must be used + afterwards. Or if this is a new feature, :py:meth:`Layer.CreateFeature` must be + used afterwards. + + Parameters + ----------- + geom : Geometry + geometry to apply to feature. + + Returns + -------- + 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). + """ ret = $action(self, geom) if ret == OGRERR_NONE: self._add_geom_ref(geom) @@ -1038,6 +1104,31 @@ def ReleaseResultSet(self, sql_lyr): %feature("shadow") SetGeomFieldDirectly %{ def SetGeomFieldDirectly(self, field, geom): + """ + Set feature geometry of a specified geometry field. + + This function updates the features geometry, and operates exactly as + :py:meth:`SetGeomField`, except that this function assumes ownership of the + passed geometry (even in case of failure of that function). + + See :cpp:func:`OGRFeature::SetGeomFieldDirectly`. + + Parameters + ----------- + fld_index : int / str + Geometry field name or 0-based numeric index. For repeated + access, use of the numeric index avoids a lookup + step. + geom : Geometry + handle to the new geometry to apply to feature. + + Returns + -------- + 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). + """ ret = $action(self, field, geom) if ret == OGRERR_NONE: self._add_geom_ref(geom)