Skip to content

Commit 3c3059c

Browse files
nyalldawsonnyalldawson
committedJun 25, 2021
Fix code example blocks in QgsFeature documentation
·
ltr-3_40final-3_22_0
1 parent 711a615 commit 3c3059c

File tree

2 files changed

+221
-49
lines changed

2 files changed

+221
-49
lines changed
 

‎python/core/auto_generated/qgsfeature.sip.in

Lines changed: 107 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -180,11 +180,17 @@ Sets the feature ``id`` for this feature.
180180
%Docstring
181181
Returns the feature's attributes.
182182

183-
.. seealso:: :py:func:`setAttributes`
183+
Alternatively, in Python it is possible to directly iterate over a feature in order to retrieve
184+
its attributes:
184185

185-
.. note::
186+
.. code-block:: python
187+
188+
feature = QgsFeature()
189+
feature.setAttributes([11, 'string value', 55.5])
190+
for attr in feature:
191+
print(attr)
186192

187-
Alternatively in Python: iterate feature, eg. @code [attr for attr in feature] @endcode
193+
.. seealso:: :py:func:`setAttributes`
188194

189195
.. versionadded:: 2.9
190196
%End
@@ -225,15 +231,25 @@ Sets an attribute's value by field index.
225231

226232
If the attribute was successfully set then the feature will be automatically marked as valid (see :py:func:`~QgsFeature.isValid`).
227233

234+
Alternatively, in Python it is possible to directly set a field's value via the field's index:
235+
236+
.. code-block:: python
237+
238+
fields = QgsFields()
239+
fields.append(QgsField('my_id', QVariant.Int))
240+
fields.append(QgsField('name', QVariant.String))
241+
feature = QgsFeature(fields)
242+
243+
# set the "name" field value
244+
feature[1] = "my name"
245+
# set the "my_id" field value
246+
feature[0] = 55
247+
228248
:param field: the index of the field to set
229249
:param attr: the value of the attribute
230250

231251
:raises KeyError: if the field index does not exist
232252

233-
.. note::
234-
235-
Alternatively in Python: @code feature[field] = attr @endcode
236-
237253
.. seealso:: :py:func:`setAttributes`
238254
%End
239255
%MethodCode
@@ -297,15 +313,29 @@ Resizes the attributes attached to this feature by appending the specified ``cou
297313

298314
void deleteAttribute( int field );
299315
%Docstring
300-
Deletes an attribute and its value.
316+
Clear's an attribute's value by its index.
301317

302318
:param field: the index of the field
303319

304-
:raises KeyError: if the field is not found
320+
Alternatively, in Python it is possible to directly `del` an attribute via its index:
305321

306-
.. note::
322+
.. code-block:: python
323+
324+
feature = QgsFeature()
325+
feature.setAttributes([11, 'my feature', 55.5])
326+
327+
# will print [11, 'my feature', 55.5]
328+
print(feature.attributes())
329+
330+
# clear the second attribute
331+
del feature[1]
307332

308-
Alternatively in Python: @code del feature[field] @endcode
333+
# will now print [11, NONE]
334+
print(feature.attributes())
335+
336+
337+
338+
:raises KeyError: if the field is not found
309339

310340
.. seealso:: :py:func:`setAttribute`
311341
%End
@@ -452,15 +482,25 @@ Field map must be associated using :py:func:`~QgsFeature.setFields` before this
452482

453483
Calling this method will automatically set the feature as valid (see :py:func:`~QgsFeature.isValid`).
454484

485+
Alternatively, in Python it is possible to directly set a field's value via the field's name:
486+
487+
.. code-block:: python
488+
489+
fields = QgsFields()
490+
fields.append(QgsField('my_id', QVariant.Int))
491+
fields.append(QgsField('name', QVariant.String))
492+
feature = QgsFeature(fields)
493+
494+
# set the "name" field value
495+
feature['name'] = "my name"
496+
# set the "my_id" field value
497+
feature['my_id'] = 55
498+
455499
:param name: The name of the field to set
456500
:param value: The value to set
457501

458502
:raises KeyError: if the attribute name could not be converted to an index
459503

