Metadata-Version: 2.0
Name: packit
Version: 0.3
Summary: UNKNOWN
Home-page: UNKNOWN
Author: UNKNOWN
Author-email: UNKNOWN
License: NCBI license
Platform: UNKNOWN
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.6
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Requires-Dist: setuptools (>=8)
Requires-Dist: wheel (>=0.24)
Requires-Dist: pbr (>=0.10.8,<0.11)

PacKit
======

Rationale
---------

Creating python packages is routine operation that involves a lot of
actions that could be automated. Although there are petty good tools
like `pbr`_ for that purpose, they miss some features and lack
flexibility by trying to enforce some strongly opinionated decisions
upon you.  PacKit tries to solve this by providing a simple,
convenient, and flexible way to create and build packages while aiming
for following goals:

- simple declarative way to configure your package through *setup.cfg*  following  `distutils2 setup.cfg syntax`_

- reasonable defaults

- open for extension

Overview
--------

PacKit is wrapper around `pbr`_ though it only uses it for interaction
with setuptools/distutils through simplified interface.  None of `pbr`_
functions are exposed but instead PacKit provides its own
interface.

Available facilities
^^^^^^^^^^^^^^^^^^^^

Here's a brief overview of currently implemented facilities and the
list will be extended as new ones will be added.

- **auto-version** - set package version depending on selected
  versioning strategy.

- **auto-description** - set package long description

- **auto-license** - include license file into distribution

- **auto-dependencies** - populate *install_requires* and
  *test_requires* from requirement files

- **auto-packages** - discover packages to include in distribution.

- **auto-extra-meta** - add useful options to the metadata config section

- **auto-package-data** - include all files tracked by *git* from
  package dirs only.

- **auto-tests** - make ``python setup.py test`` run tests with *tox*
  or *pytest* (depending on *tox.ini* presence).

On top of that PacKit forces easy_install to honor `PIP's fetch directives set through environment variables`_:

- find_links

- site_dirs

- index_url

- optimize

- site_dirs

- allow_hosts


Planned facilities
^^^^^^^^^^^^^^^^^^

- **auto-plate** - integration with `platter`_

- **auto-license** - fill out license information

- **auto-pep8** - produce style-check reports

- **auto-docs** - API docs generation

- **auto-coverage** (?) - produce coverage reports while running tests

If you don't see desired facilities or have cool features in mind feel
free to contact us and tell about your ideas.


Usage
-----

Create a *setup.py* in your project dir:
::

    from setuptools import setup

    setup(setup_requires='packit', packit=True)


That was the first and the last time you touched that file for your project.

Now let's create a *setup.cfg* that you will use in order to configure
your package:

::

    [metadata]
    name = cool-package


And... if you're not doing anything tricky in your package then that's
enough! And if you do, take a look at the section below.


Facilities
----------

Currently all available facilities are enabled by default. Though you
can easily turn them off by using *facilities* section in your
*setup.cfg*:

::

    [facilities]
    auto-version = 0
    auto-dependencies = f
    auto-packages = false
    auto-package-data = n
    auto-tests = no


If facility is explicitly disabled it won't be used even if
facility-specific configuration section is present.

Facility-specific defaults and configuration options described below.


auto-version
^^^^^^^^^^^^

When enabled, ``auto-version`` will generate and set package version
according to selected versioning strategy.

Versioning strategy can be selected using *type* field under
*auto-version* section within *setup.cfg*.  The default is:

::

    [auto-version]
    type = git-pep440

git-pep440
""""""""""

Generate `PEP440`_-compliant version from *git* tags. It's expected
that you using git tags that follow `public version identifier`_
description and *git-pep440* will just append number of commits since
tag was applied to your tag value (the *N* in `public version
identifier`_ description).

If number of commits since tag equal to 0 (your building the tagged
version) the *N* value won't be appended. Otherwise, it will be
appended and `local version identifier`_ equal to first 7 chars of
commit hash will be also added.

Example:
1. <git tag 1.2.3.dev> -> version is *1.2.3.dev*

2. <git commit> -> version is *1.2.3.dev.post1*

3. <git commit> -> version is *1.2.3.dev.post2*

4. <git tag 1.2.3.a> -> version is *1.2.3.a*

5. <git commit> -> version is *1.2.3.a.post1*

6. <git tag 1.2.3> -> version is *1.2.3*

7. <git commit> -> version is *1.2.3.post1*

8. <git commit> -> version is *1.2.3.post2*

fixed
"""""

Use value specified in *value* (it's required when this strategy is
used) under *auto-version* section in *setup.cfg*:

::

    [auto-version]
    type = fixed
    value = 3.3

file
""""

Read a line using UTF-8 encoding from the file specified in *value*
(it's required when this strategy is used) under *auto-version*
section in *setup.cfg*, strip it and use as a version.

::

    [auto-version]
    type = file
    value = VERSION.txt

shell
"""""

Execute command specified in *value* (it's required when this strategy
is used) under *auto-version* section in *setup.cfg*, read a line from
*stdout*, strip it and use as a version

