Package: qgis-plugin-dev-tools
qgis-plugin-dev-toolsQGIS plugin development and packaging tools, which make managing runtime dependencies easy.PrerequisitesYour plugin package must be available to import from the python environment this tool is run in. For example, runningpython -c "import your_plugin_package_name"should not fail. Additionally, any dependency libraries must also be available in the python environment, so a dependency tosome_pypi_packageneeds something likepip install some_pypi_packagefor this tool to work.LimitationsBundling works by copying the code as-is and replacing the imports in all bundled files, so native library dependencies and other special cases might not work. To be safe, only depend on pure python libraries. Also verify the result zip works, since some import statements orsys.modulesusage might not be supported.SetupInstall this library withpip install qgis-plugin-dev-tools.Create apyproject.tomltool section:[tool.qgis_plugin_dev_tools]plugin_package_name="your_plugin_package_name"If the plugin runtime depends on external libraries, add the distribution names toruntime_requireslist as abstract dependencies.[tool.qgis_plugin_dev_tools]plugin_package_name="your_plugin_package_name"runtime_requires=["some_pypi_package"]If the plugin runtime dependencies have many dependencies themselves, it is possible to include those recursively withauto_add_recursive_runtime_dependencies. Alternatively, all the requirements can be listed inruntime_requires.[tool.qgis_plugin_dev_tools]plugin_package_name="your_plugin_package_name"runtime_requires=["some_pypi_package"]auto_add_recursive_runtime_dependencies=trueIf the plugin runtime dependencies do not work with the aforementioned configuration, the dependencies can be added to the Python Path withuse_dangerous_vendor_sys_path_appendflag. This method might beunsafeif there are conflicts between dependency versions of different plugins.[tool.qgis_plugin_dev_tools]plugin_package_name="your_plugin_package_name"runtime_requires=["some_pypi_package_with_binary_files"]use_dangerous_vendor_sys_path_append=trueBy default build version number is read from changelog top-most second level heading having format## version anything. This behaviour is configurable withversion_number_sourceto use plugin package distribution metadata. Optionally, the version number can also be provided as an argument for the build script usingqpdt b --version 0.1.0-rc2.[tool.qgis_plugin_dev_tools]plugin_package_name="your_plugin_package_name"version_number_source="distribution"# or "changelog" (default if missing)Plugin packagingRunqgis-plugin-dev-tools build(shortqpdt b) to package the plugin and any runtime dependencies to a standard QGIS plugin zip file, that can be installed and published.By default config is read frompyproject.toml, changelog notes fromCHANGELOG.md, version from changelog, and package is created in adistdirectory in the current working directory. Changelog contents and version number are inserted to themetadata.txtfile, so the version and changelog sections do not need manual updates.Plugin publishingRunqgis-plugin-dev-tools publish <file>(shortqpdt publish <file>) to publish a previously built plugin zip file to QGIS plugin repository.By default username and password are read fromQPDT_PUBLISH_USERNAMEandQPDT_PUBLISH_PASSWORDenvironment variables.Plugin development modeRunqgis-plugin-dev-tools start(shortqpdt s) to launch QGIS with the plugin installed and ready for development.By default config is read frompyproject.tomland runtime config from.envin the current working directory. Extra environment files can be passed using-eflag..envmust configure the executable path, and may configure debugger, profile name and any extra runtime variables necessary for the plugin.QGIS_EXECUTABLE_PATH=# path to qgis-bin/qgis-bin-ltr or .exe equivalents, necessary# DEBUGGER_LIBRARY= # debugpy/pydevd to start a debugger on init, library must be installed to the environment# DEVELOPMENT_PROFILE_NAME= # name of the profile that qgis is launched with, otherwise uses default# any other variables are added to the runtime QGIS environment# SOMETHING=somethingDevelopment mode bootstraps the launched QGIS to have access to any packages available to the launching python environment, setups enviroment variables, configures a debugger, and installs and enables the developed plugin package.Additionally editable installs for the plugin dependencies are supported. For example with a dependency tosome_pypi_package, usepip install -e /path/to/some_pypi_packageto providesome_pypi_packagein editable mode from a local directory, and usePlugin Reloaderto refresh new code when its changed on disk. This will also reload the declared dependencies.Developing multiple pluginsDevelopment mode also enables using and developing multiple plugins easily if certain requirements are satisfied for all extra plugins:Extra plugin must be installable python packagesSee e.g.Quickstart for setuptoolsExtra plugin must have entry point in group "qgis_plugin_dev_tools"See for example:Entry point usage with setuptoolsUse plugin package name for entry point nameExtra plugin needs to be installed in the same python environment where this tool is run inExtra plugins are loaded on launch and reloaded together with the main plugin ifPlugin Reloaderis used.Development of qgis-plugin-dev-toolsSeedevelopment readme.License & copyrightLicensed under GNU GPL v3.0.Copyright (C) 2022National Land Survey of Finland.ChangelogAll notable changes to this project will be documented in this file.The format is based onKeep a Changelog, and this project adheres toSemantic Versioning.0.6.2- 2023-09-27Fix: Fix issues with bundling requirements of the requirements recursively0.6.1- 2023-09-06update author email0.6.0- 2023-02-17Feat: Support dependencies having package references in .ui files0.5.0- 2022-11-09Feat: Add publish command to cliFix: Support build without actually importing the codeFix: Preserve case for key names in metadata file0.4.0- 2022-11-01Feat: Add an option to get version from distribution metadataFix: Rewrite imports correctly when dependency name is a prefix of the plugin package name0.3.0- 2022-09-02Feat: Add an option to append vendor package to the Python PathFeat: Add an option to bundle requirements of the requirements recursivelyFeat: Add module packages and .pyd files to the bundle if foundFeat: Add version as an optional build argumentChore: Drop support from Python < 3.90.2.1- 2022-07-07Fix: Correct some plain import rewrites0.2.0- 2022-06-13Feat: enable extra plugins in development mode0.1.2- 2022-05-30Fix: use UTF-8 encoding for file reads/writes0.1.1- 2022-05-16Fix: rewrite runtime requirement imports correctly0.1.0- 2022-05-12Initial release:startandbuildcommands with minimal configuration options.