setuptools.dist.Distribution

class documentation

class Distribution(_Distribution): (source)

Known subclasses: setuptools.build_meta.Distribution

View In Hierarchy

Distribution with support for tests and package data This is an enhanced version of 'distutils.dist.Distribution' that effectively adds the following new optional keyword arguments to 'setup()': 'install_requires' -- a string or sequence of strings specifying project versions that the distribution requires when installed, in the format used by 'pkg_resources.require()'. They will be installed automatically when the package is installed. If you wish to use packages that are not available in PyPI, or want to give your users an alternate download location, you can add a 'find_links' option to the '[easy_install]' section of your project's 'setup.cfg' file, and then setuptools will scan the listed web pages for links that satisfy the requirements. 'extras_require' -- a dictionary mapping names of optional "extras" to the additional requirement(s) that using those extras incurs. For example, this:: extras_require = dict(reST = ["docutils>=0.3", "reSTedit"]) indicates that the distribution can optionally provide an extra capability called "reST", but it can only be used if docutils and reSTedit are installed. If the user installs your package using EasyInstall and requests one of your extras, the corresponding additional requirements will be installed if needed. 'test_suite' -- the name of a test suite to run for the 'test' command. If the user runs 'python setup.py test', the package will be installed, and the named test suite will be run. The format is the same as would be used on a 'unittest.py' command line. That is, it is the dotted name of an object to import and call to generate a test suite. 'package_data' -- a dictionary mapping package names to lists of filenames or globs to use to find data files contained in the named packages. If the dictionary has filenames or globs listed under '""' (the empty string), those names will be searched for in every package, in addition to any names for the specific package. Data files found using these names/globs will be installed along with the package, in the same location as the package. Note that globs are allowed to reference the contents of non-package subdirectories, as long as you use '/' as a path separator. (Globs are automatically converted to platform-specific paths at runtime.) In addition to these new keywords, this class also has several new methods for manipulating the distribution's contents. For example, the 'include()' and 'exclude()' methods can be thought of as in-place add and subtract commands that add or remove packages, modules, extensions, and so on from the distribution.

Method __init__ Undocumented
Method exclude Remove items from distribution that are named in keyword arguments
Method exclude_package Remove packages, modules, and extensions in named package
Method fetch_build_egg Fetch an egg needed for building
Method fetch_build_eggs Resolve pre-setup requirements
Method finalize_options Allow plugins to apply arbitrary operations to the distribution. Each hook may optionally define a 'order' to influence the order of execution. Smaller numbers go first and the default is 0.
Method get_cmdline_options Return a '{cmd: {opt:val}}' map of all command-line options
Method get_command_class Pluggable version of get_command_class()
Method get_command_list Undocumented
Method get_egg_cache_dir Undocumented
Method handle_display_options If there were any non-global "display-only" options (--help-commands or the metadata display options) on the command line, display the requested info and return true; else return false.
Method has_contents_for Return true if 'exclude_package(package)' would do something
Method include Add items to distribution that are named in keyword arguments
Method iter_distribution_names Yield all packages, modules, and extension names in distribution
Method make_option_lowercase Undocumented
Method parse_config_files Parses configuration files from various levels and loads configuration.
Method patch_missing_pkg_info Undocumented
Method print_commands Undocumented
Method run_command Undocumented
Method warn_dash_deprecation Undocumented
Instance Variable dependency_links Undocumented
Instance Variable dist_files Undocumented
Instance Variable ext_modules Undocumented
Instance Variable extras_require Undocumented
Instance Variable global_options Undocumented
Instance Variable install_requires Undocumented
Instance Variable negative_opt Undocumented
Instance Variable package_data Undocumented
Instance Variable packages Undocumented
Instance Variable py_modules Undocumented
Instance Variable set_defaults Undocumented
Instance Variable setup_requires Undocumented
Instance Variable src_root Undocumented
Static Method _expand_patterns >>> list(Distribution._expand_patterns(['LICENSE'])) ['LICENSE'] >>> list(Distribution._expand_patterns(['setup.cfg', 'LIC*'])) ['setup.cfg', 'LICENSE']
Static Method _normalize_version Undocumented
Static Method _removed When removing an entry point, if metadata is loaded from an older version of Setuptools, that removed entry point will attempt to be loaded and will fail. See #2765 for more details.
Static Method _suffix_for For a requirement, return the 'extras_require' suffix for that requirement.
Static Method _validate_version Undocumented
Method _clean_req Given a Requirement, remove environment markers and return it.
Method _convert_extras_requirements Convert requirements in `extras_require` of the form `"extra": ["barbazquux; {marker}"]` to `"extra:{marker}": ["barbazquux"]`.
Method _exclude_misc Handle 'exclude()' for list/tuple attrs without a special handler
Method _exclude_packages Undocumented
Method _finalize_license_files Compute names of all license files which should be included.
Method _finalize_requires Set `metadata.python_requires` and fix environment markers in `install_requires` and `extras_require`.
Method _finalize_setup_keywords Undocumented
Method _get_project_config_files Add default file and split between INI and TOML
Method _include_misc Handle 'include()' for list/tuple attrs without a special handler
Method _move_install_requirements_markers Move requirements in `install_requires` that are using environment markers `extras_require`.
Method _parse_command_opts Undocumented
Method _parse_config_files Adapted from distutils.dist.Distribution.parse_config_files, this method provides the same functionality in subtly-improved ways.
Method _set_command_options Set the options for 'command_obj' from 'option_dict'. Basically this means copying elements of a dictionary ('option_dict') to attributes of an instance ('command').
Method _set_metadata_defaults Fill-in missing metadata fields not supported by distutils. Some fields may have been set by other tools (e.g. pbr). Those fields (vars(self.metadata)) take precedence to supplied attrs.
Method _setuptools_commands Undocumented
Method _validate_metadata Undocumented
Constant _DISTUTILS_UNSUPPORTED_METADATA Undocumented
Instance Variable _orig_extras_require Undocumented
Instance Variable _orig_install_requires Undocumented
Instance Variable _patched_dist Undocumented
Instance Variable _referenced_files Undocumented
Instance Variable _tmp_extras_require Undocumented
def __init__(self, attrs=None): (source)

