Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/setuptools/extension.py: 56%

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"""