From 0254a2fda8e8bd4f289d01e2179191e936517f04 Mon Sep 17 00:00:00 2001 From: Carsten Klein Date: Fri, 17 Aug 2018 14:58:35 +0200 Subject: Rename find_namepaces_ns to find_namespace_packages (#1423) * fix #1419 PEP420: add find_namespace: directive * fix #1419 PEP420: add find_namespace: directive to documentation * fix #1419 PEP420: add tests * fix #1419 PEP420: clean up code * fix #1419 PEP420: fix typo in documentation * fix #1419 PEP420: fix typo in documentation * fix #1419 PEP420: clean up code * fix #1419 PEP420: add changelog entry * fixup! fix #1419 PEP420: add tests * fix #1419 PEP420: cleanup code refactor markers * #1420: Rename find_namespace_ns to find_namespace_packages * #1420: update changelog entry --- docs/setuptools.txt | 35 +++++++++++++++++++---------------- 1 file changed, 19 insertions(+), 16 deletions(-) (limited to 'docs/setuptools.txt') diff --git a/docs/setuptools.txt b/docs/setuptools.txt index 0660e14d..89f45bd8 100644 --- a/docs/setuptools.txt +++ b/docs/setuptools.txt @@ -57,7 +57,7 @@ Feature Highlights: * Create extensible applications and frameworks that automatically discover extensions, using simple "entry points" declared in a project's setup script. -* Full support for PEP 420 via ``find_packages_ns()``, which is also backwards +* Full support for PEP 420 via ``find_namespace_packages()``, which is also backwards compatible to the existing ``find_packages()`` for Python >= 3.3. .. contents:: **Table of Contents** @@ -462,18 +462,18 @@ argument in your setup script. Especially since it frees you from having to remember to modify your setup script whenever your project grows additional top-level packages or subpackages. -``find_packages_ns()`` ----------------------- -In Python 3.3+, ``setuptools`` also provides the ``find_packages_ns`` variant +``find_namespace_packages()`` +----------------------------- +In Python 3.3+, ``setuptools`` also provides the ``find_namespace_packages`` variant of ``find_packages``, which has the same function signature as ``find_packages``, but works with `PEP 420`_ compliant implicit namespace -packages. Here is a minimal setup script using ``find_packages_ns``:: +packages. Here is a minimal setup script using ``find_namespace_packages``:: - from setuptools import setup, find_packages_ns + from setuptools import setup, find_namespace_packages setup( name="HelloWorld", version="0.1", - packages=find_packages_ns(), + packages=find_namespace_packages(), ) @@ -490,16 +490,16 @@ namespace package is quite lenient, so for a project organized like so:: └── tests └── test_mod1.py -A naive ``find_packages_ns()`` would install both ``namespace.mypackage`` and a +A naive ``find_namespace_packages()`` would install both ``namespace.mypackage`` and a top-level package called ``tests``! One way to avoid this problem is to use the ``include`` keyword to whitelist the packages to include, like so:: - from setuptools import setup, find_packages_ns + from setuptools import setup, find_namespace_packages setup( name="namespace.mypackage", version="0.1", - packages=find_packages_ns(include=['namespace.*']) + packages=find_namespace_packages(include=['namespace.*']) ) Another option is to use the "src" layout, where all package code is placed in @@ -520,7 +520,7 @@ With this layout, the package directory is specified as ``src``, as such:: setup(name="namespace.mypackage", version="0.1", package_dir={'': 'src'}, - packages=find_packages_ns(where='src')) + packages=find_namespace_packages(where='src')) .. _PEP 420: https://www.python.org/dev/peps/pep-0420/ @@ -2389,8 +2389,8 @@ Metadata and options are set in the config sections of the same name. * In some cases, complex values can be provided in dedicated subsections for clarity. -* Some keys allow ``file:``, ``attr:``, and ``find:`` directives in order to - cover common usecases. +* Some keys allow ``file:``, ``attr:``, and ``find:`` and ``find_namespace:`` directives in + order to cover common usecases. * Unknown keys are ignored. @@ -2479,7 +2479,7 @@ eager_resources list-comma dependency_links list-comma tests_require list-semi include_package_data bool -packages find:, list-comma +packages find:, find_namespace:, list-comma package_dir dict package_data section exclude_package_data section @@ -2489,10 +2489,13 @@ py_modules list-comma .. note:: - **packages** - The ``find:`` directive can be further configured + **packages** - The ``find:`` and ``find_namespace:`` directive can be further configured in a dedicated subsection ``options.packages.find``. This subsection - accepts the same keys as the `setuptools.find` function: + accepts the same keys as the `setuptools.find_packages` and the + `setuptools.find_namespace_packages` function: ``where``, ``include``, and ``exclude``. + + **find_namespace directive** - The ``find_namespace:`` directive is supported since Python >=3.3. Configuration API -- cgit v1.2.3