pkg_utils documentation

Utilities for linking setuptools with package version metadata, GitHub README.md files, requirements.txt files, and restoring overridden entry points during for editable installations.

Contents

Installation

Requirements

First, install Python and pip. The following command illustrates how to install Python and pip on Ubuntu Linux:

apt-get install python python-pip

Optional requirements

Second, optionally install pandoc to convert Markdown-formatted README files for GitHub into reStructuredText-formatted files for PyPI:

apt-get install pandoc

Installing this package

Use the following command to install this package from PyPI:

pip install pkg_utils

The latest version of this package can be installed from GitHub using this command:

pip install git+https://github.com/KarrLab/pkg_utils.git#egg=pkg_utils

Support for the pandoc can be installed using the following option:

pip install pkg_utils[pandoc]
pip install git+https://github.com/KarrLab/pkg_utils.git#egg=pkg_utils[pandoc]

Tutorial

Linking setuptools with package version numbers

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

import os
import setuptools
try:
    import pkg_utils
except ImportError:
    import pip
    pip.main(['install', 'git+https://github.com/KarrLab/pkg_utils.git#egg=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,
)

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 pip
    pip.main(['install', 'git+https://github.com/KarrLab/pkg_utils.git#egg=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,
)

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 pip
    pip.main(['install', 'git+https://github.com/KarrLab/pkg_utils.git#egg=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.

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 pip
    pip.main(['install', 'git+https://github.com/KarrLab/pkg_utils.git#egg=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)

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 pip
    pip.main(['install', 'git+https://github.com/KarrLab/pkg_utils.git#egg=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)

Testing

The package can be tested by running these commands:

pip install pytest
python -m pytest tests

pkg_utils package

Submodules

pkg_utils.core module

Utilities for linking setuptools with package version metadata, GitHub README.md files, requirements.txt files, and restoring overridden entry points during for editable installations.

Author:Jonathan Karr <jonrkarr@gmail.com> Date:2017-12-03 Copyright:2017, Karr Lab License:MIT

class pkg_utils.core.PackageMetadata

Bases: object

Metadata about a package

name

str

description

str – short description

long_description

str – long description, e.g. from README.rst

version

str – version, e.g. from package/VERSION

install_requires

list of str – dependencies, e.g. from requirements.txt

extras_require

dict of list of str – optional dependencies, e.g. from requirements.optional.txt

tests_require

list of str – test dependencies, e.g. from tests/requirements.txt

dependency_links

list of str – documentation dependencies, e.g. from docs/requirements.txt

pkg_utils.core.add_console_scripts(dirname, package_name, console_scripts)

Add console scripts for a package

Parameters:

• dirname (str) – path to the package
• package_name (str) – package name
• console_scripts (dict) – console script names and locations

pkg_utils.core.convert_readme_md_to_rst(dirname)

Convert the README.md to README.rst

Parameters:dirname (str) – path to the package

pkg_utils.core.get_console_scripts(dirname, package_name)

Get the console scripts for a package

Parameters:

• dirname (str) – path to the package
• package_name (str) – package name

Returns:

console script names and locations

Return type:

dict

pkg_utils.core.get_long_description(dirname)

Get the long description of a package from its README.rst file

Parameters:dirname (str) – path to the package Returns:long description Return type:str

pkg_utils.core.get_package_metadata(dirname, package_name)

Get meta data about a package

Parameters:

• dirname (str) – path to the package
• package_name (str) – package name

Returns:

meta data

Return type:

PackageMetadata

Raises:

Exception: if test or documentation dependencies are defined in requirements.optional.txt

pkg_utils.core.get_version(dirname, package_name)

Get the version a package from its VERSION file (package/VERSION)

Parameters:

• dirname (str) – path to the package
• package_name (str) – package name

Returns:

version

Return type:

str

pkg_utils.core.install_dependencies(dependencies, upgrade=False)

Install dependencies

Parameters:

• dependencies (list) – list of dependencies
• upgrade (bool, optional) – if True, upgrade package

pkg_utils.core.parse_optional_requirements_file(filename)

Parse a requirements.optional.txt file into list of requirements and dependency links

Parameters:filename (str) – path to requirements.txt file Returns:requirements list of str: dependency links Return type:dict of list of str Raises:Exception – if a line cannot be parsed

pkg_utils.core.parse_requirement_lines(lines)

Parse lines from a requirements.txt file into list of requirements and dependency links

Parameters:lines (list of str) – lines from a requirements.txt file Returns:requirements list of str of str: dependency links Return type:list of str Raises:Exception – if a line cannot be parse

pkg_utils.core.parse_requirements_file(filename)

Parse a requirements.txt file into list of requirements and dependency links

Parameters:filename (str) – path to requirements.txt file Returns:requirements list of str: dependency links Return type:list of str

Module contents

About

License

The software is released under the MIT license

The MIT License (MIT)

Copyright (c) 2017 Karr Lab

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Development team

This package was developed by the Karr Lab at the Icahn School of Medicine at Mount Sinai in New York, USA.

Questions and comments

Please contact the Karr Lab with any questions or comments.