From 6417adf60e18f6843f59dfdd1a4a0548d978b684 Mon Sep 17 00:00:00 2001 From: Nyall Dawson Date: Wed, 9 Jul 2025 08:51:21 +1000 Subject: [PATCH] Fix Python docstring for dijkstra method Fixes #56172 --- cmake_templates/Doxyfile.in | 1 + .../network/qgsgraphanalyzer.sip.in | 15 ++++++++------- .../network/qgsgraphanalyzer.sip.in | 15 ++++++++------- scripts/sipify.py | 3 ++- src/analysis/network/qgsgraphanalyzer.h | 2 +- src/core/qgis_sip.h | 8 ++++++++ 6 files changed, 28 insertions(+), 16 deletions(-) diff --git a/cmake_templates/Doxyfile.in b/cmake_templates/Doxyfile.in index 5f38d1215fc..1704adf86df 100644 --- a/cmake_templates/Doxyfile.in +++ b/cmake_templates/Doxyfile.in @@ -2418,6 +2418,7 @@ EXPAND_AS_DEFINED = "SIP_ABSTRACT" \ "SIP_NODEFAULTCTORS" \ "SIP_NO_FILE" \ "SIP_OUT" \ + "SIP_DOCSTRING_OUT" \ "SIP_PROPERTY" \ "SIP_PYARGDEFAULT" \ "SIP_PYARGREMOVE" \ diff --git a/python/PyQt6/analysis/auto_generated/network/qgsgraphanalyzer.sip.in b/python/PyQt6/analysis/auto_generated/network/qgsgraphanalyzer.sip.in index cf25bb3b352..d9131070379 100644 --- a/python/PyQt6/analysis/auto_generated/network/qgsgraphanalyzer.sip.in +++ b/python/PyQt6/analysis/auto_generated/network/qgsgraphanalyzer.sip.in @@ -21,19 +21,20 @@ points using different strategies with Dijkstra's algorithm. #include "qgsgraphanalyzer.h" %End public: - static SIP_PYLIST dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree = 0, QVector *resultCost = 0 ); + static SIP_PYLIST dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree = 0, QVector *resultCost = 0 ); %Docstring Solve shortest path problem using Dijkstra algorithm :param source: source graph :param startVertexIdx: index of the start vertex :param criterionNum: index of the optimization strategy -:param resultTree: array that represents shortest path tree. resultTree[ - vertexIndex ] == inboundingArcIndex if vertex - reachable, otherwise resultTree[ vertexIndex ] == -1. - Note that the startVertexIdx will also have a value - of -1 and may need special handling by callers. -:param resultCost: array of the paths costs + +:return: - resultTree: array that represents shortest path tree. + resultTree[ vertexIndex ] == inboundingArcIndex if vertex + reachable, otherwise resultTree[ vertexIndex ] == -1. Note + that the startVertexIdx will also have a value of -1 and may + need special handling by callers. + - resultCost: array of the paths costs %End %MethodCode diff --git a/python/analysis/auto_generated/network/qgsgraphanalyzer.sip.in b/python/analysis/auto_generated/network/qgsgraphanalyzer.sip.in index cf25bb3b352..d9131070379 100644 --- a/python/analysis/auto_generated/network/qgsgraphanalyzer.sip.in +++ b/python/analysis/auto_generated/network/qgsgraphanalyzer.sip.in @@ -21,19 +21,20 @@ points using different strategies with Dijkstra's algorithm. #include "qgsgraphanalyzer.h" %End public: - static SIP_PYLIST dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree = 0, QVector *resultCost = 0 ); + static SIP_PYLIST dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree = 0, QVector *resultCost = 0 ); %Docstring Solve shortest path problem using Dijkstra algorithm :param source: source graph :param startVertexIdx: index of the start vertex :param criterionNum: index of the optimization strategy -:param resultTree: array that represents shortest path tree. resultTree[ - vertexIndex ] == inboundingArcIndex if vertex - reachable, otherwise resultTree[ vertexIndex ] == -1. - Note that the startVertexIdx will also have a value - of -1 and may need special handling by callers. -:param resultCost: array of the paths costs + +:return: - resultTree: array that represents shortest path tree. + resultTree[ vertexIndex ] == inboundingArcIndex if vertex + reachable, otherwise resultTree[ vertexIndex ] == -1. Note + that the startVertexIdx will also have a value of -1 and may + need special handling by callers. + - resultCost: array of the paths costs %End %MethodCode diff --git a/scripts/sipify.py b/scripts/sipify.py index 24e3148171c..430a548aed7 100755 --- a/scripts/sipify.py +++ b/scripts/sipify.py @@ -1364,7 +1364,7 @@ def fix_annotations(line): CONTEXT.skipped_params_remove.append(param) dbg_info(f"caught removed param: {CONTEXT.skipped_params_remove[-1]}") - _out_params = re.findall(r"(\w+)\s+SIP_OUT", line) + _out_params = re.findall(r"(\w+)\s+(?:SIP_OUT|SIP_DOCSTRING_OUT)", line) for param in _out_params: CONTEXT.skipped_params_out.append(param) dbg_info(f"caught removed param: {CONTEXT.skipped_params_out[-1]}") @@ -1388,6 +1388,7 @@ def fix_annotations(line): r"\bSIP_KEEPREFERENCE\b": "/KeepReference/", r"\bSIP_NODEFAULTCTORS\b": "/NoDefaultCtors/", r"\bSIP_OUT\b": "/Out/", + r"\bSIP_DOCSTRING_OUT\b": "", r"\bSIP_RELEASEGIL\b": "/ReleaseGIL/", r"\bSIP_HOLDGIL\b": "/HoldGIL/", r"\bSIP_TRANSFER\b": "/Transfer/", diff --git a/src/analysis/network/qgsgraphanalyzer.h b/src/analysis/network/qgsgraphanalyzer.h index b83d05a3ff0..f0ecc6f03b1 100644 --- a/src/analysis/network/qgsgraphanalyzer.h +++ b/src/analysis/network/qgsgraphanalyzer.h @@ -40,7 +40,7 @@ class ANALYSIS_EXPORT QgsGraphAnalyzer * Note that the startVertexIdx will also have a value of -1 and may need special handling by callers. * \param resultCost array of the paths costs */ - static void SIP_PYALTERNATIVETYPE( SIP_PYLIST ) dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree = nullptr, QVector *resultCost = nullptr ); + static void SIP_PYALTERNATIVETYPE( SIP_PYLIST ) dijkstra( const QgsGraph *source, int startVertexIdx, int criterionNum, QVector *resultTree SIP_DOCSTRING_OUT = nullptr, QVector *resultCost SIP_DOCSTRING_OUT = nullptr ); #ifdef SIP_RUN //%MethodCode diff --git a/src/core/qgis_sip.h b/src/core/qgis_sip.h index e95515faae1..5afa9982af7 100644 --- a/src/core/qgis_sip.h +++ b/src/core/qgis_sip.h @@ -57,6 +57,14 @@ */ #define SIP_OUT +/* + * Alternative to SIP_OUT for methods with manual SIP MethodCode, where only the docstring needs to be + * considered for the output argument. + * + * No /Out/ annotation will be added to the SIP bindings. + */ +#define SIP_DOCSTRING_OUT + /* * https://www.riverbankcomputing.com/static/Docs/sip/annotations.html#argument-annotation-In */