quicklib
========
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
| | OR
| --- quicklib_setup.yml
|-- 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:
.. code:: Python
# -------- 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:
.. code:: Python
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=[
"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.
YAML-based setup
~~~~~~~~~~~~~~~~
The easiest way for simple libraries is to provide all necessary details
in a YAML file. This is essentially the same as creating a setup.py that
uses the YAML dictionary as its kwargs.
For example, create a ``quicklib_setup.yml`` file at the root of your
project:
::
setup:
name: mylibrary
description: a library for doing some stuff
version: 1.0
And run ``quicklib-setup sdist`` (instead of ``python setup.py sdist``)
to create the library package.
You can also ``include`` additional files of a similar format (overriding each other in order of appearance), e.g. to use as common template of values:
::
# mylib_setup.yml
include:
- ../common_properties.yml
setup:
name: mylibrary
# common_properties.yml
setup:
author: ACME Inc.
author_email: user@example.com
For additional parameters, see the rest of this documentation and
provide parameters to ``quicklib.setup(...)`` as values under the
``setup`` dictionary in your ``quicklib_setup.yml`` file.
Take a look at the `minimal example library`_ for usage example.
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-describe``\ s 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:
.. code:: Python
# quicklib version boilerplate
DEV_VERSION = "0.0.0.dev0"
__version__ = DEV_VERSION
In addition, tell ``setup.py`` where to find those files:
.. code:: Python
quicklib.setup(
version_module_paths=[
"mypackage/version.py",
# ... you can specify more than one
],
)
Then, your users can programmatically query this version value by running
e.g.:
.. code:: Python
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.
Choosing packages to include
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The default behavior calls ``setuptools.find_packages()`` and typically collects all top-level packages found. To disable this behavior, provide ``packages`` yourself.
Another alternative is to provide a list of top-level package names in the ``top_packages`` argument. In this case, ``find_packages()`` is called when only these top-level packages are included in the search.
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``. At packaging time, the
available versions will be retrieved from ``pypi.python.org``, and the
latest matching version will be hardcoded as the requirement.
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.
.. _when-not-using-pypipythonorg:
when not using pypi.python.org
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
If your dependency libraries come from another package repository, you
can specify another address or even provide your own plugin to retrieve
information from such a server.
To do this, provide a dictionary of options in ``freeze_requirements``:
.. code:: Python
quicklib.setup(
# ...
freeze_requirements = {
# alternative pypi server address
'pypi_server': 'https://my-private-pypi.com/packages/',
# when given, this is imported at packaging time and used to find package versions.
# see quicklib/requirements.py for the StandardPypiServerPlugin default plugin, and follow its interface.
'server_plugin': 'foo.bar:baz()',
}
)
.. _repo: https://github.com/yonatanp/quicklib
.. _examplelibrary: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary/
.. _minimal example library: https://github.com/yonatanp/quicklib/tree/master/examples/minimal/
.. _examplelibrary2: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary2/
.. _Structuring Your Project: http://docs.python-guide.org/en/latest/writing/structure/
.. _examplelibrary's setup.py: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary/setup.py
Raw data
{
"_id": null,
"home_page": "https://github.com/yonatanp/quicklib",
"name": "quicklib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Yonatan Perry",
"author_email": "yonatan.perry@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d4/c9/9a18bdf8e36841e642ec9763d22bcb5b177f267175129c77ac80077f1deb/quicklib-2.5.tar.gz",
"platform": "any",
"description": "quicklib\n========\n\nBuild hassle-free setup scripts for your python libraries, with\npractical versioning, requirements specification, and more (to come).\n\nInstallation\n------------\n\nInstall using:\n\n::\n\n pip install quicklib\n\nOr clone this project's `repo`_ and run:\n\n::\n\n python setup.py install\n\nCreating libraries\n------------------\n\n**TL;DR** - run ``python -m quicklib.bootstrap`` in a new folder and\nanswer some questions, and you're good to go coding. Look at\n`examplelibrary`_ for an example created with this bootstrap process.\n\nAlso, your library needs to be in a git-managed folder, and needs at\nleast one numeric ``major.minor`` tag in your current history.\n\nIf you have no version tags yet, create the first one now and push it:\n\n::\n\n git tag -a 0.1 -m \"first version tag: 0.1\"\n git push origin 0.1\n\nFile structure\n~~~~~~~~~~~~~~\n\nThe recommended library file structure is something like:\n\n::\n\n mylibrary/\n |----- setup.py\n | | OR\n | --- quicklib_setup.yml\n |-- README.md\n |-- [requirements.txt]\n mypackage/\n |-- __init__.py\n |-- version.py\n |-- module1.py\n |-- module2.py\n |-- subpackage/\n |-- __init__.py\n |-- module3.py\n\nIf you want to include more than one top-level package in your library,\nplace additional ones next to ``mypackage``.\n\nFor a deeper dive into recommended structure and other possible options,\ncheck out `Structuring Your Project`_ at the Hitchhiker's Guide to\nPython.\n\nSetup script\n~~~~~~~~~~~~\n\nFor an example ``setup.py`` file see `examplelibrary's setup.py`_.\n\nThe setup script must include this fixed stub copy-pasted verbatim:\n\n.. code:: Python\n\n # -------- quicklib direct/bundled import, copy pasted --------------------------------------------\n import sys as _sys, glob as _glob, os as _os\n is_packaging = not _os.path.exists(\"PKG-INFO\")\n if is_packaging:\n import quicklib\n else:\n zips = _glob.glob(\"quicklib_incorporated.*.zip\")\n if len(zips) != 1:\n raise Exception(\"expected exactly one incorporated quicklib zip but found %s\" % (zips,))\n _sys.path.insert(0, zips[0]); import quicklib; _sys.path.pop(0)\n # -------------------------------------------------------------------------------------------------\n\nAfter that, where you would usually call ``setuptools.setup(...)``, call\n``quicklib.setup(...)`` instead:\n\n.. code:: Python\n\n quicklib.setup(\n name='examplelibrary',\n url=\"https://example.com/\",\n author='ACME Inc.',\n author_email='user@example.com',\n description='examplelibrary: a library to demonstrate how quicklib is used to quickly setup python libraries',\n license='Copyright ACME Inc.',\n platforms='any',\n classifiers=[\n 'Programming Language :: Python',\n 'Development Status :: 4 - Beta',\n 'Natural Language :: English',\n 'Intended Audience :: Developers',\n 'Operating System :: OS Independent',\n 'Topic :: Software Development :: Libraries :: Python Modules',\n ],\n version_module_paths=[\n \"examplepackage/version.py\",\n ],\n )\n\nMost parameters are exactly the same as they are in ``setuptools``.\n\nAdditional parameters:\n\n- ``version_module_paths`` - see details in \"Versioning\" below\n\nModified parameter defaults:\n\n- if ``packages`` is not given, ``find_packages()`` is used\n automatically to discover packages under your library's top\n directory.\n\nYAML-based setup\n~~~~~~~~~~~~~~~~\n\nThe easiest way for simple libraries is to provide all necessary details\nin a YAML file. This is essentially the same as creating a setup.py that\nuses the YAML dictionary as its kwargs.\n\nFor example, create a ``quicklib_setup.yml`` file at the root of your\nproject:\n\n::\n\n setup:\n name: mylibrary\n description: a library for doing some stuff\n version: 1.0\n\nAnd run ``quicklib-setup sdist`` (instead of ``python setup.py sdist``)\nto create the library package.\n\nYou can also ``include`` additional files of a similar format (overriding each other in order of appearance), e.g. to use as common template of values:\n\n::\n\n # mylib_setup.yml\n include:\n - ../common_properties.yml\n setup:\n name: mylibrary\n\n # common_properties.yml\n setup:\n author: ACME Inc.\n author_email: user@example.com\n\nFor additional parameters, see the rest of this documentation and\nprovide parameters to ``quicklib.setup(...)`` as values under the\n``setup`` dictionary in your ``quicklib_setup.yml`` file.\n\nTake a look at the `minimal example library`_ for usage example.\n\nSetup script in non-standard location\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIt is possible to build libraries with quicklib from setup scripts\nother than \"top level setup.py\". This allows building more than one\nlibrary (or variants of a single library) from a single repository.\n\nLook at `examplelibrary2`_ for two such example library variants built\nfrom the same sources.\n\nJust place your setup code in any folder and run it the same way as\nusual, e.g.:\n\n::\n\n python my_other_setup.py sdist bdist_wheel\n\nNote that if you want to have a ``MANIFEST.in`` file to go with the\nscript, you can put it alongside it and using the same base name,\ne.g.:\n\n::\n\n ...\n |-- my_other_setup.py\n |-- my_other_setup.MANIFEST.in\n ...\n\nIf no such alternative MANIFEST.in file is present and a top-level\nMANIFEST.in exists, it will be used as usual.\n\nVersioning\n~~~~~~~~~~\n\nThe build process automatically sets your library version based on the\ngit log and tags. This version information is applied to the built\nlibrary and can later be programmatically queried by library package\nusers.\n\nversion value inference\n^^^^^^^^^^^^^^^^^^^^^^^\n\n1. It ``git-describe``\\ s the ``HEAD`` searching for the latest\n annotated (!) tag with a ``major.minor`` label\n2. If the tag is placed directly on the current ``HEAD`` then this is\n the version label\n\n - otherwise, a ``.micro`` suffix is added denoting the number of\n commits between the tag and ``HEAD``\n\n3. Finally, if there are any local modifications, a ``.dirty`` suffix is\n added\n\nadding version info to your packages\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nAdd a ``version.py`` stub file under any of your top-level packages with\nthis fixed template:\n\n.. code:: Python\n\n # quicklib version boilerplate\n DEV_VERSION = \"0.0.0.dev0\"\n __version__ = DEV_VERSION\n\nIn addition, tell ``setup.py`` where to find those files:\n\n.. code:: Python\n\n quicklib.setup(\n version_module_paths=[\n \"mypackage/version.py\",\n # ... you can specify more than one\n ],\n )\n\nThen, your users can programmatically query this version value by running\ne.g.:\n\n.. code:: Python\n\n import mypackage\n print(mypackage.version.__version__)\n\nversioning multiple packages\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf your library contains multiple top-level packages, a ``version.py``\nfile should usually be added under each of them. This allows your\nlibrary users to ask about the version of each of your individual\npackages while being agnostic to the fact that they come from the same\nlibrary. If you find this confusing, you may want to stick to one\ntop-level package per library.\n\nChoosing packages to include\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe default behavior calls ``setuptools.find_packages()`` and typically collects all top-level packages found. To disable this behavior, provide ``packages`` yourself.\n\nAnother alternative is to provide a list of top-level package names in the ``top_packages`` argument. In this case, ``find_packages()`` is called when only these top-level packages are included in the search.\n\nRequirements\n~~~~~~~~~~~~\n\nTo add requirements to your library, add them in a ``requirements.txt``\nfile at the project root.\n\nUse syntax such as:\n\n::\n\n numpy\n pandas==0.18.1\n yarg~=0.1.1\n\nFreezing requirements\n^^^^^^^^^^^^^^^^^^^^^\n\nSometimes you want to hardcode the versions of your dependencies. This\nhelps provide your users the exact same configuration you built and\ntested with. To avoid having to manually update those numbers, you can\nkeep your requirements specified as usual but activate \"requirement\nfreezing\".\n\nDo this by passing ``freeze_requirements=True`` to the\n``quicklib.setup(...)`` call in ``setup.py``. At packaging time, the\navailable versions will be retrieved from ``pypi.python.org``, and the\nlatest matching version will be hardcoded as the requirement.\n\nNote: if your library depends on a hardcoded ``dep==1.0`` but ``dep``\ndid not hardcode its dependencies, your users might get different\npackages. To get around that you can specify your requirements'\nrequirements as your own requirements. Automatically fetching this\ninformation is on this library's roadmap.\n\n.. _when-not-using-pypipythonorg:\n\nwhen not using pypi.python.org\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf your dependency libraries come from another package repository, you\ncan specify another address or even provide your own plugin to retrieve\ninformation from such a server.\n\nTo do this, provide a dictionary of options in ``freeze_requirements``:\n\n.. code:: Python\n\n quicklib.setup(\n # ...\n freeze_requirements = {\n # alternative pypi server address\n 'pypi_server': 'https://my-private-pypi.com/packages/',\n # when given, this is imported at packaging time and used to find package versions.\n # see quicklib/requirements.py for the StandardPypiServerPlugin default plugin, and follow its interface.\n 'server_plugin': 'foo.bar:baz()',\n }\n )\n\n.. _repo: https://github.com/yonatanp/quicklib\n.. _examplelibrary: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary/\n.. _minimal example library: https://github.com/yonatanp/quicklib/tree/master/examples/minimal/\n.. _examplelibrary2: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary2/\n.. _Structuring Your Project: http://docs.python-guide.org/en/latest/writing/structure/\n.. _examplelibrary's setup.py: https://github.com/yonatanp/quicklib/tree/master/examples/examplelibrary/setup.py\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "quicklib: hassle-free setup scripts for your python libraries",
"version": "2.5",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f36ed0ec7d8c88d769641567ace89bfa4898596814ba16f4f319ad9b21b3457b",
"md5": "7c9ca71bedd3c9c479c8c9d777822a97",
"sha256": "185a95c252b37e89df047c982f1f82878856f8c8fd11f7b417030996f711b414"
},
"downloads": -1,
"filename": "quicklib-2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c9ca71bedd3c9c479c8c9d777822a97",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 39678,
"upload_time": "2023-02-07T22:02:55",
"upload_time_iso_8601": "2023-02-07T22:02:55.502554Z",
"url": "https://files.pythonhosted.org/packages/f3/6e/d0ec7d8c88d769641567ace89bfa4898596814ba16f4f319ad9b21b3457b/quicklib-2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d4c99a18bdf8e36841e642ec9763d22bcb5b177f267175129c77ac80077f1deb",
"md5": "922153fb51b33c8e0ea232de00d90817",
"sha256": "e3ea8b3d27b1b062a665df5d1620ab26c0f9d92d152b2045df0108d4607d149d"
},
"downloads": -1,
"filename": "quicklib-2.5.tar.gz",
"has_sig": false,
"md5_digest": "922153fb51b33c8e0ea232de00d90817",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 42138,
"upload_time": "2023-02-07T22:02:56",
"upload_time_iso_8601": "2023-02-07T22:02:56.769077Z",
"url": "https://files.pythonhosted.org/packages/d4/c9/9a18bdf8e36841e642ec9763d22bcb5b177f267175129c77ac80077f1deb/quicklib-2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-02-07 22:02:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "yonatanp",
"github_project": "quicklib",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "quicklib"
}
JSON