auto-description
^^^^^^^^^^^^^^^^

When enabled will fill out *long_description* for package from a readme.

The *readme* file name could be specified with *file* field under
*auto-description* section.

If no file name provided, it will be discovered automatically by
trying following list of files:

- README

- readme

- CHANGELOG

- changelog

Each of these files will be tried with following extensions:

- <without extension>

- .md

- .markdown

- .mkdn

- .text

- .rst

- .txt

The readme file will be included in the package data.

auto-license
^^^^^^^^^^^^

When enabled will include the license file into the distribution.

The license file name could be specified by the *file* field within *auto-license* section.

If license file name is not provided the facility will try to discover it in the current dir
trying following file names:

- LICENSE

- license

Each of these files will be tried with following extensions:

- <without extension>

- .md

- .markdown

- .mkdn

- .text

- .rst

- .txt

auto-dependencies
^^^^^^^^^^^^^^^^^

When enabled will fill *install_requires* and *test_requires* from requirement
files.

Requirement files could be specified by *install* and *test* fields under the
*auto-dependencies* section of the *setup.cfg*.

If requirements file names not provided then the facility will try to discover them automatically.

For installation requirements following paths will be tried:

- requires
- requirements
- requirements/prod
- requirements/release
- requirements/install
- requirements/main
- requirements/base

For testing requirements following paths will be tried:

- test-requires
- test_requires
- test-requirements
- test_requirements
- requirements_test
- requirements-test
- requirements/test

For each path following extensions will be tried

- <without extension>
- .pip
- .txt

Once a file is found, PacKit stops looking for more files.

**You can use vcs project urls and/or archive urls/paths** as
described in `pip usage`_ - they will be split in dependency links and
package names during package creation and will be properly handled by
pip/easyinstall during installation.  Remember that you can also make
"includes" relationships between ``requirements.txt`` files by
including a line like ``-r other-requires-file.txt``.

auto-packages
^^^^^^^^^^^^^

When enabled and no packages provided in *setup.cfg* through
*packages* option under *files* section will try to automatically find
out all packages in current dir recursively.

It operates using *exclude* and *include* values that can be specified
under *auto-packages* section within *setup.cfg*.

If *exclude* not provided the following defaults will be used:
*test**, *docs*, *.tox* and *env*.

If *include* not provided, *auto-packages* will try the following
steps in order to generate it:

1. If *packages_root* value provided under *files* section in
   *setup.cfg*, it will be used.

2. Otherwise the current working dir will be scanned for any python
   packages (dirs with __init__.py) while honoring exclude
   *value*. *This packages also will be included into the resulting
   list of packages.*

Once *include* value is determined, the resulting packages list will
be generated using following algorithm:

::

  for path in include:
      found_packages = set(find_packages(path, exclude))


auto-extra-meta
^^^^^^^^^^^^^^^

When enabled, adds a number of additional options to 'metadata' section.

Right now, only 1 extra option supported:

- **is_pure** - allows you to override 'purity' flag for distribution, i.e.
  you can explicitly say whether your distribution is platform-specific or no.


auto-package-data
^^^^^^^^^^^^^^^^^

When enabled:

1. If the *everything* option under the *auto-package-data* section is
    set to true, behaves like `setuptools-git`_. Otherwise, includes all
    files only from packages' dirs tracked by git to distribution.

2. Allows you to specify extra files to be included in distribution in
   *setup.cfg* using *extra_files* under *files* section like:

::

  [files]
  extra_files =
    LICENSE.txt
    hints.txt
    some/stuff/lib.so

auto-tests
^^^^^^^^^^

Has no additional configuration options [yet].

When enabled, the *python setup.py test* is equal to running:

- **tox** if *tox.ini* is present

- **pytest** with `pytest-gitignore`_ and `teamcity-messages`_ plugins
  enabled otherwise

Further Development
-------------------

- Add tests
- Improve docs
- More configuration options for existing facilities
- New facilities
- Allow extension through entry points


.. _pbr: http://docs.openstack.org/developer/pbr/
.. _distutils2 setup.cfg syntax: http://alexis.notmyidea.org/distutils2/setupcfg.html
.. _PIP's fetch directives set through environment variables: https://pip.pypa.io/en/latest/user_guide.html#environment-variables
.. _platter: http://platter.pocoo.org/
.. _setuptools-git: https://pypi.python.org/pypi/setuptools-git
.. _pytest-gitignore: https://pypi.python.org/pypi/pytest-gitignore/
.. _teamcity-messages: https://pypi.python.org/pypi/teamcity-messages/
.. _pip usage: https://pip.pypa.io/en/latest/reference/pip_install.html#usage
.. _PEP440: https://www.python.org/dev/peps/pep-0440/
.. _public version identifier: https://www.python.org/dev/peps/pep-0440/#public-version-identifiers
.. _local version identifier: https://www.python.org/dev/peps/pep-0440/#local-version-identifiers


