From 0fc05051dd93dcc05b0a30fa40fd07f4e8b4e505 Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Thu, 10 Apr 2025 11:53:12 +1000 Subject: [PATCH] Fix docstrings for QgsDateRange/QgsDateTimeRange We can't rely on sip to generate these -- it outputs malformed docstrings where the constructor docs are incorrectly placed before the class docstrings --- python/PyQt6/core/__init__.py.in | 52 ++++++++++++++++++ .../PyQt6/core/auto_generated/qgsrange.sip.in | 11 ---- python/core/__init__.py.in | 54 +++++++++++++++++++ python/core/auto_generated/qgsrange.sip.in | 11 ---- src/core/qgsrange.h | 4 +- 5 files changed, 109 insertions(+), 23 deletions(-) diff --git a/python/PyQt6/core/__init__.py.in b/python/PyQt6/core/__init__.py.in index f0f1e7a8e84..509ffcba133 100644 --- a/python/PyQt6/core/__init__.py.in +++ b/python/PyQt6/core/__init__.py.in @@ -70,6 +70,58 @@ def _date_range_repr(self): QgsDateTimeRange.__repr__ = _datetime_range_repr QgsDateRange.__repr__ = _date_range_repr + +QgsDateRange.__doc__ = """Stores a date range. + +Invalid dates as the beginning or end are permitted. In this case, the bound is +considered to be infinite. E.g. + +.. code-block:: python + + # a range containing all dates before 2017-1-1 + QgsDateRange(QDate(),QDate(2017,1,1)) + + # a range containing all dates after 2017-1-1 + QgsDateRange(QDate(2017,1,1),QDate()) + + +.. seealso:: :py:class:`QgsDateTimeRange` + +QgsDateRange(begin: Union[QDate, datetime.date], end: Union[QDate, datetime.date], includeBeginning: bool = True, includeEnd: bool = True) +Constructor for QgsDateRange. The ``begin`` and ``end`` are +specified, and optionally whether or not these bounds are included in +the range. + +QgsDateRange(QgsDateRange) +Copy constructor. +""" + +QgsDateTimeRange.__doc__ = """Stores a range of date times. + +Invalid date times as the beginning or end are permitted. In this case, the bound is +considered to be infinite. E.g. + +.. code-block:: python + + # a range containing all dates before 2017-1-1 + QgsDateTimeRange(QDateTime(),QDateTime(2017,1,1)) + + # a range containing all dates after 2017-1-1 + QgsDateTimeRange(QDateTime(2017,1,1),QDateTime()) + + +.. seealso:: :py:class:`QgsDateRange` + +QgsDateTimeRange(begin: Union[QDateTime, datetime.datetime], end: Union[QDateTime, datetime.datetime], includeBeginning: bool = True, includeEnd: bool = True) +Constructor for QgsDateTimeRange. The ``begin`` and ``end`` are +specified, and optionally whether or not these bounds are included in +the range. + +QgsDateTimeRange(QgsDateTimeRange) +Copy constructor. +""" + + QgsProperty.__bool__ = lambda self: self.propertyType() != Qgis.PropertyType.Invalid QgsOptionalExpression.__bool__ = lambda self: self.enabled() QgsUnsetAttributeValue.__hash__ = lambda self: 2178310 diff --git a/python/PyQt6/core/auto_generated/qgsrange.sip.in b/python/PyQt6/core/auto_generated/qgsrange.sip.in index fba00f63211..5fb3fc07835 100644 --- a/python/PyQt6/core/auto_generated/qgsrange.sip.in +++ b/python/PyQt6/core/auto_generated/qgsrange.sip.in @@ -425,17 +425,6 @@ range is empty and ``other`` is not, the range is changed and set to typedef QgsTemporalRange< QDate > QgsDateRange; -@DOCSTRINGSTEMPLATE@%Docstring -@DOCSTRINGSTEMPLATE@:py:class:`QgsRange` which stores a range of dates. -@DOCSTRINGSTEMPLATE@ @DOCSTRINGSTEMPLATE@Invalid QDates as the beginning -or end are permitted. In this case, @DOCSTRINGSTEMPLATE@the bound is -considered to be infinite. E.g. QgsDateRange(QDate(),QDate(2017,1,1)) -@DOCSTRINGSTEMPLATE@is treated as a range containing all dates before -2017-1-1. @DOCSTRINGSTEMPLATE@QgsDateRange(QDate(2017,1,1),QDate()) is -treated as a range containing all dates after 2017-1-1. -@DOCSTRINGSTEMPLATE@ @DOCSTRINGSTEMPLATE@.. seealso:: -:py:class:`QgsDateTimeRange` -@DOCSTRINGSTEMPLATE@%End typedef QgsTemporalRange< QDateTime > QgsDateTimeRange; diff --git a/python/core/__init__.py.in b/python/core/__init__.py.in index ff45e726766..2d3f85beafa 100644 --- a/python/core/__init__.py.in +++ b/python/core/__init__.py.in @@ -71,6 +71,60 @@ def _date_range_repr(self): QgsDateTimeRange.__repr__ = _datetime_range_repr QgsDateRange.__repr__ = _date_range_repr +# add docstrings for QgsDateRange/QgsDateTimeRange. These can't be done via sip as sip gets tripped up on the +# constructor docstrings for the templated class and creates malformed docstrings + +QgsDateRange.__doc__ = """Stores a date range. + +Invalid dates as the beginning or end are permitted. In this case, the bound is +considered to be infinite. E.g. + +.. code-block:: python + + # a range containing all dates before 2017-1-1 + QgsDateRange(QDate(),QDate(2017,1,1)) + + # a range containing all dates after 2017-1-1 + QgsDateRange(QDate(2017,1,1),QDate()) + + +.. seealso:: :py:class:`QgsDateTimeRange` + +QgsDateRange(begin: Union[QDate, datetime.date], end: Union[QDate, datetime.date], includeBeginning: bool = True, includeEnd: bool = True) +Constructor for QgsDateRange. The ``begin`` and ``end`` are +specified, and optionally whether or not these bounds are included in +the range. + +QgsDateRange(QgsDateRange) +Copy constructor. +""" + +QgsDateTimeRange.__doc__ = """Stores a range of date times. + +Invalid date times as the beginning or end are permitted. In this case, the bound is +considered to be infinite. E.g. + +.. code-block:: python + + # a range containing all dates before 2017-1-1 + QgsDateTimeRange(QDateTime(),QDateTime(2017,1,1)) + + # a range containing all dates after 2017-1-1 + QgsDateTimeRange(QDateTime(2017,1,1),QDateTime()) + + +.. seealso:: :py:class:`QgsDateRange` + +QgsDateTimeRange(begin: Union[QDateTime, datetime.datetime], end: Union[QDateTime, datetime.datetime], includeBeginning: bool = True, includeEnd: bool = True) +Constructor for QgsDateTimeRange. The ``begin`` and ``end`` are +specified, and optionally whether or not these bounds are included in +the range. + +QgsDateTimeRange(QgsDateTimeRange) +Copy constructor. +""" + + QgsProperty.__bool__ = lambda self: self.propertyType() != Qgis.PropertyType.Invalid QgsOptionalExpression.__bool__ = lambda self: self.enabled() QgsUnsetAttributeValue.__hash__ = lambda self: 2178310 diff --git a/python/core/auto_generated/qgsrange.sip.in b/python/core/auto_generated/qgsrange.sip.in index fba00f63211..5fb3fc07835 100644 --- a/python/core/auto_generated/qgsrange.sip.in +++ b/python/core/auto_generated/qgsrange.sip.in @@ -425,17 +425,6 @@ range is empty and ``other`` is not, the range is changed and set to typedef QgsTemporalRange< QDate > QgsDateRange; -@DOCSTRINGSTEMPLATE@%Docstring -@DOCSTRINGSTEMPLATE@:py:class:`QgsRange` which stores a range of dates. -@DOCSTRINGSTEMPLATE@ @DOCSTRINGSTEMPLATE@Invalid QDates as the beginning -or end are permitted. In this case, @DOCSTRINGSTEMPLATE@the bound is -considered to be infinite. E.g. QgsDateRange(QDate(),QDate(2017,1,1)) -@DOCSTRINGSTEMPLATE@is treated as a range containing all dates before -2017-1-1. @DOCSTRINGSTEMPLATE@QgsDateRange(QDate(2017,1,1),QDate()) is -treated as a range containing all dates after 2017-1-1. -@DOCSTRINGSTEMPLATE@ @DOCSTRINGSTEMPLATE@.. seealso:: -:py:class:`QgsDateTimeRange` -@DOCSTRINGSTEMPLATE@%End typedef QgsTemporalRange< QDateTime > QgsDateTimeRange; diff --git a/src/core/qgsrange.h b/src/core/qgsrange.h index 8760c145fbf..6c9eec2d001 100644 --- a/src/core/qgsrange.h +++ b/src/core/qgsrange.h @@ -744,7 +744,8 @@ class QgsTemporalRange * QgsDateRange(QDate(2017,1,1),QDate()) is treated as a range containing all dates after 2017-1-1. * \see QgsDateTimeRange */ -typedef QgsTemporalRange< QDate > QgsDateRange SIP_DOC_TEMPLATE; +typedef QgsTemporalRange< QDate > QgsDateRange; +// NOTE -- Python docstrings for QgsDateRange are patched in python/core/__init__.py Q_DECLARE_METATYPE( QgsDateRange ) @@ -758,6 +759,7 @@ Q_DECLARE_METATYPE( QgsDateRange ) * \see QgsDateRange */ typedef QgsTemporalRange< QDateTime > QgsDateTimeRange SIP_DOC_TEMPLATE; +// NOTE -- Python docstrings for QgsDateTimeRange are patched in python/core/__init__.py Q_DECLARE_METATYPE( QgsDateTimeRange )