Installing ``setuptools``
=========================

.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/

To install the latest version of setuptools, use::

    pip install --upgrade setuptools

Refer to `Installing Packages`_ guide for more information.

Basic Use
=========

For basic use of setuptools, just import things from setuptools instead of
the distutils.  Here's a minimal setup script using setuptools::

    from setuptools import setup, find_packages
    setup(
        name="HelloWorld",
        version="0.1",
        packages=find_packages(),
    )

As you can see, it doesn't take much to use setuptools in a project.
Run that script in your project folder, alongside the Python packages
you have developed.

Invoke that script to produce distributions and automatically include all
packages in the directory where the setup.py lives.  See the `Command
Reference`_ section below to see what commands you can give to this setup
script. For example, to produce a source distribution, simply invoke::

    setup.py sdist

Of course, before you release your project to PyPI, you'll want to add a bit
more information to your setup script to help people find or learn about your
project.  And maybe your project will have grown by then to include a few
dependencies, and perhaps some data files and scripts::

    from setuptools import setup, find_packages
    setup(
        name="HelloWorld",
        version="0.1",
        packages=find_packages(),
        scripts=["say_hello.py"],

        # Project uses reStructuredText, so ensure that the docutils get
        # installed or upgraded on the target machine
        install_requires=["docutils>=0.3"],

        package_data={
            # If any package contains *.txt or *.rst files, include them:
            "": ["*.txt", "*.rst"],
            # And include any *.msg files found in the "hello" package, too:
            "hello": ["*.msg"],
        },

        # metadata to display on PyPI
        author="Me",
        author_email="me@example.com",
        description="This is an Example Package",
        keywords="hello world example examples",
        url="http://example.com/HelloWorld/",   # project home page, if any
        project_urls={
            "Bug Tracker": "https://bugs.example.com/HelloWorld/",
            "Documentation": "https://docs.example.com/HelloWorld/",
            "Source Code": "https://code.example.com/HelloWorld/",
        },
        classifiers=[
            "License :: OSI Approved :: Python Software Foundation License"
        ]

        # could also include long_description, download_url, etc.
    )