2. Tutorial¶

2.1. Linking setuptools with package version numbers¶

The following example shows how to link a package number stored in package/_version.py with setuptools:

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import subprocess
    import sys
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "pkg_utils"])
    import pkg_utils

# package name
name = 'my_package'
dirname = os.path.dirname(__file__)

# get package metadata
md = pkg_utils.get_package_metadata(dirname, name)

# install package
setuptools.setup(
    ...
    version=md.version,
)

2.2. Linking setuptools with GitHub README.md files¶

The following example shows how to link GutHub Markdown-formatted README.md files with setuptools which requires long descriptions in reStructuredText format. Note, this feature requires the pandoc option.

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import subprocess
    import sys
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "pkg_utils"])
    import pkg_utils

# package name
name = 'my_package'
dirname = os.path.dirname(__file__)

# convert README.md to README.rst
pkg_utils.convert_readme_md_to_rst(dirname)

# get package metadata
md = pkg_utils.get_package_metadata(dirname, name)

# install package
setuptools.setup(
    ...
    long_description=md.long_description,
)

2.3. Linking setuptools with requirements¶

The following example illustrates how to link setuptools with requirements.txt files:

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import subprocess
    import sys
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "pkg_utils"])
    import pkg_utils

# package name
name = 'my_package'
dirname = os.path.dirname(__file__)

# get package metadata
md = pkg_utils.get_package_metadata(dirname, name)

# install package
setuptools.setup(
    ...
    install_requires=md.install_requires,
    extras_require=md.extras_require,
    tests_require=md.tests_require,
    dependency_links=md.dependency_links,
)

This extracts dependencies from the following files:

requirements.txt: dependencies
requirements.optional.txt: optional dependencies
tests/requirement.txt: dependencies to run the tests
docs/requirement.txt: dependencies to build the docummentation

The requirements.txt files should follow the pip format:

package_1
package_2[package_2_option_2] >= 1.0.0; python_version >= "2.7.14"

The requirements.optional.txt should follow the same format, but with section headings to indicate the options:

[my_option_1]
package_1
package_2[package_2_option_2] >= 1.0.0; python_version >= "2.7.14"

[my_option_2]
package_3
package_4

In addition to the installation options described in requirements.optional.txt, pkg_utils will create tests, docs and all options to install the test, documentation, and all dependencies.

2.4. Restoring overridden console scripts during editable installations¶

The following example illustrates how to restore overridden console scripts during editable installations. This useful for generating console scripts for specific versions of Python.

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import subprocess
    import sys
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "pkg_utils"])
    import pkg_utils

# package name
name = 'my_package'
dirname = os.path.dirname(__file__)

# read old console scripts
console_scripts = pkg_utils.get_console_scripts(dirname, name)

# install package
setuptools.setup(...)

# restore old console scripts
pkg_utils.add_console_scripts(dirname, name, console_scripts)

2.5. Putting it all together¶

The following example shows how to use all of the features of this package:

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import subprocess
    import sys
    subprocess.check_call(
        [sys.executable, "-m", "pip", "install", "pkg_utils"])
    import pkg_utils

# package name
name = 'my_package'
dirname = os.path.dirname(__file__)

# get package metadata
md = pkg_utils.get_package_metadata(dirname, name)

# read old console scripts
console_scripts = pkg_utils.get_console_scripts(dirname, name)

# install package
setuptools.setup(
    ...
    version=md.version,
    long_description=md.long_description,
    install_requires=md.install_requires,
    extras_require=md.extras_require,
    tests_require=md.tests_require,
    dependency_links=md.dependency_links,
)

# restore old console scripts
pkg_utils.add_console_scripts(dirname, name, console_scripts)