python module: default extensions to hidden symbol visibility

python compiled extensions should never need to expose any symbol other
than PyInit_* which is declared with default visibility via
PyMODINIT_FUNC on supported compilers.

Thus, a reasonably sane default is to mark any other symbols as hidden,
while still respecting any manually specified visibility.

Gate this on the version of python itself, as not all versions decorate
PyMODINIT_FUNC properly.

2 files changed, 18 insertions, 0 deletions

diff --git a/docs/markdown/Python-module.md b/docs/markdown/Python-module.md
index 0602955..8809fd0 100644
--- a/docs/markdown/Python-module.md
+++ b/docs/markdown/Python-module.md
@@ -93,6 +93,12 @@ the addition of the following:
   it will be appended to that location. This keyword argument is
   mutually exclusive with `install_dir`
 
+Additionally, the following diverge from [[shared_module]]'s default behavior:
+
+- `gnu_symbol_visibility`: if unset, it will default to `'hidden'` on versions
+  of Python that support this (the python headers define `PyMODINIT_FUNC` has
+  default visibility).
+
 `extension_module` does not add any dependencies to the library so
 user may need to add `dependencies : py_installation.dependency()`,
 see [[dependency]].
diff --git a/docs/markdown/snippets/python-extension-module-visibility.md b/docs/markdown/snippets/python-extension-module-visibility.md
new file mode 100644
index 0000000..ed1fc48
--- /dev/null
+++ b/docs/markdown/snippets/python-extension-module-visibility.md
@@ -0,0 +1,12 @@
+## Python extension modules now build with hidden visibility
+
+Python extension modules are usually expected to only export a single symbol,
+decorated with the `PyMODINIT_FUNC` macro and providing the module entry point.
+On versions of python >= 3.9, the python headers contain GNU symbol visibility
+attributes to mark the init function with default visibility; it is then safe
+to set the [[shared_module]] inherited kwarg `gnu_symbol_visibility: 'hidden'`.
+
+In the interest of doing the right thing out of the box, this is now the
+default for extension modules for found installations that are new enough to
+have this set, which is not expected to break anything, but remains possible to
+set explicitly (in which case that will take precedence).