Undocumented

def exclude(self, **attrs): (source)

Remove items from distribution that are named in keyword arguments For example, 'dist.exclude(py_modules=["x"])' would remove 'x' from the distribution's 'py_modules' attribute. Excluding packages uses the 'exclude_package()' method, so all of the package's contained packages, modules, and extensions are also excluded. Currently, this method only supports exclusion from attributes that are lists or tuples. If you need to add support for excluding from other attributes in this or a subclass, you can add an '_exclude_X' method, where 'X' is the name of the attribute. The method will be called with the value passed to 'exclude()'. So, 'dist.exclude(foo={"bar":"baz"})' will try to call 'dist._exclude_foo({"bar":"baz"})', which can then handle whatever special exclusion logic is needed.

def exclude_package(self, package): (source)

Remove packages, modules, and extensions in named package

def fetch_build_egg(self, req): (source)

Fetch an egg needed for building

def fetch_build_eggs(self, requires): (source)
overridden in setuptools.build_meta.Distribution

Resolve pre-setup requirements

def finalize_options(self): (source)

Allow plugins to apply arbitrary operations to the distribution. Each hook may optionally define a 'order' to influence the order of execution. Smaller numbers go first and the default is 0.

def get_cmdline_options(self): (source)

Return a '{cmd: {opt:val}}' map of all command-line options Option names are all long, but do not include the leading '--', and contain dashes rather than underscores. If the option doesn't take an argument (e.g. '--quiet'), the 'val' is 'None'. Note that options provided by config files are intentionally excluded.

def get_command_class(self, command): (source)

Pluggable version of get_command_class()

def get_command_list(self): (source)

Undocumented

def get_egg_cache_dir(self): (source)

Undocumented

def handle_display_options(self, option_order): (source)

If there were any non-global "display-only" options (--help-commands or the metadata display options) on the command line, display the requested info and return true; else return false.

def has_contents_for(self, package): (source)

Return true if 'exclude_package(package)' would do something

def include(self, **attrs): (source)

Add items to distribution that are named in keyword arguments For example, 'dist.include(py_modules=["x"])' would add 'x' to the distribution's 'py_modules' attribute, if it was not already there. Currently, this method only supports inclusion for attributes that are lists or tuples. If you need to add support for adding to other attributes in this or a subclass, you can add an '_include_X' method, where 'X' is the name of the attribute. The method will be called with the value passed to 'include()'. So, 'dist.include(foo={"bar":"baz"})' will try to call 'dist._include_foo({"bar":"baz"})', which can then handle whatever special inclusion logic is needed.

