jpayne@68: from __future__ import annotations jpayne@68: jpayne@68: import functools jpayne@68: import re jpayne@68: from typing import TYPE_CHECKING jpayne@68: jpayne@68: from setuptools._path import StrPath jpayne@68: jpayne@68: from .monkey import get_unpatched jpayne@68: jpayne@68: import distutils.core jpayne@68: import distutils.errors jpayne@68: import distutils.extension jpayne@68: jpayne@68: jpayne@68: def _have_cython(): jpayne@68: """ jpayne@68: Return True if Cython can be imported. jpayne@68: """ jpayne@68: cython_impl = 'Cython.Distutils.build_ext' jpayne@68: try: jpayne@68: # from (cython_impl) import build_ext jpayne@68: __import__(cython_impl, fromlist=['build_ext']).build_ext jpayne@68: except Exception: jpayne@68: return False jpayne@68: return True jpayne@68: jpayne@68: jpayne@68: # for compatibility jpayne@68: have_pyrex = _have_cython jpayne@68: if TYPE_CHECKING: jpayne@68: # Work around a mypy issue where type[T] can't be used as a base: https://github.com/python/mypy/issues/10962 jpayne@68: from distutils.core import Extension as _Extension jpayne@68: else: jpayne@68: _Extension = get_unpatched(distutils.core.Extension) jpayne@68: jpayne@68: jpayne@68: class Extension(_Extension): jpayne@68: """ jpayne@68: Describes a single extension module. jpayne@68: jpayne@68: This means that all source files will be compiled into a single binary file jpayne@68: ``.`` (with ```` derived from ``name`` and jpayne@68: ```` defined by one of the values in jpayne@68: ``importlib.machinery.EXTENSION_SUFFIXES``). jpayne@68: jpayne@68: In the case ``.pyx`` files are passed as ``sources and`` ``Cython`` is **not** jpayne@68: installed in the build environment, ``setuptools`` may also try to look for the jpayne@68: equivalent ``.cpp`` or ``.c`` files. jpayne@68: jpayne@68: :arg str name: jpayne@68: the full name of the extension, including any packages -- ie. jpayne@68: *not* a filename or pathname, but Python dotted name jpayne@68: jpayne@68: :arg list[str|os.PathLike[str]] sources: jpayne@68: list of source filenames, relative to the distribution root jpayne@68: (where the setup script lives), in Unix form (slash-separated) jpayne@68: for portability. Source files may be C, C++, SWIG (.i), jpayne@68: platform-specific resource files, or whatever else is recognized jpayne@68: by the "build_ext" command as source for a Python extension. jpayne@68: jpayne@68: :keyword list[str] include_dirs: jpayne@68: list of directories to search for C/C++ header files (in Unix jpayne@68: form for portability) jpayne@68: jpayne@68: :keyword list[tuple[str, str|None]] define_macros: jpayne@68: list of macros to define; each macro is defined using a 2-tuple: jpayne@68: the first item corresponding to the name of the macro and the second jpayne@68: item either a string with its value or None to jpayne@68: define it without a particular value (equivalent of "#define jpayne@68: FOO" in source or -DFOO on Unix C compiler command line) jpayne@68: jpayne@68: :keyword list[str] undef_macros: jpayne@68: list of macros to undefine explicitly jpayne@68: jpayne@68: :keyword list[str] library_dirs: jpayne@68: list of directories to search for C/C++ libraries at link time jpayne@68: jpayne@68: :keyword list[str] libraries: jpayne@68: list of library names (not filenames or paths) to link against jpayne@68: jpayne@68: :keyword list[str] runtime_library_dirs: jpayne@68: list of directories to search for C/C++ libraries at run time jpayne@68: (for shared extensions, this is when the extension is loaded). jpayne@68: Setting this will cause an exception during build on Windows jpayne@68: platforms. jpayne@68: jpayne@68: :keyword list[str] extra_objects: jpayne@68: list of extra files to link with (eg. object files not implied jpayne@68: by 'sources', static library that must be explicitly specified, jpayne@68: binary resource files, etc.) jpayne@68: jpayne@68: :keyword list[str] extra_compile_args: jpayne@68: any extra platform- and compiler-specific information to use jpayne@68: when compiling the source files in 'sources'. For platforms and jpayne@68: compilers where "command line" makes sense, this is typically a jpayne@68: list of command-line arguments, but for other platforms it could jpayne@68: be anything. jpayne@68: jpayne@68: :keyword list[str] extra_link_args: jpayne@68: any extra platform- and compiler-specific information to use jpayne@68: when linking object files together to create the extension (or jpayne@68: to create a new static Python interpreter). Similar jpayne@68: interpretation as for 'extra_compile_args'. jpayne@68: jpayne@68: :keyword list[str] export_symbols: jpayne@68: list of symbols to be exported from a shared extension. Not jpayne@68: used on all platforms, and not generally necessary for Python jpayne@68: extensions, which typically export exactly one symbol: "init" + jpayne@68: extension_name. jpayne@68: jpayne@68: :keyword list[str] swig_opts: jpayne@68: any extra options to pass to SWIG if a source file has the .i jpayne@68: extension. jpayne@68: jpayne@68: :keyword list[str] depends: jpayne@68: list of files that the extension depends on jpayne@68: jpayne@68: :keyword str language: jpayne@68: extension language (i.e. "c", "c++", "objc"). Will be detected jpayne@68: from the source extensions if not provided. jpayne@68: jpayne@68: :keyword bool optional: jpayne@68: specifies that a build failure in the extension should not abort the jpayne@68: build process, but simply not install the failing extension. jpayne@68: jpayne@68: :keyword bool py_limited_api: jpayne@68: opt-in flag for the usage of :doc:`Python's limited API `. jpayne@68: jpayne@68: :raises setuptools.errors.PlatformError: if ``runtime_library_dirs`` is jpayne@68: specified on Windows. (since v63) jpayne@68: """ jpayne@68: jpayne@68: # These 4 are set and used in setuptools/command/build_ext.py jpayne@68: # The lack of a default value and risk of `AttributeError` is purposeful jpayne@68: # to avoid people forgetting to call finalize_options if they modify the extension list. jpayne@68: # See example/rationale in https://github.com/pypa/setuptools/issues/4529. jpayne@68: _full_name: str #: Private API, internal use only. jpayne@68: _links_to_dynamic: bool #: Private API, internal use only. jpayne@68: _needs_stub: bool #: Private API, internal use only. jpayne@68: _file_name: str #: Private API, internal use only. jpayne@68: jpayne@68: def __init__( jpayne@68: self, jpayne@68: name: str, jpayne@68: sources: list[StrPath], jpayne@68: *args, jpayne@68: py_limited_api: bool = False, jpayne@68: **kw, jpayne@68: ): jpayne@68: # The *args is needed for compatibility as calls may use positional jpayne@68: # arguments. py_limited_api may be set only via keyword. jpayne@68: self.py_limited_api = py_limited_api jpayne@68: super().__init__( jpayne@68: name, jpayne@68: sources, # type: ignore[arg-type] # Vendored version of setuptools supports PathLike jpayne@68: *args, jpayne@68: **kw, jpayne@68: ) jpayne@68: jpayne@68: def _convert_pyx_sources_to_lang(self): jpayne@68: """ jpayne@68: Replace sources with .pyx extensions to sources with the target jpayne@68: language extension. This mechanism allows language authors to supply jpayne@68: pre-converted sources but to prefer the .pyx sources. jpayne@68: """ jpayne@68: if _have_cython(): jpayne@68: # the build has Cython, so allow it to compile the .pyx files jpayne@68: return jpayne@68: lang = self.language or '' jpayne@68: target_ext = '.cpp' if lang.lower() == 'c++' else '.c' jpayne@68: sub = functools.partial(re.sub, '.pyx$', target_ext) jpayne@68: self.sources = list(map(sub, self.sources)) jpayne@68: jpayne@68: jpayne@68: class Library(Extension): jpayne@68: """Just like a regular Extension, but built as a library instead"""