diff options
Diffstat (limited to 'docs/userguide/quickstart.txt')
| -rw-r--r-- | docs/userguide/quickstart.txt | 131 |
1 files changed, 131 insertions, 0 deletions
diff --git a/docs/userguide/quickstart.txt b/docs/userguide/quickstart.txt index 535227a0..4a851ee3 100644 --- a/docs/userguide/quickstart.txt +++ b/docs/userguide/quickstart.txt @@ -74,6 +74,137 @@ dependencies, and perhaps some data files and scripts:: # could also include long_description, download_url, etc. ) +Automatic package discovery +=========================== +For simple projects, it's usually easy enough to manually add packages to +the ``packages`` argument of ``setup()``. However, for very large projects +, it can be a big burden to keep the package list updated. setuptools therefore +provides tools to ease the burden. + +``find_packages()`` takes a source directory and two lists of package name +patterns to exclude and include. It then walks the target directory, filtering +by inclusion patterns, and return a list of Python packages (any directory). +Finally, exclusion patterns are applied to remove matching packages. + +For example:: + #... + from setuptools import find_packages() + + setup( + #..., + packages = find_packages() + ) + +For more details and advanced use, go to :ref:`package_discovery` + +Entry points and automatic script creation +=========================================== + +Setuptools support automatic creation of scripts upon installation, that runs +code within your package if you specify them with the ``entry_point`` keyword. +This is what allows you to run commands like ``pip install`` instead of having +to type ``python -m pip install``. To accomplish this, consider the following +example:: + + setup( + #.... + entry_points={ + "console_scripts": [ + "foo = my_package.some_module:main_func", + ], + } + ) + +When this project is installed, a ``foo`` script will be installed and will +invoke the ``main_func`` when called by the user. For detailed usage, including +managing the additional or optional dependencies, go to :ref:`entry_point`. + +Dependency management +===================== + +``setuptools`` supports automatically installing dependencies when a package is +installed. The simplest way to include requirement specifiers is to use the +``install_requires`` argument to ``setup()``. It takes a string or list of +strings containing requirement specifiers:: + + setup( + #... + install_requires = "docutils >= 0.3" + ) + +When your project is installed, either by using pip, ``setup.py install``, +or ``setup.py develop``, all of the dependencies not already installed will +be located (via PyPI), downloaded, built (if necessary), and installed. + +For more advanced use, see :ref:`dependencies` + +Including Data Files +==================== + +The distutils have traditionally allowed installation of "data files", which +are placed in a platform-specific location. Setuptools offers three ways to +specify data files to be included in your packages. For the simpliest use, you +can simply use the ``include_package_data`` keyword e.g.:: + + setup( + ... + include_package_data=True + ) + +This tells setuptools to install any data files it finds in your packages. +The data files must be specified via the distutils' ``MANIFEST.in`` file. + +For more details, see :ref:`datafiles` + +Development mode +================ + +Setuptools allows you to deploy your projects for use in a common directory or +staging area, but without copying any files. Thus, you can edit each project's +code in its checkout directory, and only need to run build commands when you +change a project's C extensions or similarly compiled files. + +To do this, use the ``setup.py develop`` command. It works very similarly to +``setup.py install``, except that it doesn't actually install anything. +Instead, it creates a special ``.egg-link`` file in the deployment directory, +that links to your project's source code. And, if your deployment directory is +Python's ``site-packages`` directory, it will also update the +``easy-install.pth`` file to include your project's source code, thereby making +it available on ``sys.path`` for all programs using that Python installation. + +for more information, go to :ref:`development_mode` + +Distributing a ``setuptools``-based project +=========================================== +Before you begin, make sure you have the latest versions of setuptools and wheel:: + + pip install --upgrade setuptools wheel + +To build a setuptools project, run this command from the same directory where +setup.py is located:: + + setup.py sdist bdist_wheel + +This will generate distribution archives in the `dist` directory. + +Before you upload the generated archives make sure you're registered on +https://test.pypi.org/account/register/. You will also need to verify your email +to be able to upload any packages. +You should install twine to be able to upload packages:: + + pip install --upgrade twine + +Now, to upload these archives, run:: + + twine upload --repository-url https://test.pypi.org/legacy/ dist/* + +To install your newly uploaded package ``example_pkg``, you can use pip:: + + pip install --index-url https://test.pypi.org/simple/ example_pkg + +The next following sections will walk you through all of the available functions +``setuptools`` offers in excrutiating details (including those already mentioned) +for more advanced use. |