diff --git a/python/core/auto_generated/geometry/qgscurvepolygon.sip.in b/python/core/auto_generated/geometry/qgscurvepolygon.sip.in index e60b15d8dd3a..967fc6e7c25b 100644 --- a/python/core/auto_generated/geometry/qgscurvepolygon.sip.in +++ b/python/core/auto_generated/geometry/qgscurvepolygon.sip.in @@ -95,7 +95,7 @@ Returns the curve polygon's exterior ring. %Docstring Retrieves an interior ring from the curve polygon. The first interior ring has index 0. -An IndexError will be raised if no interior ring with the specified index exists. +:raises IndexError: if no interior ring with the specified index exists. .. seealso:: :py:func:`numInteriorRings` @@ -151,7 +151,7 @@ Removes an interior ring from the polygon. The first interior ring has index 0. The corresponding ring is removed from the polygon and deleted. It is not possible to remove the exterior ring using this method. -An IndexError will be raised if no interior ring with the specified index exists. +:raises IndexError: if no interior ring with the specified index exists. .. seealso:: :py:func:`removeInteriorRings` %End diff --git a/python/core/auto_generated/geometry/qgsgeometry.sip.in b/python/core/auto_generated/geometry/qgsgeometry.sip.in index ccbdb0d02576..dc1913bceed1 100644 --- a/python/core/auto_generated/geometry/qgsgeometry.sip.in +++ b/python/core/auto_generated/geometry/qgsgeometry.sip.in @@ -1694,9 +1694,11 @@ Returns a list of ``count`` random points generated inside a (multi)polygon geom Optionally, a specific random ``seed`` can be used when generating points. If ``seed`` is 0, then a completely random sequence of points will be generated. -This method works only with (multi)polygon geometry types. If the geometry -is not a polygon type, a TypeError will be raised. If the geometry -is null, a ValueError will be raised. +This method works only with (multi)polygon geometry types. + +:raises TypeError: if the geometry is not a polygon type + +:raises ValueError: if the geometry is null .. versionadded:: 3.10 %End @@ -1823,9 +1825,11 @@ Returns the contents of the geometry as a 2-dimensional point. Any z or m values present in the geometry will be discarded. -This method works only with single-point geometry types. If the geometry -is not a single-point type, a TypeError will be raised. If the geometry -is null, a ValueError will be raised. +This method works only with single-point geometry types. + +:raises TypeError: if the geometry is not a single-point type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); @@ -1853,9 +1857,11 @@ Returns the contents of the geometry as a polyline. Any z or m values present in the geometry will be discarded. If the geometry is a curved line type (such as a CircularString), it will be automatically segmentized. -This method works only with single-line (or single-curve) geometry types. If the geometry -is not a single-line type, a TypeError will be raised. If the geometry is null, a ValueError -will be raised. +This method works only with single-line (or single-curve). + +:raises TypeError: if the geometry is not a single-line type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); @@ -1884,9 +1890,11 @@ Returns the contents of the geometry as a polygon. Any z or m values present in the geometry will be discarded. If the geometry is a curved polygon type (such as a CurvePolygon), it will be automatically segmentized. -This method works only with single-polygon (or single-curve polygon) geometry types. If the geometry -is not a single-polygon type, a TypeError will be raised. If the geometry is null, a ValueError -will be raised. +This method works only with single-polygon (or single-curve polygon) geometry types. + +:raises TypeError: if the geometry is not a single-polygon type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); @@ -1914,9 +1922,11 @@ Returns the contents of the geometry as a multi-point. Any z or m values present in the geometry will be discarded. -This method works only with multi-point geometry types. If the geometry -is not a multi-point type, a TypeError will be raised. If the geometry is null, a ValueError -will be raised. +This method works only with multi-point geometry types. + +:raises TypeError: if the geometry is not a multi-point type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); @@ -1945,9 +1955,11 @@ Returns the contents of the geometry as a multi-linestring. Any z or m values present in the geometry will be discarded. If the geometry is a curved line type (such as a MultiCurve), it will be automatically segmentized. -This method works only with multi-linestring (or multi-curve) geometry types. If the geometry -is not a multi-linestring type, a TypeError will be raised. If the geometry is null, a ValueError -will be raised. +This method works only with multi-linestring (or multi-curve) geometry types. + +:raises TypeError: if the geometry is not a multi-linestring type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); @@ -1976,9 +1988,11 @@ Returns the contents of the geometry as a multi-polygon. Any z or m values present in the geometry will be discarded. If the geometry is a curved polygon type (such as a MultiSurface), it will be automatically segmentized. -This method works only with multi-polygon (or multi-curve polygon) geometry types. If the geometry -is not a multi-polygon type, a TypeError will be raised. If the geometry is null, a ValueError -will be raised. +This method works only with multi-polygon (or multi-curve polygon) geometry types. + +:raises TypeError: if the geometry is not a multi-polygon type + +:raises ValueError: if the geometry is null %End %MethodCode const QgsWkbTypes::Type type = sipCpp->wkbType(); diff --git a/python/core/auto_generated/geometry/qgsgeometrycollection.sip.in b/python/core/auto_generated/geometry/qgsgeometrycollection.sip.in index 99d0d84c6f10..0579b70d11b5 100644 --- a/python/core/auto_generated/geometry/qgsgeometrycollection.sip.in +++ b/python/core/auto_generated/geometry/qgsgeometrycollection.sip.in @@ -69,7 +69,9 @@ Returns the number of geometries within the collection. %Docstring Returns a geometry from within the collection. -:param n: index of geometry to return. An IndexError will be raised if no geometry with the specified index exists. +:param n: index of geometry to return. + +:raises IndexError: if no geometry with the specified index exists. %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->numGeometries() ) @@ -133,9 +135,9 @@ Inserts a geometry before a specified index and takes ownership. Returns ``True` %Docstring Removes a geometry from the collection by index. -An IndexError will be raised if no geometry with the specified index exists. - :return: ``True`` if removal was successful. + +:raises IndexError: if no geometry with the specified index exists. %End %MethodCode const int count = sipCpp->numGeometries(); @@ -256,11 +258,13 @@ Returns a geometry without curves. Caller takes ownership SIP_PYOBJECT __getitem__( int index ) /TypeHint="QgsAbstractGeometry"/; %Docstring -Returns the geometry at the specified ``index``. An IndexError will be raised if no geometry with the specified ``index`` exists. +Returns the geometry at the specified ``index``. Indexes can be less than 0, in which case they correspond to geometries from the end of the collect. E.g. an index of -1 corresponds to the last geometry in the collection. +:raises IndexError: if no geometry with the specified ``index`` exists. + .. versionadded:: 3.6 %End %MethodCode @@ -282,11 +286,13 @@ corresponds to the last geometry in the collection. void __delitem__( int index ); %Docstring -Deletes the geometry at the specified ``index``. A geometry at the ``index`` must already exist or an IndexError will be raised. +Deletes the geometry at the specified ``index``. Indexes can be less than 0, in which case they correspond to geometries from the end of the collection. E.g. an index of -1 corresponds to the last geometry in the collection. +:raises IndexError: if no geometry at the ``index`` exists + .. versionadded:: 3.6 %End %MethodCode diff --git a/python/core/auto_generated/geometry/qgslinestring.sip.in b/python/core/auto_generated/geometry/qgslinestring.sip.in index b32b4648c7c2..642f1d50c2ae 100644 --- a/python/core/auto_generated/geometry/qgslinestring.sip.in +++ b/python/core/auto_generated/geometry/qgslinestring.sip.in @@ -274,10 +274,12 @@ Returns a new linestring from a QPolygonF ``polygon`` input. SIP_PYOBJECT pointN( int i ) const /TypeHint="QgsPoint"/; %Docstring -Returns the point at the specified index. An IndexError will be raised if no point with the specified index exists. +Returns the point at the specified index. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. + +:raises IndexError: if no point with the specified index exists. %End %MethodCode const int count = sipCpp->numPoints(); @@ -303,10 +305,10 @@ corresponds to the last point in the line. %Docstring Returns the x-coordinate of the specified node in the line string. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. + +:raises IndexError: if no point with the specified index exists. %End %MethodCode const int count = sipCpp->numPoints(); @@ -330,10 +332,10 @@ corresponds to the last point in the line. %Docstring Returns the y-coordinate of the specified node in the line string. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. + +:raises IndexError: if no point with the specified index exists. %End %MethodCode const int count = sipCpp->numPoints(); @@ -360,12 +362,12 @@ corresponds to the last point in the line. %Docstring Returns the z-coordinate of the specified node in the line string. -An IndexError will be raised if no point with the specified index exists. - If the LineString does not have a z-dimension then ``nan`` will be returned. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. + +:raises IndexError: if no point with the specified index exists. %End %MethodCode const int count = sipCpp->numPoints(); @@ -388,12 +390,12 @@ corresponds to the last point in the line. %Docstring Returns the m-coordinate of the specified node in the line string. -An IndexError will be raised if no point with the specified index exists. - If the LineString does not have a m-dimension then ``nan`` will be returned. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. + +:raises IndexError: if no point with the specified index exists. %End %MethodCode const int count = sipCpp->numPoints(); @@ -417,11 +419,11 @@ corresponds to the last point in the line. Sets the x-coordinate of the specified node in the line string. The corresponding node must already exist in line string. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified index exists. + .. seealso:: :py:func:`xAt` %End %MethodCode @@ -446,11 +448,11 @@ corresponds to the last point in the line. Sets the y-coordinate of the specified node in the line string. The corresponding node must already exist in line string. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified index exists. + .. seealso:: :py:func:`yAt` %End %MethodCode @@ -475,11 +477,11 @@ corresponds to the last point in the line. Sets the z-coordinate of the specified node in the line string. The corresponding node must already exist in line string and the line string must have z-dimension. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified index exists. + .. seealso:: :py:func:`zAt` %End %MethodCode @@ -504,11 +506,11 @@ corresponds to the last point in the line. Sets the m-coordinate of the specified node in the line string. The corresponding node must already exist in line string and the line string must have m-dimension. -An IndexError will be raised if no point with the specified index exists. - Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified index exists. + .. seealso:: :py:func:`mAt` %End %MethodCode @@ -736,11 +738,13 @@ of the curve. SIP_PYOBJECT __getitem__( int index ) /TypeHint="QgsPoint"/; %Docstring -Returns the point at the specified ``index``. An IndexError will be raised if no point with the specified ``index`` exists. +Returns the point at the specified ``index``. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified ``index`` exists. + .. versionadded:: 3.6 %End %MethodCode @@ -763,11 +767,13 @@ corresponds to the last point in the line. void __setitem__( int index, const QgsPoint &point ); %Docstring -Sets the point at the specified ``index``. A point at the ``index`` must already exist or an IndexError will be raised. +Sets the point at the specified ``index``. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified ``index`` exists. + .. versionadded:: 3.6 %End %MethodCode @@ -793,11 +799,13 @@ corresponds to the last point in the line. void __delitem__( int index ); %Docstring -Deletes the vertex at the specified ``index``. A point at the ``index`` must already exist or an IndexError will be raised. +Deletes the vertex at the specified ``index``. Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 corresponds to the last point in the line. +:raises IndexError: if no point with the specified ``index`` exists. + .. versionadded:: 3.6 %End %MethodCode diff --git a/python/core/auto_generated/geometry/qgsmulticurve.sip.in b/python/core/auto_generated/geometry/qgsmulticurve.sip.in index 25c0e3fcb285..178557c120e4 100644 --- a/python/core/auto_generated/geometry/qgsmulticurve.sip.in +++ b/python/core/auto_generated/geometry/qgsmulticurve.sip.in @@ -28,7 +28,7 @@ Multi curve geometry collection. %Docstring Returns the curve with the specified ``index``. -An IndexError will be raised if no curve with the specified index exists. +:raises IndexError: if no curve with the specified index exists. .. versionadded:: 3.16 %End diff --git a/python/core/auto_generated/geometry/qgsmultilinestring.sip.in b/python/core/auto_generated/geometry/qgsmultilinestring.sip.in index 4dce019c38e7..bd1164eeec49 100644 --- a/python/core/auto_generated/geometry/qgsmultilinestring.sip.in +++ b/python/core/auto_generated/geometry/qgsmultilinestring.sip.in @@ -33,7 +33,7 @@ Constructor for an empty multilinestring geometry. %Docstring Returns the line string with the specified ``index``. -An IndexError will be raised if no line string with the specified index exists. +:raises IndexError: if no line string with the specified index exists. .. versionadded:: 3.16 %End diff --git a/python/core/auto_generated/geometry/qgsmultipoint.sip.in b/python/core/auto_generated/geometry/qgsmultipoint.sip.in index aa5d0a6a0b95..19f81ef506ae 100644 --- a/python/core/auto_generated/geometry/qgsmultipoint.sip.in +++ b/python/core/auto_generated/geometry/qgsmultipoint.sip.in @@ -31,7 +31,7 @@ Constructor for an empty multipoint geometry. %Docstring Returns the point with the specified ``index``. -An IndexError will be raised if no point with the specified index exists. +:raises IndexError: if no point with the specified index exists. .. versionadded:: 3.16 %End diff --git a/python/core/auto_generated/geometry/qgsmultipolygon.sip.in b/python/core/auto_generated/geometry/qgsmultipolygon.sip.in index 5be5aacb96eb..e43c7a4ce116 100644 --- a/python/core/auto_generated/geometry/qgsmultipolygon.sip.in +++ b/python/core/auto_generated/geometry/qgsmultipolygon.sip.in @@ -33,7 +33,7 @@ Constructor for an empty multipolygon geometry. %Docstring Returns the polygon with the specified ``index``. -An IndexError will be raised if no polygon with the specified index exists. +:raises IndexError: if no polygon with the specified index exists. .. versionadded:: 3.16 %End diff --git a/python/core/auto_generated/geometry/qgsmultisurface.sip.in b/python/core/auto_generated/geometry/qgsmultisurface.sip.in index b7416bd900d9..38b05a142b5c 100644 --- a/python/core/auto_generated/geometry/qgsmultisurface.sip.in +++ b/python/core/auto_generated/geometry/qgsmultisurface.sip.in @@ -33,7 +33,7 @@ Constructor for an empty multisurface geometry. %Docstring Returns the surface with the specified ``index``. -An IndexError will be raised if no surface with the specified index exists. +:raises IndexError: if no surface with the specified index exists. .. versionadded:: 3.16 %End diff --git a/python/core/auto_generated/qgsfeature.sip.in b/python/core/auto_generated/qgsfeature.sip.in index fda563ae0fbe..81b987cd2cd9 100644 --- a/python/core/auto_generated/qgsfeature.sip.in +++ b/python/core/auto_generated/qgsfeature.sip.in @@ -219,6 +219,7 @@ number of the feature's fields. provider. %End + bool setAttribute( int field, const QVariant &attr /GetWrapper/ ); %Docstring Set an attribute's value by field index. @@ -227,11 +228,7 @@ The feature will be valid if it was successful. :param field: the index of the field to set :param attr: the value of the attribute -:return: ``False``, if the field index does not exist - -.. note:: - - For Python: raises a KeyError exception instead of returning ``False`` +:raises KeyError: if the field index does not exist .. note:: @@ -295,6 +292,7 @@ Resizes the attributes attached to this feature by appending the specified ``cou .. versionadded:: 3.18 %End + void deleteAttribute( int field ); %Docstring Deletes an attribute and its value. @@ -303,9 +301,7 @@ Deletes an attribute and its value. .. seealso:: :py:func:`setAttribute` -.. note:: - - For Python: raises a KeyError exception if the field is not found +:raises KeyError: if the field is not found .. note:: @@ -439,6 +435,7 @@ Returns the field map associated with the feature. .. seealso:: :py:func:`setFields` %End + void setAttribute( const QString &name, const QVariant &value /GetWrapper/ ); %Docstring Insert a value into attribute. Returns ``False`` if attribute name could not be converted to index. @@ -448,11 +445,7 @@ The feature will be valid if it was successful :param name: The name of the field to set :param value: The value to set -:return: ``False`` if attribute name could not be converted to index (C++ only) - -.. note:: - - For Python: raises a KeyError exception instead of returning ``False`` +:raises KeyError: if the attribute name could not be converted to an index .. note:: @@ -480,6 +473,7 @@ The feature will be valid if it was successful } %End + bool deleteAttribute( const QString &name ); %Docstring Removes an attribute value by field name. Field map must be associated using :py:func:`~QgsFeature.setFields` @@ -487,11 +481,7 @@ before this method can be used. :param name: The name of the field to delete -:return: ``False`` if attribute name could not be converted to index (C++ only) - -.. note:: - - For Python: raises a KeyError exception instead of returning ``False`` +:raises KeyError: if attribute name could not be converted to index .. note:: @@ -514,6 +504,7 @@ before this method can be used. } %End + SIP_PYOBJECT attribute( const QString &name ) const; %Docstring Lookup attribute value from attribute name. Field map must be associated using :py:func:`~QgsFeature.setFields` @@ -521,11 +512,7 @@ before this method can be used. :param name: The name of the attribute to get -:return: The value of the attribute (C++: Invalid variant if no such name exists ) - -.. note:: - - For Python: raises a KeyError exception if the field is not found +:raises KeyError: if the field is not found .. note:: @@ -547,6 +534,7 @@ before this method can be used. } %End + SIP_PYOBJECT attribute( int fieldIdx ) const; %Docstring Lookup attribute value from its index. Field map must be associated using :py:func:`~QgsFeature.setFields` @@ -554,11 +542,7 @@ before this method can be used. :param fieldIdx: The index of the attribute to get -:return: The value of the attribute (C++: Invalid variant if no such index exists ) - -.. note:: - - For Python: raises a KeyError exception if the field is not found +:raises KeyError: if the field is not found .. note:: diff --git a/python/core/auto_generated/qgsfield.sip.in b/python/core/auto_generated/qgsfield.sip.in index bcbdfeb5ee1f..7c0d1ffc6df6 100644 --- a/python/core/auto_generated/qgsfield.sip.in +++ b/python/core/auto_generated/qgsfield.sip.in @@ -300,7 +300,7 @@ Converts the provided variant to a compatible format :param v: The value to convert -:return: ``True`` if the conversion was successful +:raises ValueError: if the value could not be converted to a compatible format %End %MethodCode PyObject *sipParseErr = NULL; diff --git a/python/core/auto_generated/qgsfields.sip.in b/python/core/auto_generated/qgsfields.sip.in index 4a462197780e..ee85739789d4 100644 --- a/python/core/auto_generated/qgsfields.sip.in +++ b/python/core/auto_generated/qgsfields.sip.in @@ -75,9 +75,12 @@ Renames a name of field. The field must have unique name, otherwise change is re Appends an expression field. The field must have unique name, otherwise it is rejected (returns ``False``) %End + void remove( int fieldIdx ); %Docstring -Removes a field with the given index +Removes the field with the given index. + +:raises KeyError: if no field with the specified index exists %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) @@ -148,9 +151,12 @@ Returns if a field index is valid sipRes = new QgsField( sipCpp->operator[]( idx ) ); %End + QgsField at( int i ) const /Factory/; %Docstring -Gets field at particular index (must be in range 0..N-1) +Returns the field at particular index (must be in range 0..N-1). + +:raises KeyError: if no field exists at the specified index %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) @@ -164,9 +170,12 @@ Gets field at particular index (must be in range 0..N-1) } %End + QgsField field( int fieldIdx ) const /Factory/; %Docstring -Gets field at particular index (must be in range 0..N-1) +Returns the field at particular index (must be in range 0..N-1). + +:raises KeyError: if no field exists at the specified index %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) @@ -180,9 +189,12 @@ Gets field at particular index (must be in range 0..N-1) } %End + QgsField field( const QString &name ) const /Factory/; %Docstring -Gets field with matching name +Returns the field with matching name. + +:raises KeyError: if no matching field was found. %End %MethodCode int fieldIdx = sipCpp->indexFromName( *a0 ); @@ -197,9 +209,12 @@ Gets field with matching name } %End + FieldOrigin fieldOrigin( int fieldIdx ) const; %Docstring -Gets field's origin (value from an enumeration) +Returns the field's origin (value from an enumeration). + +:raises KeyError: if no field exists at the specified index %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) @@ -213,9 +228,12 @@ Gets field's origin (value from an enumeration) } %End + int fieldOriginIndex( int fieldIdx ) const; %Docstring -Gets field's origin index (its meaning is specific to each type of origin) +Returns the field's origin index (its meaning is specific to each type of origin). + +:raises KeyError: if no field exists at the specified index %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) @@ -291,6 +309,7 @@ Utility function to return a list of :py:class:`QgsField` instances bool operator==( const QgsFields &other ) const; bool operator!=( const QgsFields &other ) const; + QIcon iconForField( int fieldIdx, bool considerOrigin = false ) const /Factory/; %Docstring Returns an icon corresponding to a field index, based on the field's type and source @@ -298,6 +317,8 @@ Returns an icon corresponding to a field index, based on the field's type and so :param fieldIdx: the field index :param considerOrigin: if ``True`` the icon will the origin of the field +:raises KeyError: if no field exists at the specified index + .. versionadded:: 2.14 %End %MethodCode diff --git a/python/core/auto_generated/qgspathresolver.sip.in b/python/core/auto_generated/qgspathresolver.sip.in index a883b6ae071d..419e8578807a 100644 --- a/python/core/auto_generated/qgspathresolver.sip.in +++ b/python/core/auto_generated/qgspathresolver.sip.in @@ -122,7 +122,8 @@ Example - replace stored database credentials with new ones: Removes the custom pre-processor function with matching ``id``. The ``id`` must correspond to a pre-processor previously added via a call to :py:func:`~QgsPathResolver.setPathPreprocessor`. -An KeyError will be raised if no processor with the specified ``id`` exists. + +:raises KeyError: if no processor with the specified ``id`` exists. .. seealso:: :py:func:`setPathPreprocessor` diff --git a/python/core/auto_generated/qgsspatialindex.sip.in b/python/core/auto_generated/qgsspatialindex.sip.in index bc57175a2596..95b9af2a5670 100644 --- a/python/core/auto_generated/qgsspatialindex.sip.in +++ b/python/core/auto_generated/qgsspatialindex.sip.in @@ -195,11 +195,12 @@ number of returned feature IDs may exceed ``neighbors``. SIP_PYOBJECT geometry( QgsFeatureId id ) const /TypeHint="QgsGeometry"/; %Docstring -Returns the stored geometry for the indexed feature with matching ``id``. A KeyError will be raised if no -geometry with the specified feature id exists in the index. +Returns the stored geometry for the indexed feature with matching ``id``. Geometry is only stored if the QgsSpatialIndex was created with the FlagStoreFeatureGeometries flag. +:raises KeyError: if no geometry with the specified feature id exists in the index. + .. versionadded:: 3.6 %End %MethodCode diff --git a/python/core/auto_generated/symbology/qgssymbol.sip.in b/python/core/auto_generated/symbology/qgssymbol.sip.in index 6f559a056dac..7635657519a1 100644 --- a/python/core/auto_generated/symbology/qgssymbol.sip.in +++ b/python/core/auto_generated/symbology/qgssymbol.sip.in @@ -89,7 +89,9 @@ Returns the list of symbol layers contained in the symbol. SIP_PYOBJECT symbolLayer( int layer ) /TypeHint="QgsSymbolLayer"/; %Docstring -Returns the symbol layer at the specified index. An IndexError will be raised if no layer with the specified index exists. +Returns the symbol layer at the specified index. + +:raises IndexError: if no layer with the specified index exists. .. seealso:: :py:func:`symbolLayers` @@ -140,11 +142,13 @@ Returns the number of symbol layers contained in the symbol. SIP_PYOBJECT __getitem__( int index ) /TypeHint="QgsSymbolLayer"/; %Docstring -Returns the symbol layer at the specified ``index``. An IndexError will be raised if no layer with the specified ``index`` exists. +Returns the symbol layer at the specified ``index``. Indexes can be less than 0, in which case they correspond to layers from the end of the symbol. E.g. an index of -1 corresponds to the last layer in the symbol. +:raises IndexError: if no layer with the specified ``index`` exists. + .. versionadded:: 3.10 %End %MethodCode @@ -166,11 +170,13 @@ corresponds to the last layer in the symbol. void __delitem__( int index ); %Docstring -Deletes the layer at the specified ``index``. A layer at the ``index`` must already exist or an IndexError will be raised. +Deletes the layer at the specified ``index``. Indexes can be less than 0, in which case they correspond to layers from the end of the symbol. E.g. an index of -1 corresponds to the last layer in the symbol. +:raises IndexError: if no layer at the specified ``index`` exists + .. versionadded:: 3.10 %End %MethodCode diff --git a/python/core/auto_generated/textrenderer/qgstextblock.sip.in b/python/core/auto_generated/textrenderer/qgstextblock.sip.in index 673bcd10f934..78ef763cee2c 100644 --- a/python/core/auto_generated/textrenderer/qgstextblock.sip.in +++ b/python/core/auto_generated/textrenderer/qgstextblock.sip.in @@ -76,9 +76,12 @@ Applies a ``capitalization`` style to the block's text. sipRes = sipCpp->size(); %End + const QgsTextFragment &at( int index ) const /Factory/; %Docstring Returns the fragment at the specified ``index``. + +:raises KeyError: if no fragment exists at the specified index. %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->size() ) diff --git a/python/core/auto_generated/textrenderer/qgstextdocument.sip.in b/python/core/auto_generated/textrenderer/qgstextdocument.sip.in index f90d35c80ef8..ae57926cd287 100644 --- a/python/core/auto_generated/textrenderer/qgstextdocument.sip.in +++ b/python/core/auto_generated/textrenderer/qgstextdocument.sip.in @@ -62,9 +62,12 @@ Appends a ``block`` to the document. Reserves the specified ``count`` of blocks for optimised block appending. %End + const QgsTextBlock &at( int index ) const /Factory/; %Docstring Returns the block at the specified ``index``. + +:raises KeyError: if no block exists at the specified index. %End %MethodCode if ( a0 < 0 || a0 >= sipCpp->size() ) diff --git a/src/core/geometry/qgscurvepolygon.h b/src/core/geometry/qgscurvepolygon.h index ce0e7e7f85c3..2b7ce32fe175 100644 --- a/src/core/geometry/qgscurvepolygon.h +++ b/src/core/geometry/qgscurvepolygon.h @@ -112,7 +112,7 @@ class CORE_EXPORT QgsCurvePolygon: public QgsSurface /** * Retrieves an interior ring from the curve polygon. The first interior ring has index 0. * - * An IndexError will be raised if no interior ring with the specified index exists. + * \throws IndexError if no interior ring with the specified index exists. * * \see numInteriorRings() * \see exteriorRing() @@ -170,7 +170,7 @@ class CORE_EXPORT QgsCurvePolygon: public QgsSurface * The corresponding ring is removed from the polygon and deleted. * It is not possible to remove the exterior ring using this method. * - * An IndexError will be raised if no interior ring with the specified index exists. + * \throws IndexError if no interior ring with the specified index exists. * * \see removeInteriorRings() */ diff --git a/src/core/geometry/qgsgeometry.h b/src/core/geometry/qgsgeometry.h index 32185adf6d0b..6a0c674034de 100644 --- a/src/core/geometry/qgsgeometry.h +++ b/src/core/geometry/qgsgeometry.h @@ -1712,9 +1712,10 @@ class CORE_EXPORT QgsGeometry * Optionally, a specific random \a seed can be used when generating points. If \a seed * is 0, then a completely random sequence of points will be generated. * - * This method works only with (multi)polygon geometry types. If the geometry - * is not a polygon type, a TypeError will be raised. If the geometry - * is null, a ValueError will be raised. + * This method works only with (multi)polygon geometry types. + * + * \throws TypeError if the geometry is not a polygon type + * \throws ValueError if the geometry is null * * \since QGIS 3.10 */ @@ -1853,9 +1854,10 @@ class CORE_EXPORT QgsGeometry * * Any z or m values present in the geometry will be discarded. * - * This method works only with single-point geometry types. If the geometry - * is not a single-point type, a TypeError will be raised. If the geometry - * is null, a ValueError will be raised. + * This method works only with single-point geometry types. + * + * \throws TypeError if the geometry is not a single-point type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asPoint() const SIP_TYPEHINT( QgsPointXY ); % MethodCode @@ -1896,9 +1898,10 @@ class CORE_EXPORT QgsGeometry * Any z or m values present in the geometry will be discarded. If the geometry is a curved line type * (such as a CircularString), it will be automatically segmentized. * - * This method works only with single-line (or single-curve) geometry types. If the geometry - * is not a single-line type, a TypeError will be raised. If the geometry is null, a ValueError - * will be raised. + * This method works only with single-line (or single-curve). + * + * \throws TypeError if the geometry is not a single-line type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asPolyline() const SIP_TYPEHINT( QgsPolylineXY ); % MethodCode @@ -1940,9 +1943,10 @@ class CORE_EXPORT QgsGeometry * Any z or m values present in the geometry will be discarded. If the geometry is a curved polygon type * (such as a CurvePolygon), it will be automatically segmentized. * - * This method works only with single-polygon (or single-curve polygon) geometry types. If the geometry - * is not a single-polygon type, a TypeError will be raised. If the geometry is null, a ValueError - * will be raised. + * This method works only with single-polygon (or single-curve polygon) geometry types. + * + * \throws TypeError if the geometry is not a single-polygon type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asPolygon() const SIP_TYPEHINT( QgsPolygonXY ); % MethodCode @@ -1982,9 +1986,10 @@ class CORE_EXPORT QgsGeometry * * Any z or m values present in the geometry will be discarded. * - * This method works only with multi-point geometry types. If the geometry - * is not a multi-point type, a TypeError will be raised. If the geometry is null, a ValueError - * will be raised. + * This method works only with multi-point geometry types. + * + * \throws TypeError if the geometry is not a multi-point type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asMultiPoint() const SIP_TYPEHINT( QgsMultiPointXY ); % MethodCode @@ -2026,9 +2031,10 @@ class CORE_EXPORT QgsGeometry * Any z or m values present in the geometry will be discarded. If the geometry is a curved line type * (such as a MultiCurve), it will be automatically segmentized. * - * This method works only with multi-linestring (or multi-curve) geometry types. If the geometry - * is not a multi-linestring type, a TypeError will be raised. If the geometry is null, a ValueError - * will be raised. + * This method works only with multi-linestring (or multi-curve) geometry types. + * + * \throws TypeError if the geometry is not a multi-linestring type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asMultiPolyline() const SIP_TYPEHINT( QgsMultiPolylineXY ); % MethodCode @@ -2070,9 +2076,10 @@ class CORE_EXPORT QgsGeometry * Any z or m values present in the geometry will be discarded. If the geometry is a curved polygon type * (such as a MultiSurface), it will be automatically segmentized. * - * This method works only with multi-polygon (or multi-curve polygon) geometry types. If the geometry - * is not a multi-polygon type, a TypeError will be raised. If the geometry is null, a ValueError - * will be raised. + * This method works only with multi-polygon (or multi-curve polygon) geometry types. + * + * \throws TypeError if the geometry is not a multi-polygon type + * \throws ValueError if the geometry is null */ SIP_PYOBJECT asMultiPolygon() const SIP_TYPEHINT( QgsMultiPolygonXY ); % MethodCode diff --git a/src/core/geometry/qgsgeometrycollection.h b/src/core/geometry/qgsgeometrycollection.h index 97428dfafc21..b5de35971510 100644 --- a/src/core/geometry/qgsgeometrycollection.h +++ b/src/core/geometry/qgsgeometrycollection.h @@ -98,7 +98,8 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry /** * Returns a geometry from within the collection. - * \param n index of geometry to return. An IndexError will be raised if no geometry with the specified index exists. + * \param n index of geometry to return. + * \throws IndexError if no geometry with the specified index exists. */ SIP_PYOBJECT geometryN( int n ) SIP_TYPEHINT( QgsAbstractGeometry ); % MethodCode @@ -160,9 +161,8 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry /** * Removes a geometry from the collection by index. * - * An IndexError will be raised if no geometry with the specified index exists. - * * \returns TRUE if removal was successful. + * \throws IndexError if no geometry with the specified index exists. */ virtual bool removeGeometry( int nr ); % MethodCode @@ -264,11 +264,13 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry #ifdef SIP_RUN /** - * Returns the geometry at the specified ``index``. An IndexError will be raised if no geometry with the specified ``index`` exists. + * Returns the geometry at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to geometries from the end of the collect. E.g. an index of -1 * corresponds to the last geometry in the collection. * + * \throws IndexError if no geometry with the specified ``index`` exists. + * * \since QGIS 3.6 */ SIP_PYOBJECT __getitem__( int index ) SIP_TYPEHINT( QgsAbstractGeometry ); @@ -290,11 +292,13 @@ class CORE_EXPORT QgsGeometryCollection: public QgsAbstractGeometry % End /** - * Deletes the geometry at the specified ``index``. A geometry at the ``index`` must already exist or an IndexError will be raised. + * Deletes the geometry at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to geometries from the end of the collection. E.g. an index of -1 * corresponds to the last geometry in the collection. * + * \throws IndexError if no geometry at the ``index`` exists + * * \since QGIS 3.6 */ void __delitem__( int index ); diff --git a/src/core/geometry/qgslinestring.h b/src/core/geometry/qgslinestring.h index f6219c446b37..54772c8103ff 100644 --- a/src/core/geometry/qgslinestring.h +++ b/src/core/geometry/qgslinestring.h @@ -316,10 +316,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve #else /** - * Returns the point at the specified index. An IndexError will be raised if no point with the specified index exists. + * Returns the point at the specified index. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. + * + * \throws IndexError if no point with the specified index exists. */ SIP_PYOBJECT pointN( int i ) const SIP_TYPEHINT( QgsPoint ); % MethodCode @@ -348,10 +350,10 @@ class CORE_EXPORT QgsLineString: public QgsCurve /** * Returns the x-coordinate of the specified node in the line string. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. + * + * \throws IndexError if no point with the specified index exists. */ double xAt( int index ) const override; % MethodCode @@ -378,10 +380,10 @@ class CORE_EXPORT QgsLineString: public QgsCurve /** * Returns the y-coordinate of the specified node in the line string. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. + * + * \throws IndexError if no point with the specified index exists. */ double yAt( int index ) const override; % MethodCode @@ -476,12 +478,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve /** * Returns the z-coordinate of the specified node in the line string. * - * An IndexError will be raised if no point with the specified index exists. - * * If the LineString does not have a z-dimension then ``nan`` will be returned. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. + * + * \throws IndexError if no point with the specified index exists. */ double zAt( int index ) const; % MethodCode @@ -522,12 +524,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve /** * Returns the m-coordinate of the specified node in the line string. * - * An IndexError will be raised if no point with the specified index exists. - * * If the LineString does not have a m-dimension then ``nan`` will be returned. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. + * + * \throws IndexError if no point with the specified index exists. */ double mAt( int index ) const; % MethodCode @@ -563,11 +565,11 @@ class CORE_EXPORT QgsLineString: public QgsCurve * Sets the x-coordinate of the specified node in the line string. * The corresponding node must already exist in line string. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified index exists. + * * \see xAt() */ void setXAt( int index, double x ); @@ -604,11 +606,11 @@ class CORE_EXPORT QgsLineString: public QgsCurve * Sets the y-coordinate of the specified node in the line string. * The corresponding node must already exist in line string. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified index exists. + * * \see yAt() */ void setYAt( int index, double y ); @@ -649,11 +651,10 @@ class CORE_EXPORT QgsLineString: public QgsCurve * Sets the z-coordinate of the specified node in the line string. * The corresponding node must already exist in line string and the line string must have z-dimension. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified index exists. * \see zAt() */ void setZAt( int index, double z ); @@ -694,11 +695,10 @@ class CORE_EXPORT QgsLineString: public QgsCurve * Sets the m-coordinate of the specified node in the line string. * The corresponding node must already exist in line string and the line string must have m-dimension. * - * An IndexError will be raised if no point with the specified index exists. - * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified index exists. * \see mAt() */ void setMAt( int index, double m ); @@ -901,11 +901,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve % End /** - * Returns the point at the specified ``index``. An IndexError will be raised if no point with the specified ``index`` exists. + * Returns the point at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified ``index`` exists. * \since QGIS 3.6 */ SIP_PYOBJECT __getitem__( int index ) SIP_TYPEHINT( QgsPoint ); @@ -928,11 +929,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve % End /** - * Sets the point at the specified ``index``. A point at the ``index`` must already exist or an IndexError will be raised. + * Sets the point at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified ``index`` exists. * \since QGIS 3.6 */ void __setitem__( int index, const QgsPoint &point ); @@ -958,11 +960,12 @@ class CORE_EXPORT QgsLineString: public QgsCurve /** - * Deletes the vertex at the specified ``index``. A point at the ``index`` must already exist or an IndexError will be raised. + * Deletes the vertex at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to positions from the end of the line. E.g. an index of -1 * corresponds to the last point in the line. * + * \throws IndexError if no point with the specified ``index`` exists. * \since QGIS 3.6 */ void __delitem__( int index ); diff --git a/src/core/geometry/qgsmulticurve.h b/src/core/geometry/qgsmulticurve.h index 32cad522b349..f85c3cf902d9 100644 --- a/src/core/geometry/qgsmulticurve.h +++ b/src/core/geometry/qgsmulticurve.h @@ -45,7 +45,7 @@ class CORE_EXPORT QgsMultiCurve: public QgsGeometryCollection /** * Returns the curve with the specified \a index. * - * An IndexError will be raised if no curve with the specified index exists. + * \throws IndexError if no curve with the specified index exists. * * \since QGIS 3.16 */ diff --git a/src/core/geometry/qgsmultilinestring.h b/src/core/geometry/qgsmultilinestring.h index 4991cad8a600..10167b5288b0 100644 --- a/src/core/geometry/qgsmultilinestring.h +++ b/src/core/geometry/qgsmultilinestring.h @@ -51,7 +51,7 @@ class CORE_EXPORT QgsMultiLineString: public QgsMultiCurve /** * Returns the line string with the specified \a index. * - * An IndexError will be raised if no line string with the specified index exists. + * \throws IndexError if no line string with the specified index exists. * * \since QGIS 3.16 */ diff --git a/src/core/geometry/qgsmultipoint.h b/src/core/geometry/qgsmultipoint.h index d18152e005e4..da3abde26ced 100644 --- a/src/core/geometry/qgsmultipoint.h +++ b/src/core/geometry/qgsmultipoint.h @@ -48,7 +48,7 @@ class CORE_EXPORT QgsMultiPoint: public QgsGeometryCollection /** * Returns the point with the specified \a index. * - * An IndexError will be raised if no point with the specified index exists. + * \throws IndexError if no point with the specified index exists. * * \since QGIS 3.16 */ diff --git a/src/core/geometry/qgsmultipolygon.h b/src/core/geometry/qgsmultipolygon.h index 1d0c344be53e..38a9689974dd 100644 --- a/src/core/geometry/qgsmultipolygon.h +++ b/src/core/geometry/qgsmultipolygon.h @@ -51,7 +51,7 @@ class CORE_EXPORT QgsMultiPolygon: public QgsMultiSurface /** * Returns the polygon with the specified \a index. * - * An IndexError will be raised if no polygon with the specified index exists. + * \throws IndexError if no polygon with the specified index exists. * * \since QGIS 3.16 */ diff --git a/src/core/geometry/qgsmultisurface.h b/src/core/geometry/qgsmultisurface.h index 84fe05683a26..8fab2bd83ced 100644 --- a/src/core/geometry/qgsmultisurface.h +++ b/src/core/geometry/qgsmultisurface.h @@ -51,7 +51,7 @@ class CORE_EXPORT QgsMultiSurface: public QgsGeometryCollection /** * Returns the surface with the specified \a index. * - * An IndexError will be raised if no surface with the specified index exists. + * \throws IndexError if no surface with the specified index exists. * * \since QGIS 3.16 */ diff --git a/src/core/qgsfeature.h b/src/core/qgsfeature.h index 637f205c2a29..0e6b9314daeb 100644 --- a/src/core/qgsfeature.h +++ b/src/core/qgsfeature.h @@ -256,19 +256,28 @@ class CORE_EXPORT QgsFeature */ void setAttributes( const QgsAttributes &attrs ); +#ifndef SIP_RUN + /** * Set an attribute's value by field index. * The feature will be valid if it was successful. * \param field the index of the field to set * \param attr the value of the attribute * \returns FALSE, if the field index does not exist - * \note For Python: raises a KeyError exception instead of returning FALSE - * \note Alternatively in Python: @code feature[field] = attr @endcode * \see setAttributes */ -#ifndef SIP_RUN bool setAttribute( int field, const QVariant &attr ); #else + + /** + * Set an attribute's value by field index. + * The feature will be valid if it was successful. + * \param field the index of the field to set + * \param attr the value of the attribute + * \throws KeyError if the field index does not exist + * \note Alternatively in Python: @code feature[field] = attr @endcode + * \see setAttributes + */ bool setAttribute( int field, const QVariant &attr / GetWrapper / ); % MethodCode bool rv; @@ -323,15 +332,24 @@ class CORE_EXPORT QgsFeature */ void padAttributes( int count ); +#ifndef SIP_RUN + /** * Deletes an attribute and its value. * \param field the index of the field * \see setAttribute - * \note For Python: raises a KeyError exception if the field is not found + */ + void deleteAttribute( int field ); +#else + + /** + * Deletes an attribute and its value. + * \param field the index of the field + * \see setAttribute + * \throws KeyError if the field is not found * \note Alternatively in Python: @code del feature[field] @endcode */ void deleteAttribute( int field ); -#ifdef SIP_RUN % MethodCode if ( a0 >= 0 && a0 < sipCpp->attributes().count() ) sipCpp->deleteAttribute( a0 ); @@ -442,6 +460,8 @@ class CORE_EXPORT QgsFeature */ QgsFields fields() const; +#ifndef SIP_RUN + /** * Insert a value into attribute. Returns FALSE if attribute name could not be converted to index. * Field map must be associated using setFields() before this method can be used. @@ -449,13 +469,21 @@ class CORE_EXPORT QgsFeature * \param name The name of the field to set * \param value The value to set * \returns FALSE if attribute name could not be converted to index (C++ only) - * \note For Python: raises a KeyError exception instead of returning FALSE - * \note Alternatively in Python: @code feature[name] = attr @endcode * \see setFields */ -#ifndef SIP_RUN bool setAttribute( const QString &name, const QVariant &value ); #else + + /** + * Insert a value into attribute. Returns FALSE if attribute name could not be converted to index. + * Field map must be associated using setFields() before this method can be used. + * The feature will be valid if it was successful + * \param name The name of the field to set + * \param value The value to set + * \throws KeyError if the attribute name could not be converted to an index + * \note Alternatively in Python: @code feature[name] = attr @endcode + * \see setFields + */ void setAttribute( const QString &name, const QVariant &value / GetWrapper / ); % MethodCode int fieldIdx = sipCpp->fieldNameIndex( *a0 ); @@ -478,17 +506,27 @@ class CORE_EXPORT QgsFeature % End #endif +#ifndef SIP_RUN + /** * Removes an attribute value by field name. Field map must be associated using setFields() * before this method can be used. * \param name The name of the field to delete * \returns FALSE if attribute name could not be converted to index (C++ only) - * \note For Python: raises a KeyError exception instead of returning FALSE + * \see setFields + */ + bool deleteAttribute( const QString &name ); +#else + + /** + * Removes an attribute value by field name. Field map must be associated using setFields() + * before this method can be used. + * \param name The name of the field to delete + * \throws KeyError if attribute name could not be converted to index * \note Alternatively in Python: @code del feature[name] @endcode * \see setFields */ bool deleteAttribute( const QString &name ); -#ifdef SIP_RUN % MethodCode int fieldIdx = sipCpp->fieldNameIndex( *a0 ); if ( fieldIdx == -1 ) @@ -505,18 +543,26 @@ class CORE_EXPORT QgsFeature % End #endif +#ifndef SIP_RUN + /** * Lookup attribute value from attribute name. Field map must be associated using setFields() * before this method can be used. * \param name The name of the attribute to get * \returns The value of the attribute (C++: Invalid variant if no such name exists ) - * \note For Python: raises a KeyError exception if the field is not found - * \note Alternatively in Python: @code feature[name] @endcode * \see setFields */ -#ifndef SIP_RUN QVariant attribute( const QString &name ) const; #else + + /** + * Lookup attribute value from attribute name. Field map must be associated using setFields() + * before this method can be used. + * \param name The name of the attribute to get + * \throws KeyError if the field is not found + * \note Alternatively in Python: @code feature[name] @endcode + * \see setFields + */ SIP_PYOBJECT attribute( const QString &name ) const; % MethodCode int fieldIdx = sipCpp->fieldNameIndex( *a0 ); @@ -533,18 +579,26 @@ class CORE_EXPORT QgsFeature % End #endif +#ifndef SIP_RUN + /** * Lookup attribute value from its index. Field map must be associated using setFields() * before this method can be used. * \param fieldIdx The index of the attribute to get * \returns The value of the attribute (C++: Invalid variant if no such index exists ) - * \note For Python: raises a KeyError exception if the field is not found - * \note Alternatively in Python: @code feature[fieldIdx] @endcode * \see setFields */ -#ifndef SIP_RUN QVariant attribute( int fieldIdx ) const; #else + + /** + * Lookup attribute value from its index. Field map must be associated using setFields() + * before this method can be used. + * \param fieldIdx The index of the attribute to get + * \throws KeyError if the field is not found + * \note Alternatively in Python: @code feature[fieldIdx] @endcode + * \see setFields + */ SIP_PYOBJECT attribute( int fieldIdx ) const; % MethodCode { diff --git a/src/core/qgsfield.h b/src/core/qgsfield.h index 6a2cb1dd2e97..c779b1c22089 100644 --- a/src/core/qgsfield.h +++ b/src/core/qgsfield.h @@ -346,7 +346,7 @@ class CORE_EXPORT QgsField * * \param v The value to convert * - * \returns TRUE if the conversion was successful + * \throws ValueError if the value could not be converted to a compatible format */ bool convertCompatible( QVariant &v ) const; % MethodCode diff --git a/src/core/qgsfields.h b/src/core/qgsfields.h index d61050cab824..997703dadcf2 100644 --- a/src/core/qgsfields.h +++ b/src/core/qgsfields.h @@ -111,9 +111,20 @@ class CORE_EXPORT QgsFields //! Appends an expression field. The field must have unique name, otherwise it is rejected (returns FALSE) bool appendExpressionField( const QgsField &field, int originIndex ); - //! Removes a field with the given index +#ifndef SIP_RUN + + /** + * Removes the field with the given index. + */ + void remove( int fieldIdx ); +#else + + /** + * Removes the field with the given index. + * + * \throws KeyError if no field with the specified index exists + */ void remove( int fieldIdx ); -#ifdef SIP_RUN % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { @@ -182,9 +193,16 @@ class CORE_EXPORT QgsFields % End #endif - //! Gets field at particular index (must be in range 0..N-1) +#ifndef SIP_RUN + //! Returns the field at particular index (must be in range 0..N-1) + QgsField at( int i ) const SIP_FACTORY; +#else + + /** + * Returns the field at particular index (must be in range 0..N-1). + * \throws KeyError if no field exists at the specified index + */ QgsField at( int i ) const SIP_FACTORY; -#ifdef SIP_RUN % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { @@ -198,9 +216,16 @@ class CORE_EXPORT QgsFields % End #endif +#ifndef SIP_RUN //! Gets field at particular index (must be in range 0..N-1) QgsField field( int fieldIdx ) const SIP_FACTORY; -#ifdef SIP_RUN +#else + + /** + * Returns the field at particular index (must be in range 0..N-1). + * \throws KeyError if no field exists at the specified index + */ + QgsField field( int fieldIdx ) const SIP_FACTORY; % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { @@ -214,9 +239,16 @@ class CORE_EXPORT QgsFields % End #endif +#ifndef SIP_RUN //! Gets field with matching name QgsField field( const QString &name ) const SIP_FACTORY; -#ifdef SIP_RUN +#else + + /** + * Returns the field with matching name. + * \throws KeyError if no matching field was found. + */ + QgsField field( const QString &name ) const SIP_FACTORY; % MethodCode int fieldIdx = sipCpp->indexFromName( *a0 ); if ( fieldIdx == -1 ) @@ -231,9 +263,17 @@ class CORE_EXPORT QgsFields % End #endif +#ifndef SIP_RUN //! Gets field's origin (value from an enumeration) FieldOrigin fieldOrigin( int fieldIdx ) const; -#ifdef SIP_RUN +#else + + /** + * Returns the field's origin (value from an enumeration). + * + * \throws KeyError if no field exists at the specified index + */ + FieldOrigin fieldOrigin( int fieldIdx ) const; % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { @@ -247,9 +287,17 @@ class CORE_EXPORT QgsFields % End #endif +#ifndef SIP_RUN //! Gets field's origin index (its meaning is specific to each type of origin) int fieldOriginIndex( int fieldIdx ) const; -#ifdef SIP_RUN +#else + + /** + * Returns the field's origin index (its meaning is specific to each type of origin). + * + * \throws KeyError if no field exists at the specified index + */ + int fieldOriginIndex( int fieldIdx ) const; % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { @@ -319,6 +367,8 @@ class CORE_EXPORT QgsFields //! \since QGIS 2.6 bool operator!=( const QgsFields &other ) const { return !( *this == other ); } +#ifndef SIP_RUN + /** * Returns an icon corresponding to a field index, based on the field's type and source * \param fieldIdx the field index @@ -326,7 +376,16 @@ class CORE_EXPORT QgsFields * \since QGIS 2.14 */ QIcon iconForField( int fieldIdx, bool considerOrigin = false ) const SIP_FACTORY; -#ifdef SIP_RUN +#else + + /** + * Returns an icon corresponding to a field index, based on the field's type and source + * \param fieldIdx the field index + * \param considerOrigin if TRUE the icon will the origin of the field + * \throws KeyError if no field exists at the specified index + * \since QGIS 2.14 + */ + QIcon iconForField( int fieldIdx, bool considerOrigin = false ) const SIP_FACTORY; % MethodCode if ( a0 < 0 || a0 >= sipCpp->count() ) { diff --git a/src/core/qgspathresolver.h b/src/core/qgspathresolver.h index 4346a45f57fe..fa464e1c99d1 100644 --- a/src/core/qgspathresolver.h +++ b/src/core/qgspathresolver.h @@ -156,7 +156,8 @@ class CORE_EXPORT QgsPathResolver * Removes the custom pre-processor function with matching \a id. * * The \a id must correspond to a pre-processor previously added via a call to setPathPreprocessor(). - * An KeyError will be raised if no processor with the specified \a id exists. + * + * \throws KeyError if no processor with the specified \a id exists. * * \see setPathPreprocessor() * \since QGIS 3.10 diff --git a/src/core/qgsspatialindex.h b/src/core/qgsspatialindex.h index 382b0eb43b8d..65daeb52b033 100644 --- a/src/core/qgsspatialindex.h +++ b/src/core/qgsspatialindex.h @@ -243,11 +243,12 @@ class CORE_EXPORT QgsSpatialIndex : public QgsFeatureSink #else /** - * Returns the stored geometry for the indexed feature with matching \a id. A KeyError will be raised if no - * geometry with the specified feature id exists in the index. + * Returns the stored geometry for the indexed feature with matching \a id. * * Geometry is only stored if the QgsSpatialIndex was created with the FlagStoreFeatureGeometries flag. * + * \throws KeyError if no geometry with the specified feature id exists in the index. + * * \since QGIS 3.6 */ SIP_PYOBJECT geometry( QgsFeatureId id ) const SIP_TYPEHINT( QgsGeometry ); diff --git a/src/core/symbology/qgssymbol.h b/src/core/symbology/qgssymbol.h index e9e1148f050e..5c0921db5079 100644 --- a/src/core/symbology/qgssymbol.h +++ b/src/core/symbology/qgssymbol.h @@ -127,7 +127,9 @@ class CORE_EXPORT QgsSymbol #else /** - * Returns the symbol layer at the specified index. An IndexError will be raised if no layer with the specified index exists. + * Returns the symbol layer at the specified index. + * + * \throws IndexError if no layer with the specified index exists. * * \see symbolLayers * \see symbolLayerCount @@ -174,11 +176,13 @@ class CORE_EXPORT QgsSymbol % End /** - * Returns the symbol layer at the specified ``index``. An IndexError will be raised if no layer with the specified ``index`` exists. + * Returns the symbol layer at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to layers from the end of the symbol. E.g. an index of -1 * corresponds to the last layer in the symbol. * + * \throws IndexError if no layer with the specified ``index`` exists. + * * \since QGIS 3.10 */ SIP_PYOBJECT __getitem__( int index ) SIP_TYPEHINT( QgsSymbolLayer ); @@ -200,11 +204,13 @@ class CORE_EXPORT QgsSymbol % End /** - * Deletes the layer at the specified ``index``. A layer at the ``index`` must already exist or an IndexError will be raised. + * Deletes the layer at the specified ``index``. * * Indexes can be less than 0, in which case they correspond to layers from the end of the symbol. E.g. an index of -1 * corresponds to the last layer in the symbol. * + * \throws IndexError if no layer at the specified ``index`` exists + * * \since QGIS 3.10 */ void __delitem__( int index ); diff --git a/src/core/textrenderer/qgstextblock.h b/src/core/textrenderer/qgstextblock.h index bb48249b4f71..ee7f19f7123a 100644 --- a/src/core/textrenderer/qgstextblock.h +++ b/src/core/textrenderer/qgstextblock.h @@ -93,11 +93,20 @@ class CORE_EXPORT QgsTextBlock % End #endif +#ifndef SIP_RUN + /** * Returns the fragment at the specified \a index. */ const QgsTextFragment &at( int index ) const SIP_FACTORY; -#ifdef SIP_RUN +#else + + /** + * Returns the fragment at the specified \a index. + * + * \throws KeyError if no fragment exists at the specified index. + */ + const QgsTextFragment &at( int index ) const SIP_FACTORY; % MethodCode if ( a0 < 0 || a0 >= sipCpp->size() ) { diff --git a/src/core/textrenderer/qgstextdocument.h b/src/core/textrenderer/qgstextdocument.h index d7c7d65ffa1b..5b383bcd1902 100644 --- a/src/core/textrenderer/qgstextdocument.h +++ b/src/core/textrenderer/qgstextdocument.h @@ -78,11 +78,20 @@ class CORE_EXPORT QgsTextDocument */ void reserve( int count ); +#ifndef SIP_RUN + /** * Returns the block at the specified \a index. */ const QgsTextBlock &at( int index ) const SIP_FACTORY; -#ifdef SIP_RUN +#else + + /** + * Returns the block at the specified \a index. + * + * \throws KeyError if no block exists at the specified index. + */ + const QgsTextBlock &at( int index ) const SIP_FACTORY; % MethodCode if ( a0 < 0 || a0 >= sipCpp->size() ) {