def iter_distribution_names(self): (source)

Yield all packages, modules, and extension names in distribution

def make_option_lowercase(self, opt, section): (source)

Undocumented

def parse_config_files(self, filenames=None, ignore_option_errors=False): (source)

Parses configuration files from various levels and loads configuration.

def patch_missing_pkg_info(self, attrs): (source)

Undocumented

def print_commands(self): (source)

Undocumented

def run_command(self, command): (source)

Undocumented

def warn_dash_deprecation(self, opt, section): (source)

Undocumented

dependency_links = (source)

Undocumented

dist_files: list = (source)

Undocumented

ext_modules = (source)

Undocumented

extras_require = (source)

Undocumented

global_options = (source)

Undocumented

install_requires = (source)

Undocumented

negative_opt = (source)

Undocumented

package_data: dict = (source)

Undocumented

packages = (source)

Undocumented

py_modules = (source)

Undocumented

set_defaults = (source)

Undocumented

setup_requires = (source)

Undocumented

src_root = (source)

Undocumented

@staticmethod
def _expand_patterns(patterns): (source)

>>> list(Distribution._expand_patterns(['LICENSE'])) ['LICENSE'] >>> list(Distribution._expand_patterns(['setup.cfg', 'LIC*'])) ['setup.cfg', 'LICENSE']

@staticmethod
def _normalize_version(version): (source)

Undocumented

@staticmethod
def _removed(ep): (source)

When removing an entry point, if metadata is loaded from an older version of Setuptools, that removed entry point will attempt to be loaded and will fail. See #2765 for more details.

@staticmethod
def _suffix_for(req): (source)

For a requirement, return the 'extras_require' suffix for that requirement.

@staticmethod
def _validate_version(version): (source)

Undocumented

def _clean_req(self, req): (source)

Given a Requirement, remove environment markers and return it.

def _convert_extras_requirements(self): (source)

Convert requirements in `extras_require` of the form `"extra": ["barbazquux; {marker}"]` to `"extra:{marker}": ["barbazquux"]`.

def _exclude_misc(self, name, value): (source)

Handle 'exclude()' for list/tuple attrs without a special handler

def _exclude_packages(self, packages): (source)

Undocumented

def _finalize_license_files(self): (source)

Compute names of all license files which should be included.

def _finalize_requires(self): (source)

Set `metadata.python_requires` and fix environment markers in `install_requires` and `extras_require`.

def _finalize_setup_keywords(self): (source)

Undocumented

def _get_project_config_files(self, filenames): (source)

Add default file and split between INI and TOML

def _include_misc(self, name, value): (source)

Handle 'include()' for list/tuple attrs without a special handler

def _move_install_requirements_markers(self): (source)

Move requirements in `install_requires` that are using environment markers `extras_require`.

def _parse_command_opts(self, parser, args): (source)

Undocumented

def _parse_config_files(self, filenames=None): (source)

Adapted from distutils.dist.Distribution.parse_config_files, this method provides the same functionality in subtly-improved ways.

def _set_command_options(self, command_obj, option_dict=None): (source)

Set the options for 'command_obj' from 'option_dict'. Basically this means copying elements of a dictionary ('option_dict') to attributes of an instance ('command'). 'command_obj' must be a Command instance. If 'option_dict' is not supplied, uses the standard option dictionary for this command (from 'self.command_options'). (Adopted from distutils.dist.Distribution._set_command_options)

def _set_metadata_defaults(self, attrs): (source)

Fill-in missing metadata fields not supported by distutils. Some fields may have been set by other tools (e.g. pbr). Those fields (vars(self.metadata)) take precedence to supplied attrs.

def _setuptools_commands(self): (source)

Undocumented

def _validate_metadata(self): (source)

Undocumented

_DISTUTILS_UNSUPPORTED_METADATA = (source)

Undocumented

Value
{'long_description_content_type': (lambda : None),
 'project_urls': dict,
 'provides_extras': ordered_set.OrderedSet,
 'license_file': (lambda : None),
 'license_files': (lambda : None)}
_orig_extras_require = (source)

Undocumented

_orig_install_requires = (source)

Undocumented

_patched_dist = (source)

Undocumented

_referenced_files: Set[str] = (source)

Undocumented

_tmp_extras_require = (source)

Undocumented