1from __future__ import annotations
2
3import functools
4import re
5from typing import TYPE_CHECKING
6
7from .monkey import get_unpatched
8
9import distutils.core
10import distutils.errors
11import distutils.extension
12
13
14def _have_cython():
15 """
16 Return True if Cython can be imported.
17 """
18 cython_impl = 'Cython.Distutils.build_ext'
19 try:
20 # from (cython_impl) import build_ext
21 __import__(cython_impl, fromlist=['build_ext']).build_ext
22 except Exception:
23 return False
24 return True
25
26
27# for compatibility
28have_pyrex = _have_cython
29if TYPE_CHECKING:
30 from typing_extensions import TypeAlias
31
32 # Work around a mypy issue where type[T] can't be used as a base: https://github.com/python/mypy/issues/10962
33 _Extension: TypeAlias = distutils.core.Extension
34else:
35 _Extension = get_unpatched(distutils.core.Extension)
36
37
38class Extension(_Extension):
39 """
40 Describes a single extension module.
41
42 This means that all source files will be compiled into a single binary file
43 ``<module path>.<suffix>`` (with ``<module path>`` derived from ``name`` and
44 ``<suffix>`` defined by one of the values in
45 ``importlib.machinery.EXTENSION_SUFFIXES``).
46
47 In the case ``.pyx`` files are passed as ``sources and`` ``Cython`` is **not**
48 installed in the build environment, ``setuptools`` may also try to look for the
49 equivalent ``.cpp`` or ``.c`` files.
50
51 :arg str name:
52 the full name of the extension, including any packages -- ie.
53 *not* a filename or pathname, but Python dotted name
54
55 :arg list[str] sources:
56 list of source filenames, relative to the distribution root
57 (where the setup script lives), in Unix form (slash-separated)
58 for portability. Source files may be C, C++, SWIG (.i),
59 platform-specific resource files, or whatever else is recognized
60 by the "build_ext" command as source for a Python extension.
61
62 :keyword list[str] include_dirs:
63 list of directories to search for C/C++ header files (in Unix
64 form for portability)
65
66 :keyword list[tuple[str, str|None]] define_macros:
67 list of macros to define; each macro is defined using a 2-tuple:
68 the first item corresponding to the name of the macro and the second
69 item either a string with its value or None to
70 define it without a particular value (equivalent of "#define
71 FOO" in source or -DFOO on Unix C compiler command line)
72
73 :keyword list[str] undef_macros:
74 list of macros to undefine explicitly
75
76 :keyword list[str] library_dirs:
77 list of directories to search for C/C++ libraries at link time
78
79 :keyword list[str] libraries:
80 list of library names (not filenames or paths) to link against
81
82 :keyword list[str] runtime_library_dirs:
83 list of directories to search for C/C++ libraries at run time
84 (for shared extensions, this is when the extension is loaded).
85 Setting this will cause an exception during build on Windows
86 platforms.
87
88 :keyword list[str] extra_objects:
89 list of extra files to link with (eg. object files not implied
90 by 'sources', static library that must be explicitly specified,
91 binary resource files, etc.)
92
93 :keyword list[str] extra_compile_args:
94 any extra platform- and compiler-specific information to use
95 when compiling the source files in 'sources'. For platforms and
96 compilers where "command line" makes sense, this is typically a
97 list of command-line arguments, but for other platforms it could
98 be anything.
99
100 :keyword list[str] extra_link_args:
101 any extra platform- and compiler-specific information to use
102 when linking object files together to create the extension (or
103 to create a new static Python interpreter). Similar
104 interpretation as for 'extra_compile_args'.
105
106 :keyword list[str] export_symbols:
107 list of symbols to be exported from a shared extension. Not
108 used on all platforms, and not generally necessary for Python
109 extensions, which typically export exactly one symbol: "init" +
110 extension_name.
111
112 :keyword list[str] swig_opts:
113 any extra options to pass to SWIG if a source file has the .i
114 extension.
115
116 :keyword list[str] depends:
117 list of files that the extension depends on
118
119 :keyword str language:
120 extension language (i.e. "c", "c++", "objc"). Will be detected
121 from the source extensions if not provided.
122
123 :keyword bool optional:
124 specifies that a build failure in the extension should not abort the
125 build process, but simply not install the failing extension.
126
127 :keyword bool py_limited_api:
128 opt-in flag for the usage of :doc:`Python's limited API <python:c-api/stable>`.
129
130 :raises setuptools.errors.PlatformError: if ``runtime_library_dirs`` is
131 specified on Windows. (since v63)
132 """
133
134 # These 4 are set and used in setuptools/command/build_ext.py
135 # The lack of a default value and risk of `AttributeError` is purposeful
136 # to avoid people forgetting to call finalize_options if they modify the extension list.
137 # See example/rationale in https://github.com/pypa/setuptools/issues/4529.
138 _full_name: str #: Private API, internal use only.
139 _links_to_dynamic: bool #: Private API, internal use only.
140 _needs_stub: bool #: Private API, internal use only.
141 _file_name: str #: Private API, internal use only.
142
143 def __init__(self, name: str, sources, *args, py_limited_api: bool = False, **kw):
144 # The *args is needed for compatibility as calls may use positional
145 # arguments. py_limited_api may be set only via keyword.
146 self.py_limited_api = py_limited_api
147 super().__init__(name, sources, *args, **kw)
148
149 def _convert_pyx_sources_to_lang(self):
150 """
151 Replace sources with .pyx extensions to sources with the target
152 language extension. This mechanism allows language authors to supply
153 pre-converted sources but to prefer the .pyx sources.
154 """
155 if _have_cython():
156 # the build has Cython, so allow it to compile the .pyx files
157 return
158 lang = self.language or ''
159 target_ext = '.cpp' if lang.lower() == 'c++' else '.c'
160 sub = functools.partial(re.sub, '.pyx$', target_ext)
161 self.sources = list(map(sub, self.sources))
162
163
164class Library(Extension):
165 """Just like a regular Extension, but built as a library instead"""