NAME

       dh_installdebputy - install debputy plugins for debhelper packages

SYNOPSIS

       dh_installdebputy [debhelper options] [-- params]

DESCRIPTION

       dh_installdebputy is a tool for installing debputy plugins from a package built using
       debhelper

OPTIONS

       Standard debhelper options (such as -p). Please see debhelper(7).

DIRECTORIES

       debian/debputy-plugins/, debian/PACKAGE.debputy-plugins/
           These directories will contain the plugin(s) and related support files.  Unlike most
           debhelper like tools, these must be directories (not files).

           Inside each directory, place the JSON descriptor file and (if relevant) related Python
           code and tests.  For a plugin named my-plugin installed into package, you might see:

               debian/package.debputy-plugins/my-plugin.json
                   debian/package.debputy-plugins/my_plugin.py
                   debian/package.debputy-plugins/my_plugin_check.py

           If any tests are provided, they will be run when the plugin is installed provided that
           py.test is available. Consider adding python3-pytest <!nocheck> to Build-Depends for
           this purpose.  Additionally, the tests can be picked up by the autopkgtests framework
           if you add autopkgtest-pkg-debputy to the Testsuite field in debian/control.

           It is possible to have multiple test files:

               debian/package.debputy-plugins/my-plugin.json
                   debian/package.debputy-plugins/my_plugin.py
                   debian/package.debputy-plugins/my_plugin_check_foo.py
                   debian/package.debputy-plugins/my_plugin_check_bar.py

           If you find yourself fighting with upstream's Python test runner picking up the
           debputy test, then please review the "DEALING WITH UPSTREAM'S PYTHON TEST RUNNER"
           sections for ways to deal with it.

DEALING WITH UPSTREAM'S PYTHON TEST RUNNER

       There are multiple ways to deal with upstream's python test runner picking up the debputy
       test. This section is written assuming upstream is using py.test (sometimes invoked as
       python3 -m pytest). While the concepts should carry over to other test runners, the
       examples and configuration names will probably not be directly reusable.

       The "least" effort option is to use _check instead _test in the naming of the debputy
       tests.  This will work for clean builds as long as the py.test run can still load the
       modules (which often assumes that debputy is installed). However, on unclean (dpkg-
       buildpackage -nc) builds, py.test can get confused because the module implementation file
       is both in debian/pkg.debputy-plugins and in debian/pkg. You can `rm` the version under
       debian/pkg manually, but it gets tedious.

       A more involved fix is to tell py.test to either stay away from the debian directory via
       norecursedirs OR explicitly tell it where to find the source and tests (pythonpath +
       testpaths). If upstream uses pyproject.toml, this could look something like:

               [tool.pytest.ini_options]
               # Option A: Stay out of the "debian" dir.
               norecursedirs = [
                       "debian",
               ]
               # Option B: Explicitly lists where the source and tests are.
               # In this case, `py.test` will work out of the box (without resorting
               # to "python3 -m pytest" or similar tricks). This approach may have
               # value for upstream for that particular reason.
               pythonpath = [
                       "src",
               ]
               testpaths = [
                       "tests",
                       # You may need "src" here if upstream uses --doctest-modules
               ]

       The upstream fix will also prevent py.test from picking up the plugin inside
       debian/package directory, which makes it more robust for dpkg-buildpackage -nc builds.

SEE ALSO

       debhelper(7)

       This program integrates into the debhelper suite.

AUTHOR

       Niels Thykier <niels@thykier.net>