Add docs

conda_build/metadata.py

@@ -2327,7 +2327,7 @@ def copy(self: Self) -> MetaData:
         return new
 
     @property
-    def python_version_independent(self):
+    def python_version_independent(self) -> bool:
         return (
             self.get_value("build/python_version_independent")
             or self.get_value("build/noarch") == "python"
@@ -2336,7 +2336,7 @@ def python_version_independent(self):
 
     @python_version_independent.setter
     def python_version_independent(self, value: bool) -> None:
-        self.meta.setdefault("build", {})["python_version_independent"] = value
+        self.meta.setdefault("build", {})["python_version_independent"] = bool(value)
 
     @property
     def noarch(self):

docs/source/resources/define-metadata.rst

@@ -687,6 +687,61 @@ conda >=4.3 to install.
    it was built, which probably will result in incorrect/incomplete installation in other
    platforms.
 
+Python version independent packages
+-----------------------------------
+
+Allows you to specify "no python version" when building a Python
+package thus making it compatible with a user specified range of Python
+versions. Main use-case for this is to create ABI3 packages as specified
+in [CEP20](https://github.com/conda/ceps/blob/main/cep-0020.md).
+
+ABI3 packages support building a native Python extension using a
+specific Python version and running it against any later Python version.
+ABI3 or stable ABI is supported by only CPython - the reference Python
+implementation with the Global Interpreter Lock (GIL) enabled. Therefore
+package builders who wishes to support the free-threaded python build
+or another implementation like PyPy still has to build a conda package
+specific to that ABI as they don't support ABI3. There are other
+proposed standards like HPy and ABI4 (work-in-progress) that tries
+to address all python implementations.
+
+conda-build can indicate that a conda package works for any python version
+by adding
+
+.. code-block:: yaml
+
+   build:
+     python_version_independent: true
+
+A package builder also has to indicate which standard is supported by
+the package, i.e., for ABI3,
+
+.. code-block:: yaml
+
+   requirements:
+     host:
+       - python-abi3
+       - python
+     run:
+       - python
+
+
+In order to support ABI3 with python 3.9 and onwards and
+free-threaded builds you can do
+
+.. code-block:: yaml
+   build:
+     python_version_independent: true   # [py == 39]
+     skip: true                         # [py > 39 and python.endswith("t")]
+
+   requirements:
+     host:
+       - python-abi3                    # [py == 39]
+       - python
+     run:
+       - python
+
+
 Include build recipe
 --------------------
 

tests/test_api_build.py

@@ -145,6 +145,20 @@ def test_recipe_builds(
     api.build(str(recipe), config=testing_config)
 
 
+@pytest.mark.slow
+@pytest.mark.serial
+def test_python_version_independent(
+    testing_config,
+    monkeypatch: pytest.MonkeyPatch,
+):
+    recipe = os.path.join(metadata_dir, "_python_version_independent")
+    testing_config.activate = True
+    monkeypatch.setenv("CONDA_TEST_VAR", "conda_test")
+    monkeypatch.setenv("CONDA_TEST_VAR_2", "conda_test_2")
+    output = api.build(str(recipe), config=testing_config)[0]
+    print(output)
+
+
 @pytest.mark.serial
 @pytest.mark.skipif(
     "CI" in os.environ and "GITHUB_WORKFLOW" in os.environ,