460-
.. note::
461-
462-
Alternatively in Python: @code feature[name] = attr @endcode
463-
464504
.. seealso:: :py:func:`setFields`
465505
%End
466506
%MethodCode
@@ -486,17 +526,33 @@ Calling this method will automatically set the feature as valid (see :py:func:`~
486526

487527
bool deleteAttribute( const QString &name );
488528
%Docstring
489-
Removes an attribute value by field ``name``.
529+
Clear's an attribute's value by its field ``name``.
490530

491-
Field map must be associated using setFields()before this method can be used.
531+
Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
492532

493-
:param name: The name of the field to delete
533+
Alternatively, in Python it is possible to directly `del` an attribute via its name:
494534

495-
:raises KeyError: if attribute name could not be converted to index
535+
.. code-block:: python
496536

497-
.. note::
537+
fields = QgsFields()
538+
fields.append(QgsField('my_id', QVariant.Int))
539+
fields.append(QgsField('name', QVariant.String))
540+
541+
feature = QgsFeature(fields)
542+
feature.setAttributes([11, 'my feature'])
543+
544+
# will print [11, 'my feature']
545+
print(feature.attributes())
546+
547+
# clear the 'name' attribute
548+
del feature['name']
498549

499-
Alternatively in Python: @code del feature[name] @endcode
550+
# will now print [11, NULL]
551+
print(feature.attributes())
552+
553+
:param name: The name of the field to clear
554+
555+
:raises KeyError: if attribute name could not be converted to index
500556

501557
.. seealso:: :py:func:`setFields`
502558
%End
@@ -522,16 +578,27 @@ Lookup attribute value by attribute ``name``.
522578

523579
Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
524580

581+
Alternatively, in Python it is possible to directly retrieve a field's value via the field's name:
582+
583+
.. code-block:: python
584+
585+
fields = QgsFields()
586+
fields.append(QgsField('my_id', QVariant.Int))
587+
fields.append(QgsField('name', QVariant.String))
588+
feature = QgsFeature(fields)
589+
feature.setAttributes([11, 'my feature'])
590+
591+
# print the "name" field value
592+
print(feature['name'])
593+
# print the "my_id" field value
594+
print(feature['my_id'])
595+
525596
:param name: The name of the attribute to get
526597

527598
:return: The value of the attribute
528599

529600
:raises KeyError: if the field is not found
530601

531-
.. note::
532-
533-
Alternatively in Python: @code feature[name] @endcode
534-
535602
.. seealso:: :py:func:`setFields`
536603
%End
537604
%MethodCode
@@ -553,18 +620,28 @@ Field map must be associated using :py:func:`~QgsFeature.setFields` before this
553620
%Docstring
554621
Lookup attribute value from its index.
555622

556-
Field map must be associated using :py:func:`~QgsFeature.setFields` before this method can be used.
623+
Alternatively, in Python it is possible to directly retrieve a field's value via its index:
624+
625+
.. code-block:: python
626+
627+
feature = QgsFeature()
628+
feature.setAttributes([11, 'my feature', 55.5])
629+
630+
# will print 11
631+
print(feature[0])
632+
633+
# will print 'my feature'
634+
print(feature[1])
635+
636+
# will print 55.5
637+
print(feature[2])
557638

558639
:param fieldIdx: The index of the attribute to get
559640

560641
:return: The value of the attribute
561642

562643
:raises KeyError: if the field is not found
563644

564-
.. note::
565-
566-
Alternatively in Python: @code feature[fieldIdx] @endcode
567-
568645
.. seealso:: :py:func:`setFields`
569646
%End
570647
%MethodCode

‎src/core/qgsfeature.h

Lines changed: 114 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -229,8 +229,18 @@ class CORE_EXPORT QgsFeature
229229

230230
/**
231231
* Returns the feature's attributes.
232-
* \see setAttributes
233-
* \note Alternatively in Python: iterate feature, eg. @code [attr for attr in feature] @endcode
232+
*
233+
* Alternatively, in Python it is possible to directly iterate over a feature in order to retrieve
234+
* its attributes:
235+
*
236+
* \code{.py}
237+
* feature = QgsFeature()
238+
* feature.setAttributes([11, 'string value', 55.5])
239+
* for attr in feature:
240+
* print(attr)
241+
* \endcode
242+
*
243+
* \see setAttributes()
234244
* \since QGIS 2.9
235245
*/
236246
QgsAttributes attributes() const;
@@ -279,10 +289,23 @@ class CORE_EXPORT QgsFeature
279289
*
280290
* If the attribute was successfully set then the feature will be automatically marked as valid (see isValid()).
281291
*
292+
* Alternatively, in Python it is possible to directly set a field's value via the field's index:
293+
*
294+
* \code{.py}
295+
* fields = QgsFields()
296+
* fields.append(QgsField('my_id', QVariant.Int))
297+
* fields.append(QgsField('name', QVariant.String))
298+
* feature = QgsFeature(fields)
299+
*
300+
* # set the "name" field value
301+
* feature[1] = "my name"
302+
* # set the "my_id" field value
303+
* feature[0] = 55
304+
* \endcode
305+
*
282306
* \param field the index of the field to set
283307
* \param attr the value of the attribute
284308
* \throws KeyError if the field index does not exist
285-
* \note Alternatively in Python: @code feature[field] = attr @endcode
286309
* \see setAttributes()
287310
*/
288311
bool setAttribute( int field, const QVariant &attr / GetWrapper / );
@@ -345,7 +368,7 @@ class CORE_EXPORT QgsFeature
345368
#ifndef SIP_RUN
346369

347370
/**
348-
* Deletes an attribute and its value.
371+
* Clear's an attribute's value by its index.
349372
*
350373
* \param field the index of the field
351374
*
@@ -355,12 +378,27 @@ class CORE_EXPORT QgsFeature
355378
#else
356379

357380
/**
358-
* Deletes an attribute and its value.
381+
* Clear's an attribute's value by its index.
359382
*
360383
* \param field the index of the field
361384
*
385+
* Alternatively, in Python it is possible to directly `del` an attribute via its index:
386+
*
387+
* \code{.py}
388+
* feature = QgsFeature()
389+
* feature.setAttributes([11, 'my feature', 55.5])
390+
*
391+
* # will print [11, 'my feature', 55.5]
392+
* print(feature.attributes())
393+
*
394+
* # clear the second attribute
395+
* del feature[1]
396+
*
397+
* # will now print [11, NONE]
398+
* print(feature.attributes())
399+
* \endcode
400+
*
362401
* \throws KeyError if the field is not found
363-
* \note Alternatively in Python: @code del feature[field] @endcode
364402
* \see setAttribute()
365403
*/
366404
void deleteAttribute( int field );
@@ -510,10 +548,23 @@ class CORE_EXPORT QgsFeature
510548
*
511549
* Calling this method will automatically set the feature as valid (see isValid()).
512550
*
551+
* Alternatively, in Python it is possible to directly set a field's value via the field's name:
552+
*
553+
* \code{.py}
554+
* fields = QgsFields()
555+
* fields.append(QgsField('my_id', QVariant.Int))
556+
* fields.append(QgsField('name', QVariant.String))
557+
* feature = QgsFeature(fields)
558+
*
559+
* # set the "name" field value
560+
* feature['name'] = "my name"
561+
* # set the "my_id" field value
562+
* feature['my_id'] = 55
563+
* \endcode
564+
*
513565
* \param name The name of the field to set
514566
* \param value The value to set
515567
* \throws KeyError if the attribute name could not be converted to an index
516-
* \note Alternatively in Python: @code feature[name] = attr @endcode
517568
* \see setFields()
518569
*/
519570
void setAttribute( const QString &name, const QVariant &value / GetWrapper / );
@@ -541,25 +592,44 @@ class CORE_EXPORT QgsFeature
541592
#ifndef SIP_RUN
542593

543594
/**
544-
* Removes an attribute value by field \a name.
595+
* Clear's an attribute's value by its field \a name.
545596
*
546-
* Field map must be associated using setFields()before this method can be used.
597+
* Field map must be associated using setFields() before this method can be used.
547598
*
548-
* \param name The name of the field to delete
599+
* \param name The name of the field to clear
549600
* \returns FALSE if attribute name could not be converted to index
550601
* \see setFields()
551602
*/
552603
bool deleteAttribute( const QString &name );
553604
#else
554605

555606
/**
556-
* Removes an attribute value by field \a name.
607+
* Clear's an attribute's value by its field \a name.
557608
*
558-
* Field map must be associated using setFields()before this method can be used.
609+
* Field map must be associated using setFields() before this method can be used.
610+
*
611+
* Alternatively, in Python it is possible to directly `del` an attribute via its name:
612+
*
613+
* \code{.py}
614+
* fields = QgsFields()
615+
* fields.append(QgsField('my_id', QVariant.Int))
616+
* fields.append(QgsField('name', QVariant.String))
617+
*
618+
* feature = QgsFeature(fields)
619+
* feature.setAttributes([11, 'my feature'])
620+
*
621+
* # will print [11, 'my feature']
622+
* print(feature.attributes())
559623
*
560-
* \param name The name of the field to delete
624+
* # clear the 'name' attribute
625+
* del feature['name']
626+
*
627+
* # will now print [11, NULL]
628+
* print(feature.attributes())
629+
* \endcode
630+
*
631+
* \param name The name of the field to clear
561632
* \throws KeyError if attribute name could not be converted to index
562-
* \note Alternatively in Python: @code del feature[name] @endcode
563633
* \see setFields()
564634
*/
565635
bool deleteAttribute( const QString &name );
@@ -598,10 +668,24 @@ class CORE_EXPORT QgsFeature
598668
*
599669
* Field map must be associated using setFields() before this method can be used.
600670
*
671+
* Alternatively, in Python it is possible to directly retrieve a field's value via the field's name:
672+
*
673+
* \code{.py}
674+
* fields = QgsFields()
675+
* fields.append(QgsField('my_id', QVariant.Int))
676+
* fields.append(QgsField('name', QVariant.String))
677+
* feature = QgsFeature(fields)
678+
* feature.setAttributes([11, 'my feature'])
679+
*
680+
* # print the "name" field value
681+
* print(feature['name'])
682+
* # print the "my_id" field value
683+
* print(feature['my_id'])
684+
* \endcode
685+
*
601686
* \param name The name of the attribute to get
602687
* \returns The value of the attribute
603688
* \throws KeyError if the field is not found
604-
* \note Alternatively in Python: @code feature[name] @endcode
605689
* \see setFields
606690
*/
607691
SIP_PYOBJECT attribute( const QString &name ) const;
@@ -625,8 +709,6 @@ class CORE_EXPORT QgsFeature
625709
/**
626710
* Lookup attribute value from its index.
627711
*
628-
* Field map must be associated using setFields() before this method can be used.
629-
*
630712
* \param fieldIdx The index of the attribute to get
631713
* \returns The value of the attribute, or an invalid/null variant if no such name exists
632714
* \see setFields()
@@ -637,12 +719,25 @@ class CORE_EXPORT QgsFeature
637719
/**
638720
* Lookup attribute value from its index.
639721
*
640-
* Field map must be associated using setFields() before this method can be used.
722+
* Alternatively, in Python it is possible to directly retrieve a field's value via its index:
723+
*
724+
* \code{.py}
725+
* feature = QgsFeature()
726+
* feature.setAttributes([11, 'my feature', 55.5])
727+
*
728+
* # will print 11
729+
* print(feature[0])
730+
*
731+
* # will print 'my feature'
732+
* print(feature[1])
733+
*
734+
* # will print 55.5
735+
* print(feature[2])
736+
* \endcode
641737
*
642738
* \param fieldIdx The index of the attribute to get
643739
* \returns The value of the attribute
644740
* \throws KeyError if the field is not found
645-
* \note Alternatively in Python: @code feature[fieldIdx] @endcode
646741
* \see setFields()
647742
*/
648743
SIP_PYOBJECT attribute( int fieldIdx ) const;

0 commit comments

Comments
 (0)
Please sign in to comment.