From 1a4d42698c3595f0b3a20bda33413f0f96382f53 Mon Sep 17 00:00:00 2001
From: Karolina Surma <ksurma@redhat.com>
Date: Oct 29 2021 15:51:50 +0000
Subject: Document %pyproject_check_import and improvements to %py3_check_import


---

diff --git a/guidelines/modules/ROOT/pages/Python.adoc b/guidelines/modules/ROOT/pages/Python.adoc
index 2ac9f15..43b572e 100644
--- a/guidelines/modules/ROOT/pages/Python.adoc
+++ b/guidelines/modules/ROOT/pages/Python.adoc
@@ -1010,7 +1010,8 @@ dependencies not packaged in Fedora,
 and/or specialized hardware or resources.
 
 In these cases,
-you can use <<py3_check_import,the `+%py3_check_import+` macro>>
+you can use <<pyproject_check_import,the `+%pyproject_check_import+`>>
+or <<py3_check_import,the `+%py3_check_import+` macro>>
 to test that installed modules are importable.
 
 ==== Tox
@@ -1499,15 +1500,39 @@ The command that `+%pytest+` uses. May be redefined.
 [#py3_check_import]
 * `+%py3_check_import+`
 +
-Imports all modules given as positional arguments
-(separated by spaces or commas).
+Imports all provided modules.
 If running an upstream test suite is not feasible,
 use this macro in `+%check+` to test that public Python modules are importable.
 +
+Takes these arguments:
++
+--
+** `+-f+`: path to file containing qualified module names
+(separated by newlines).
+Optional, can be used multiple times.
+** `+-e+`: glob to exclude the matching module names.
+Optional, can be used multiple times.
+** `+-t+`: if set, import only top-level module names
+** Positional arguments (separated by spaces or commas)
+specify the module name(s) to check.
+--
++
 The macro sets various environment variables
 such as `+PATH+` and `+PYTHONPATH+`
 to ensure the packaged versions of modules are imported.
 
+[#pyproject_check_import]
+* `+%pyproject_check_import+`
++
+Imports all public modules found by
+<<pyproject_save_files,the `+%pyproject_save_files+` macro>>.
++
+This macro needs to be used with `+%pyproject_save_files+`
+(use `+%py3_check_import+` in other cases).
++
+The macro takes `+-e+`/`+-t+` as well as
+positional arguments for `+%py3_check_import+` above.
+
 === Extras macros
 
 [#pyproject_extras_subpkg]