Skip to main content

quicklib: hassle-free setup scripts for your python libraries

Project description

Build hassle-free setup scripts for your python libraries, with practical versioning, requirements specification, and more (to come).

Installation

Install using:

pip install quicklib

Or clone this project’s repo and run:

python setup.py install

Creating libraries

TL;DR - run python -m quicklib.bootstrap in a new folder and answer some questions, and you’re good to go coding. Look at examplelibrary for an example created with this bootstrap process.

Also, your library needs to be in a git-managed folder, and needs at least one numeric major.minor tag in your current history.

If you have no version tags yet, create the first one now and push it:

git tag -a 0.1 -m "first version tag: 0.1"
git push origin 0.1

File structure

The recommended library file structure is something like:

mylibrary/
  |-- setup.py
  |-- README.md
  |-- [requirements.txt]
  mypackage/
    |-- __init__.py
    |-- version.py
    |-- module1.py
    |-- module2.py
    |-- subpackage/
      |-- __init__.py
      |-- module3.py

If you want to include more than one top-level package in your library, place additional ones next to mypackage.

For a deeper dive into recommended structure and other possible options, check out Structuring Your Project at the Hitchhiker’s Guide to Python.

Setup script

For an example setup.py file see examplelibrary’s setup.py.

The setup script must include this fixed stub copy-pasted verbatim:

# -------- quicklib direct/bundled import, copy pasted --------------------------------------------
import sys as _sys, glob as _glob, os as _os
is_packaging = not _os.path.exists("PKG-INFO")
if is_packaging:
    import quicklib
else:
    zips = _glob.glob("quicklib_incorporated.*.zip")
    if len(zips) != 1:
        raise Exception("expected exactly one incorporated quicklib zip but found %s" % (zips,))
    _sys.path.insert(0, zips[0]); import quicklib; _sys.path.pop(0)
# -------------------------------------------------------------------------------------------------

After that, where you would usually call setuptools.setup(...), call quicklib.setup(...) instead:

quicklib.setup(
    name='examplelibrary',
    url="https://example.com/",
    author='ACME Inc.',
    author_email='user@example.com',
    description='examplelibrary: a library to demonstrate how quicklib is used to quickly setup python libraries',
    license='Copyright ACME Inc.',
    platforms='any',
    classifiers=[
        'Programming Language :: Python',
        'Development Status :: 4 - Beta',
        'Natural Language :: English',
        'Intended Audience :: Developers',
        'Operating System :: OS Independent',
        'Topic :: Software Development :: Libraries :: Python Modules',
    ],
    version_module_paths=[
        os.path.join(os.path.dirname(__file__), "examplepackage", "version.py"),
    ],
)

Most parameters are exactly the same as they are in setuptools.

Additional parameters:

  • version_module_paths - see details in “Versioning” below

Modified parameter defaults:

  • if packages is not given, find_packages() is used automatically to discover packages under your library’s top directory.

Setup script in non-standard location

It is possible to build libraries with quicklib from setup scripts other than “top level setup.py”. This allows building more than one library (or variants of a single library) from a single repository.

Look at examplelibrary2 for two such example library variants built from the same sources.

Just place your setup code in any folder and run it the same way as usual, e.g.:

python my_other_setup.py sdist bdist_wheel

Note that if you want to have a MANIFEST.in file to go with the script, you can put it alongside it and using the same base name, e.g.:

...
|-- my_other_setup.py
|-- my_other_setup.MANIFEST.in
...

If no such alternative MANIFEST.in file is present and a top-level MANIFEST.in exists, it will be used as usual.

Versioning

The build process automatically sets your library version based on the git log and tags. This version information is applied to the built library and can later be programmatically queried by library package users.

version value inference

  1. It git-describes the HEAD searching for the latest annotated (!) tag with a major.minor label

  2. If the tag is placed directly on the current HEAD then this is the version label

    • otherwise, a .micro suffix is added denoting the number of commits between the tag and HEAD

  3. Finally, if there are any local modifications, a .dirty suffix is added

adding version info to your packages

Add a version.py stub file under any of your top-level packages with this fixed template:

# quicklib version boilerplate
DEV_VERSION = "0.0.0.dev0"
__version__ = DEV_VERSION

In addition, tell setup.py where to find those files:

quicklib.setup(
    version_module_paths=[
        os.path.join(os.path.dirname(__file__), "mypackage", "version.py"),
        # ...
        # ... you can specify more than one
        # ...
    ],
)

Then, your users can programmatically query this version value by running e.g.:

import mypackage
print mypackage.version.__version__

versioning multiple packages

If your library contains multiple top-level packages, a version.py file should usually be added under each of them. This allows your library users to ask about the version of each of your individual packages while being agnostic to the fact that they come from the same library. If you find this confusing, you may want to stick to one top-level package per library.

Requirements

To add requirements to your library, add them in a requirements.txt file at the project root.

Use syntax such as:

numpy
pandas==0.18.1
yarg~=0.1.1

Freezing requirements

Sometimes you want to hardcode the versions of your dependencies. This helps provide your users the exact same configuration you built and tested with. To avoid having to manually update those numbers, you can keep your requirements specified as usual but activate “requirement freezing”.

Do this by passing freeze_requirements=True to the quicklib.setup(...) call in setup.py.

Note: if your library depends on a hardcoded dep==1.0 but dep did not hardcode its dependencies, your users might get different packages. To get around that you can specify your requirements’ requirements as your own requirements. Automatically fetching this information is on this library’s roadmap.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quicklib-0.2.tar.gz (34.3 kB view hashes)

Uploaded Source

Built Distribution

quicklib-0.2-py2-none-any.whl (38.1 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page