[Qgis-psc] Grant Report: Get rid of QgsProject::instance() singleton in qgis_core

Jan Caha jan.caha at lutraconsulting.co.uk
Fri Nov 13 01:42:05 PST 2026


Hello,

I am seding a report for grant "Get rid of QgsProject::instance() singleton
in qgis_core" (https://github.com/qgis/QGIS-Enhancement-Proposals/pull/380).

QEP 423 aims to remove QGIS core's dependency on the QgsProject::instance()
singleton, so that classes work with an explicit project instead of a
global singleton project. The work started in August 2026 - src/core
contained 101 calls to QgsProject::instance(). After the work 63 of them
have now been dealt with. 32 calls were removed outright, and 31 now
survive only inside deprecated methods or fallbacks marked for removal in
QGIS 5.0. These 31 can be deleted at the next API break with no further
design work.

The work followed a few repeating patterns. Where a class already had
access to a project, the code now uses it directly, usually through
QgsMapLayer::project(), a stored project member variable, or a
project-aware context such as QgsRelationContext or the expression
context's layer store. Where a public API had no way to receive a project,
a new constructor or method overload taking QgsProject was added. The old
signature was deprecated and kept as a thin shim that passes
QgsProject::instance(). Important note is that not all constructors could
be directly marked as Q_DECL_DEPRECATED, as there is QT limitation that
constructors that can be called without arguments (for example with all
arguments having default value) cannot be deprecated. But all of those are
marked with TODO for removal in QGIS 5.0. Where a layer may not belong to
any project, the code tries the layer's own project first and only then
falls back to the singleton. In total, 37 TODO QGIS 5.0 notes were added to
mark these compatibility paths for removal. In a few places the singleton
fallback was dropped completely, for example in relation aggregates, JSON
export of related attributes and QgsMapLayer named properties. As a result,
a layer without a project now behaves predictably instead of silently
reading another project's settings.

There are 37 remaining usages. 5 are part of the singleton's own code and
have to stay in the codebase. 2 are commented-out code. That leaves 30 real
call sites to solve. About 10 are mechanical, 7 need a new constructor that
takes the project. The remaining 13 need a design decision, because their
callers have no QgsProject to pass available in the class or close.

PRs related to QEP 423
 #66958, #66963, #66998, #67317, #67382, #67472, #67473, #67475, #67485,
#67529, #67539, #67540, #67541, #67542, #67543, #67575, #67580, #67581,
#67742, #67904, #67919, #67160, #67905

Jan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.osgeo.org/pipermail/qgis-psc/attachments/20261113/40de3443/attachment.htm>


More information about the QGIS-PSC mailing list