[pypy-commit] cffi default: Change the API and document it.

[arigo]

Author: Armin Rigo <arigo at tunes.org>
Branch: 
Changeset: r3206:cfa9cfaf529e
Date: 2019-01-31 12:44 +0100
http://bitbucket.org/cffi/cffi/changeset/cfa9cfaf529e/

Log:	Change the API and document it.

diff --git a/cffi/api.py b/cffi/api.py
--- a/cffi/api.py
+++ b/cffi/api.py
@@ -640,15 +640,19 @@
         if os.sep in module_name or (os.altsep and os.altsep in module_name):
             raise ValueError("'module_name' must not contain '/': use a dotted "
                              "name to make a 'package.module' location")
-        if "pkgconfig" in kwds:
-            from . import pkgconfig
-            libs = kwds.pop("pkgconfig")
-            if not isinstance(libs, (list, tuple)):
-                libs = [libs]
-            pkgconfig.merge_flags(kwds, pkgconfig.flags_from_pkgconfig(libs))
         self._assigned_source = (str(module_name), source,
                                  source_extension, kwds)
 
+    def set_source_pkgconfig(self, module_name, pkgconfig_libs, source,
+                             source_extension='.c', **kwds):
+        from . import pkgconfig
+        if not isinstance(pkgconfig_libs, list):
+            raise TypeError("the pkgconfig_libs argument must be a list "
+                            "of package names")
+        kwds2 = pkgconfig.flags_from_pkgconfig(pkgconfig_libs)
+        pkgconfig.merge_flags(kwds, kwds2)
+        self.set_source(module_name, source, source_extension, **kwds)
+
     def distutils_extension(self, tmpdir='build', verbose=True):
         from distutils.dir_util import mkpath
         from .recompiler import recompile
diff --git a/doc/source/cdef.rst b/doc/source/cdef.rst
--- a/doc/source/cdef.rst
+++ b/doc/source/cdef.rst
@@ -431,6 +431,23 @@
     }
     ''', source_extension='.cpp')
 
+.. _pkgconfig:
+
+**ffibuilder.set_source_pkgconfig(module_name, pkgconfig_libs,
+c_header_source, [\*\*keywords...])**:
+
+*New in version 1.12.*  This is equivalent to ``set_source()`` but it
+first calls the system utility ``pkg-config`` with the package names
+given in the list ``pkgconfig_libs``.  It collects the information
+obtained in this way and adds it to the explicitly-provided
+``**keywords`` (if any).  This should probably not be used on Windows.
+
+If the ``pkg-config`` program is not installed or does not know about
+the requested library, the call fails with ``cffi.PkgConfigError``.  If
+necessary, you can catch this error and try to call ``set_source()``
+directly (or, equivalently, call ``set_source_pkgconfig()`` with an
+empty list as the ``pkgconfig_libs`` argument).
+
 
 Letting the C compiler fill the gaps
 ------------------------------------
diff --git a/doc/source/whatsnew.rst b/doc/source/whatsnew.rst
--- a/doc/source/whatsnew.rst
+++ b/doc/source/whatsnew.rst
@@ -36,7 +36,10 @@
   cffi would contain possible crashes and/or memory leaks.  Hopefully,
   this has been fixed (see `issue #362`_).
 
+* `Direct support for pkg-config`__.
+
 .. _`issue #362`: https://bitbucket.org/cffi/cffi/issues/362/
+.. __: cdef.html#pkgconfig
 
 
 v1.11.5