setuptools.config.expand

module documentation

(source)

Utility functions to expand configuration directives or special values (such glob patterns). We can split the process of interpreting configuration files into 2 steps: 1. The parsing the file contents from strings to value objects that can be understand by Python (for example a string with a comma separated list of keywords into an actual Python list of strings). 2. The expansion (or post-processing) of these values according to the semantics ``setuptools`` assign to them (for example a configuration field with the ``file:`` directive should be expanded from a list of file paths to a single string with the contents of those files concatenated) This module focus on the second step, and therefore allow sharing the expansion functions among several configuration file formats. **PRIVATE MODULE**: API reserved for setuptools internal usage only.

Class	`EnsurePackagesDiscovered`	Some expand functions require all the packages to already be discovered before they run, e.g. :func:`read_attr`, :func:`resolve_class`, :func:`cmdclass`.
Class	`LazyMappingProxy`	Mapping proxy that delays resolving the target object, until really needed.
Class	`StaticModule`	Proxy to a module object that avoids executing arbitrary code.
Function	`canonic_data_files`	For compatibility with ``setup.py``, ``data_files`` should be a list of pairs instead of a dict.
Function	`canonic_package_data`	Undocumented
Function	`cmdclass`	Given a dictionary mapping command names to strings for qualified class names, apply :func:`resolve_class` to the dict values.
Function	`entry_points`	Given the contents of entry-points file, process it into a 2-level dictionary (``dict[str, dict[str, str]]``). The first level keys are entry-point groups, the second level keys are entry-point names, and the second level values are references to objects (that correspond to the entry-point value).
Function	`find_packages`	Works similarly to :func:`setuptools.find_packages`, but with all arguments given as keyword arguments. Moreover, ``where`` can be given as a list (the results will be simply concatenated).
Function	`glob_relative`	Expand the list of glob patterns, but preserving relative paths.
Function	`read_attr`	Reads the value of an attribute from a module.
Function	`read_files`	Return the content of the files concatenated using `` `` as str
Function	`resolve_class`	Given a qualified class name, return the associated class object
Function	`version`	When getting the version directly from an attribute, it should be normalised to string.
Function	`_assert_local`	Undocumented
Function	`_filter_existing_files`	Undocumented
Function	`_find_module`	Given a module (that could normally be imported by ``module_name`` after the build is complete), find the path to the parent directory where it is contained and the canonical name that could be used to import it considering the ``package_dir`` in the build configuration and ``root_dir``...
Function	`_find_spec`	Undocumented
Function	`_load_spec`	Undocumented
Function	`_nest_path`	Undocumented
Function	`_read_file`	Undocumented
Type Variable	`_K`	Undocumented
Type Variable	`_V`	Undocumented
Type Alias	`_Path`	Undocumented

def canonic_data_files(data_files: Union[list, dict], root_dir: Optional[_Path] = None) -> List[Tuple[str, List[str]]]: (source) ¶

For compatibility with ``setup.py``, ``data_files`` should be a list of pairs instead of a dict. This function also expands glob patterns.

def canonic_package_data(package_data: dict) -> dict: (source) ¶

Undocumented

def cmdclass(values: Dict[str, str], package_dir: Optional[Mapping[str, str]] = None, root_dir: Optional[_Path] = None) -> Dict[str, Callable]: (source) ¶

Given a dictionary mapping command names to strings for qualified class names, apply :func:`resolve_class` to the dict values.

def entry_points(text: str, text_source='entry-points') -> Dict[str, dict]: (source) ¶

Given the contents of entry-points file, process it into a 2-level dictionary (``dict[str, dict[str, str]]``). The first level keys are entry-point groups, the second level keys are entry-point names, and the second level values are references to objects (that correspond to the entry-point value).

def find_packages(*, namespaces=True, fill_package_dir: Optional[Dict[str, str]] = None, root_dir: Optional[_Path] = None, **kwargs) -> List[str]: (source) ¶

Works similarly to :func:`setuptools.find_packages`, but with all arguments given as keyword arguments. Moreover, ``where`` can be given as a list (the results will be simply concatenated). When the additional keyword argument ``namespaces`` is ``True``, it will behave like :func:`setuptools.find_namespace_packages`` (i.e. include implicit namespaces as per :pep:`420`). The ``where`` argument will be considered relative to ``root_dir`` (or the current working directory when ``root_dir`` is not given). If the ``fill_package_dir`` argument is passed, this function will consider it as a similar data structure to the ``package_dir`` configuration parameter add fill-in any missing package location. :rtype: list

def glob_relative(patterns: Iterable[str], root_dir: Optional[_Path] = None) -> List[str]: (source) ¶

Expand the list of glob patterns, but preserving relative paths. :param list[str] patterns: List of glob patterns :param str root_dir: Path to which globs should be relative (current directory by default) :rtype: list

def read_attr(attr_desc: str, package_dir: Optional[Mapping[str, str]] = None, root_dir: Optional[_Path] = None): (source) ¶

Reads the value of an attribute from a module. This function will try to read the attributed statically first (via :func:`ast.literal_eval`), and only evaluate the module if it fails. Examples: read_attr("package.attr") read_attr("package.module.attr") :param str attr_desc: Dot-separated string describing how to reach the attribute (see examples above) :param dict[str, str] package_dir: Mapping of package names to their location in disk (represented by paths relative to ``root_dir``). :param str root_dir: Path to directory containing all the packages in ``package_dir`` (current directory by default). :rtype: str

def read_files(filepaths: Union[str, bytes, Iterable[_Path]], root_dir=None) -> str: (source) ¶

Return the content of the files concatenated using `` `` as str This function is sandboxed and won't reach anything outside ``root_dir`` (By default ``root_dir`` is the current directory).

def resolve_class(qualified_class_name: str, package_dir: Optional[Mapping[str, str]] = None, root_dir: Optional[_Path] = None) -> Callable: (source) ¶

Given a qualified class name, return the associated class object

def version(value: Union[Callable, Iterable[Union[str, int]], str]) -> str: (source) ¶

When getting the version directly from an attribute, it should be normalised to string.

def _assert_local(filepath: _Path, root_dir: str): (source) ¶

Undocumented

def _filter_existing_files(filepaths: Iterable[_Path]) -> Iterator[_Path]: (source) ¶

Undocumented

def _find_module(module_name: str, package_dir: Optional[Mapping[str, str]], root_dir: _Path) -> Tuple[_Path, Optional[str], str]: (source) ¶

Given a module (that could normally be imported by ``module_name`` after the build is complete), find the path to the parent directory where it is contained and the canonical name that could be used to import it considering the ``package_dir`` in the build configuration and ``root_dir``