pkutils 3.0.2

Description:

pkutils 3.0.2

Index
Introduction | Requirements | Motivation | Usage | Installation |
Project Structure | Design Principles | Scripts | Contributing | License


Introduction
pkutils is a Python library that simplifies python module packaging. It is
intended to be used in your package’s setup.py file.
With pkutils, you can

Parse requirements files
Determine your project’s development status
Read text files
and much more…



Requirements
pkutils has been tested and is known to work on Python 3.7, 3.8, and 3.9; and PyPy3.7.


Motivation
Python has a great packaging system, but to actually create and publish a
package requires a lot of work to do well. I designed pkutils to provide
many useful packaging use-cases out of the box. For example, to automatically
include the contents of your requirements.txt file, simply add the following
to setup.py:
import pkutils

...

requirements = list(pkutils.parse_requirements('requirements.txt'))
dev_requirements = list(pkutils.parse_requirements('dev-requirements.txt'))

setup(
...
install_requires=requirements,
tests_require=dev_requirements,
...)


Usage
pkutils is intended to be used directly as a Python library.
my_package/__init__.py
__version__ = '0.5.4'

__author__ = 'Reuben Cummings'
__description__ = 'My super awesome great package'
__email__ = '[email protected]'
__license__ = 'MIT'
__copyright__ = 'Copyright 2015 Reuben Cummings'
You can set __title__ explicitly in your Python file. If you leave
__title__ unset, pkutils will use:

The parent directory for paths ending in __init__.py.
The filename before the extention for other paths
(e.g. my_package for my_package.py).

setup.py
import pkutils

try:
from setuptools import setup
except ImportError:
from distutils.core import setup

requirements = list(pkutils.parse_requirements('requirements.txt'))
dependencies = list(pkutils.parse_requirements('requirements.txt', True))
dev_requirements = list(pkutils.parse_requirements('dev-requirements.txt'))
readme = pkutils.read('README.rst')
module = pkutils.parse_module('my_package/__init__.py')
version = module.__version__
project = module.__title__
email = module.__email__
user = pkutils.get_user(email)

setup(
name=project,
version=version,
description=module.__description__,
long_description=readme,
author=module.__author__,
author_email=email,
install_requires=requirements,
tests_require=dev_requirements,
dependency_links=dependencies,
setup_requires=['pkutils'],
url=pkutils.get_url(project, user),
download_url=pkutils.get_dl_url(project, user, version),
classifiers=[
pkutils.get_license(module.__license__),
pkutils.get_status(version),
...
],
...
)
This is then converted into something like the following:
...

setup(
name='my_package',
version='0.5.4',
description='My super awesome great package',
long_description='my_package: a super awesome great...',
author='Reuben Cummings',
author_email='[email protected]',
install_requires=['semver==2.2.1'],
tests_require=['semver==2.2.1', 'wheel==0.24.0', 'flake8==2.5.1', ...],
dependency_links=[],
setup_requires=['pkutils'],
url='https://github.com/reubano/pkutils',
download_url='https://github.com/reubano/pkutils/archive/v0.5.4.tar.gz',
classifiers=[
'License :: OSI Approved :: MIT License',
'Development Status :: 4 - Beta',
...
],
...
)


Installation
(You are using a virtualenv, right?)
At the command line, install pkutils using either pip (recommended)
pip install -u pkutils
or easy_install
easy_install pkutils
Please see the installation doc for more details.


Project Structure
┌── CHANGES.rst
├── CONTRIBUTING.rst
├── LICENSE
├── MANIFEST.in
├── Makefile
├── README.md
├── dev-requirements.txt
├── helpers
│   ├── check-stage
│   ├── clean
│   ├── srcdist
│   ├── test
│   └── wheel
├── manage.py
├── pkutils.py
├── requirements.txt
├── setup.cfg
├── setup.py
├── tests
│   ├── __init__.py
│   └── standard.rc
└── tox.ini


Design Principles

minimize external dependencies
prefer functions over objects
keep the API as simple as possible



Scripts
pkutils comes with a built in task manager manage.py

Setup
pip install -r dev-requirements.txt


Examples
View available commands
manage
Show help for a given command
manage <command> -h
Run python linter and nose tests
manage lint
manage test
Or if make is more your speed…
make lint
make test



Contributing
Please mimic the coding style/conventions used in this repo.
If you add new classes or functions, please add the appropriate doc blocks with
examples. Also, make sure the python linter and nose tests pass.
Please see the contributing doc for more details.


License
pkutils is distributed under the MIT License.