Simplify your setup.py
======================
.. image:: https://img.shields.io/pypi/v/setupmeta.svg
:target: https://pypi.org/project/setupmeta/
:alt: Version on pypi
.. image:: https://github.com/codrsquad/setupmeta/workflows/Tests/badge.svg
:target: https://github.com/codrsquad/setupmeta/actions
:alt: Tested with Github Actions
.. image:: https://codecov.io/gh/codrsquad/setupmeta/branch/main/graph/badge.svg
:target: https://codecov.io/gh/codrsquad/setupmeta
:alt: Test code codecov
.. image:: https://img.shields.io/pypi/pyversions/setupmeta.svg
:target: https://github.com/codrsquad/setupmeta
:alt: Python versions tested (link to github project)
.. image:: https://img.shields.io/conda/vn/conda-forge/setupmeta
:target: https://anaconda.org/conda-forge/setupmeta
:alt: Version on conda-forge
----
Writing a ``setup.py`` typically involves lots of boilerplate and copy-pasting from project to project.
This package aims to simplify that and bring some DRY_ principle to python packaging_.
Here's what your (complete, and ready to ship to pypi) ``setup.py`` could look like with setupmeta_::
from setuptools import setup
setup(
name="myproject",
versioning="distance", # Optional, would activate tag-based versioning
setup_requires="setupmeta" # This is where setupmeta comes in
)
And that should be it - setupmeta_ will take it from there, extracting everything else from the rest of your project
(following typical conventions commonly used).
You can use the **explain** command (see commands_) to see what setupmeta_ deduced from your project,
for the above it would look something like this (you can see which file and which line each setting came from,
note that a lot of info is typically extracted from your project, if you follow usual conventions)::
~/myproject: python setup.py explain
author: (auto-adjust ) Your Name
\_: (myproject.py:7 ) Your Name<your@email.com>
author_email: (auto-adjust ) your@email.com
description: (README.rst:1 ) First line of your README
entry_points: (entry_points.ini) [console_scripts] ...
install_requires: (requirements.txt) ["click", ...
license: (auto-fill ) MIT
long_description: (README.rst ) Long description would be your inlined README
name: (explicit ) myproject
py_modules: (auto-fill ) ["myproject"]
setup_requires: (explicit ) ["setupmeta"]
version: (git ) 1.2.3.post2
versioning: (explicit ) distance
See examples_ for more.
**Note**: ``setupmeta``'s versioning is based on::
git describe --dirty --tags --long --first-parent --match 'v*.*'
# Then, if above yields nothing, we try the more vague '*.*'
git describe --dirty --tags --long --first-parent --match '*.*'
you will need **git version >= 1.8.4** if you wish to use ``setupmeta``'s versioning capabilities.
Goal
====
The goal of this project is to:
* Allow to write very short (yet complete) ``setup.py``-s, without boilerplate, and encourage good common packaging_ practices
* Point out missing important info (example: version) in ``setup.py explain``
* Support tag-based versioning_ (like setuptools_scm_, but with super simple configuration/defaults and automated ``bump`` capability)
* Provide useful Commands_ to see the metadata (**explain**), **version** (including support for bumping versions),
**cleanall**, etc
How it works?
=============
* Everything that you explicitly provide in your original ``setuptools.setup()`` call is taken as-is (never changed),
and internally labelled as ``explicit``.
So if you don't like something that setupmeta_ deduces, you can always explicitly state it.
* ``name`` is auto-filled from your setup.py's ``__title__`` (if there is one, sometimes having a constant is quite handy...)
* ``packages`` and ``package_dir`` is auto-filled accordingly if you have a ``<name>/__init__.py`` or ``src/<name>/__init__.py`` file
* ``py_modules`` is auto-filled if you have a ``<name>.py`` file
* ``entry_points`` is auto-filled from file ``entry_points.ini`` (bonus: tools like PyCharm have a nice syntax highlighter for those)
* ``install_requires`` is auto-filled if you have a ``requirements.txt`` (or ``pinned.txt``) file,
pinning is abstracted away by default as per `community recommendation`_, see requirements_ for more info.
* ``tests_require`` is auto-filled if you have a ``tests/requirements.txt``, or ``requirements-dev.txt``,
or ``dev-requirements.txt``, or ``test-requirements.txt`` file
* ``description`` will be the 1st line of your README (unless that 1st line is too short, or is just the project's name),
or the 1st line of the first docstring found in the scanned files (see list below)
* ``long_description`` is auto-filled from your README file (looking for ``README.rst``, ``README.md``,
then ``README*``, first one found wins).
Special tokens can be used (notation aimed at them easily being `rst comments`_):
* ``.. [[end long_description]]`` as end marker, so you don't have to use the entire file as long description
* ``.. [[include <relative-path>]]`` if you want another file included as well (for example, people like to add ``HISTORY.txt`` as well)
* these tokens must appear either at beginning/end of line, or be after/before at least one space character
* ``version`` can be stated explicitly, or be computed from git tags using ``versioning=...`` (see versioning_ for more info):
* With ``versioning="distance"``, your git tags will be of the form ``v{major}.{minor}.0``,
the number of commits since latest version tag will be used to auto-fill the "patch" part of the version:
* tag "v1.0.0", no commits since tag -> version is "1.0.0"
* tag "v1.0.0", 5 commits since tag -> version is "1.0.5"
* if checkout is dirty, a marker is added -> version would be "1.0.5.post5.dirty"
* With ``versioning="post"``, your git tags will be of the form ``v{major}.{minor}.{patch}``,
a "post" addendum will be present if there are commits since latest version tag:
* tag "v1.0.0", no commits since tag -> version is "1.0.0"
* tag "v1.0.0", 5 commits since tag -> version is "1.0.0.post5"
* if checkout is dirty, a marker is added -> version would be "1.0.0.post5.dirty"
* With ``versioning="build-id"``, your git tags will be of the form ``v{major}.{minor}.0``,
the number of commits since latest version tag will be used to auto-fill the "patch" part of the version:
* tag "v1.0.0", no commits since tag, ``BUILD_ID=12`` -> version is "1.0.0+h12.g123"
* tag "v1.0.0", no commits since tag, ``BUILD_ID`` not defined -> version is "1.0.0+hlocal.g123"
* tag "v1.0.0", 5 commits since tag, ``BUILD_ID=12`` -> version is "1.0.5+h12.g456"
* tag "v1.0.0", 5 commits since tag, ``BUILD_ID`` not defined -> version is "1.0.5+hlocal.g456"
* if checkout is dirty, a marker is added -> version would be "1.0.5+hlocal.g456.dirty"
* Use the **bump** command (see commands_) to easily bump (ie: increment major, minor or patch + apply git tag)
* Version format can be customized, see versioning_ for more info
* ``version``, ``versioning``, ``url``, ``download_url``, ``bugtrack_url``, ``license``, ``keywords``, ``author``, ``contact``, ``maintainer``,
and ``platforms`` will be auto-filled from:
* Lines of the form ``__key__ = "value"`` in your modules (simple constants only,
expressions are ignored - the modules are not imported but scanned using regexes)
* Lines of the form ``key: value`` in your docstring
* Files are examined in this order (first find wins):
* ``setup.py``
* ``<package>.py`` (mccabe_ for example)
* ``<package>/__about__.py`` (cryptography_ for example)
* ``<package>/__version__.py`` (requests_ for example)
* ``<package>/__init__.py`` (changes_, arrow_ for example)
* ``src/`` is also examined (for those who like to have their packages under ``src``)
* URLs can be simplified:
* if ``url`` points to your general github repo (like: https://github.com/codrsquad),
the ``name`` of your project is auto-appended to it
* relative urls are auto-filled by prefixing them with ``url``
* urls may use ``{name}`` and/or ``{version}`` markers, it will be expanded appropriately
* ``author``, ``maintainer`` and ``contact`` names and emails can be combined into one line
(setupmeta_ will figure out the email part and auto-fill it properly)
* i.e.: ``author: Bob D bob@example.com`` will yield the proper ``author`` and ``author_email`` settings
This should hopefully work nicely for the vast majority of python projects out there.
If you need advanced stuff, you can still leverage setupmeta_ for all the usual stuff above, and go explicit wherever needed.
.. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself
.. _commands: https://github.com/codrsquad/setupmeta/blob/main/docs/commands.rst
.. _requirements: https://github.com/codrsquad/setupmeta/blob/main/docs/requirements.rst
.. _versioning: https://github.com/codrsquad/setupmeta/blob/main/docs/versioning.rst
.. _community recommendation: https://packaging.python.org/discussions/install-requires-vs-requirements/
.. _packaging: https://python-packaging.readthedocs.io/en/latest/
.. _setuptools_scm: https://github.com/pypa/setuptools_scm
.. _setupmeta: https://github.com/codrsquad/setupmeta
.. _examples: https://github.com/codrsquad/setupmeta/tree/main/examples
.. _rst comments: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#comments
.. _requests: https://github.com/psf/requests/tree/main/src/requests
.. _cryptography: https://github.com/pyca/cryptography/tree/main/src/cryptography
.. _changes: https://github.com/michaeljoseph/changes/blob/main/changes/__init__.py
.. _arrow: https://github.com/arrow-py/arrow/blob/master/arrow/__init__.py
.. _mccabe: https://github.com/PyCQA/mccabe/blob/master/mccabe.py
Raw data
{
"_id": null,
"home_page": "https://github.com/codrsquad/setupmeta",
"name": "setupmeta",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": null,
"author": "Zoran Simic",
"author_email": "zoran@simicweb.com",
"download_url": "https://files.pythonhosted.org/packages/bc/f5/eaaa9231310c8276ad9e7edc5a2a6cb5de354d2b287b7ce436be8cc85739/setupmeta-3.6.1.tar.gz",
"platform": null,
"description": "Simplify your setup.py\n======================\n\n.. image:: https://img.shields.io/pypi/v/setupmeta.svg\n :target: https://pypi.org/project/setupmeta/\n :alt: Version on pypi\n\n.. image:: https://github.com/codrsquad/setupmeta/workflows/Tests/badge.svg\n :target: https://github.com/codrsquad/setupmeta/actions\n :alt: Tested with Github Actions\n\n.. image:: https://codecov.io/gh/codrsquad/setupmeta/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/codrsquad/setupmeta\n :alt: Test code codecov\n\n.. image:: https://img.shields.io/pypi/pyversions/setupmeta.svg\n :target: https://github.com/codrsquad/setupmeta\n :alt: Python versions tested (link to github project)\n\n.. image:: https://img.shields.io/conda/vn/conda-forge/setupmeta\n :target: https://anaconda.org/conda-forge/setupmeta\n :alt: Version on conda-forge\n\n----\n\nWriting a ``setup.py`` typically involves lots of boilerplate and copy-pasting from project to project.\n\nThis package aims to simplify that and bring some DRY_ principle to python packaging_.\nHere's what your (complete, and ready to ship to pypi) ``setup.py`` could look like with setupmeta_::\n\n from setuptools import setup\n\n setup(\n name=\"myproject\",\n versioning=\"distance\", # Optional, would activate tag-based versioning\n setup_requires=\"setupmeta\" # This is where setupmeta comes in\n )\n\nAnd that should be it - setupmeta_ will take it from there, extracting everything else from the rest of your project\n(following typical conventions commonly used).\n\nYou can use the **explain** command (see commands_) to see what setupmeta_ deduced from your project,\nfor the above it would look something like this (you can see which file and which line each setting came from,\nnote that a lot of info is typically extracted from your project, if you follow usual conventions)::\n\n ~/myproject: python setup.py explain\n\n author: (auto-adjust ) Your Name\n \\_: (myproject.py:7 ) Your Name<your@email.com>\n author_email: (auto-adjust ) your@email.com\n description: (README.rst:1 ) First line of your README\n entry_points: (entry_points.ini) [console_scripts] ...\n install_requires: (requirements.txt) [\"click\", ...\n license: (auto-fill ) MIT\n long_description: (README.rst ) Long description would be your inlined README\n name: (explicit ) myproject\n py_modules: (auto-fill ) [\"myproject\"]\n setup_requires: (explicit ) [\"setupmeta\"]\n version: (git ) 1.2.3.post2\n versioning: (explicit ) distance\n\nSee examples_ for more.\n\n**Note**: ``setupmeta``'s versioning is based on::\n\n git describe --dirty --tags --long --first-parent --match 'v*.*'\n\n # Then, if above yields nothing, we try the more vague '*.*'\n\n git describe --dirty --tags --long --first-parent --match '*.*'\n\nyou will need **git version >= 1.8.4** if you wish to use ``setupmeta``'s versioning capabilities.\n\n\nGoal\n====\n\nThe goal of this project is to:\n\n* Allow to write very short (yet complete) ``setup.py``-s, without boilerplate, and encourage good common packaging_ practices\n\n* Point out missing important info (example: version) in ``setup.py explain``\n\n* Support tag-based versioning_ (like setuptools_scm_, but with super simple configuration/defaults and automated ``bump`` capability)\n\n* Provide useful Commands_ to see the metadata (**explain**), **version** (including support for bumping versions),\n **cleanall**, etc\n\n\nHow it works?\n=============\n\n* Everything that you explicitly provide in your original ``setuptools.setup()`` call is taken as-is (never changed),\n and internally labelled as ``explicit``.\n So if you don't like something that setupmeta_ deduces, you can always explicitly state it.\n\n* ``name`` is auto-filled from your setup.py's ``__title__`` (if there is one, sometimes having a constant is quite handy...)\n\n* ``packages`` and ``package_dir`` is auto-filled accordingly if you have a ``<name>/__init__.py`` or ``src/<name>/__init__.py`` file\n\n* ``py_modules`` is auto-filled if you have a ``<name>.py`` file\n\n* ``entry_points`` is auto-filled from file ``entry_points.ini`` (bonus: tools like PyCharm have a nice syntax highlighter for those)\n\n* ``install_requires`` is auto-filled if you have a ``requirements.txt`` (or ``pinned.txt``) file,\n pinning is abstracted away by default as per `community recommendation`_, see requirements_ for more info.\n\n* ``tests_require`` is auto-filled if you have a ``tests/requirements.txt``, or ``requirements-dev.txt``,\n or ``dev-requirements.txt``, or ``test-requirements.txt`` file\n\n* ``description`` will be the 1st line of your README (unless that 1st line is too short, or is just the project's name),\n or the 1st line of the first docstring found in the scanned files (see list below)\n\n* ``long_description`` is auto-filled from your README file (looking for ``README.rst``, ``README.md``,\n then ``README*``, first one found wins).\n Special tokens can be used (notation aimed at them easily being `rst comments`_):\n\n * ``.. [[end long_description]]`` as end marker, so you don't have to use the entire file as long description\n\n * ``.. [[include <relative-path>]]`` if you want another file included as well (for example, people like to add ``HISTORY.txt`` as well)\n\n * these tokens must appear either at beginning/end of line, or be after/before at least one space character\n\n* ``version`` can be stated explicitly, or be computed from git tags using ``versioning=...`` (see versioning_ for more info):\n\n * With ``versioning=\"distance\"``, your git tags will be of the form ``v{major}.{minor}.0``,\n the number of commits since latest version tag will be used to auto-fill the \"patch\" part of the version:\n\n * tag \"v1.0.0\", no commits since tag -> version is \"1.0.0\"\n\n * tag \"v1.0.0\", 5 commits since tag -> version is \"1.0.5\"\n\n * if checkout is dirty, a marker is added -> version would be \"1.0.5.post5.dirty\"\n\n * With ``versioning=\"post\"``, your git tags will be of the form ``v{major}.{minor}.{patch}``,\n a \"post\" addendum will be present if there are commits since latest version tag:\n\n * tag \"v1.0.0\", no commits since tag -> version is \"1.0.0\"\n\n * tag \"v1.0.0\", 5 commits since tag -> version is \"1.0.0.post5\"\n\n * if checkout is dirty, a marker is added -> version would be \"1.0.0.post5.dirty\"\n\n * With ``versioning=\"build-id\"``, your git tags will be of the form ``v{major}.{minor}.0``,\n the number of commits since latest version tag will be used to auto-fill the \"patch\" part of the version:\n\n * tag \"v1.0.0\", no commits since tag, ``BUILD_ID=12`` -> version is \"1.0.0+h12.g123\"\n\n * tag \"v1.0.0\", no commits since tag, ``BUILD_ID`` not defined -> version is \"1.0.0+hlocal.g123\"\n\n * tag \"v1.0.0\", 5 commits since tag, ``BUILD_ID=12`` -> version is \"1.0.5+h12.g456\"\n\n * tag \"v1.0.0\", 5 commits since tag, ``BUILD_ID`` not defined -> version is \"1.0.5+hlocal.g456\"\n\n * if checkout is dirty, a marker is added -> version would be \"1.0.5+hlocal.g456.dirty\"\n\n * Use the **bump** command (see commands_) to easily bump (ie: increment major, minor or patch + apply git tag)\n\n * Version format can be customized, see versioning_ for more info\n\n* ``version``, ``versioning``, ``url``, ``download_url``, ``bugtrack_url``, ``license``, ``keywords``, ``author``, ``contact``, ``maintainer``,\n and ``platforms`` will be auto-filled from:\n\n * Lines of the form ``__key__ = \"value\"`` in your modules (simple constants only,\n expressions are ignored - the modules are not imported but scanned using regexes)\n\n * Lines of the form ``key: value`` in your docstring\n\n * Files are examined in this order (first find wins):\n\n * ``setup.py``\n\n * ``<package>.py`` (mccabe_ for example)\n\n * ``<package>/__about__.py`` (cryptography_ for example)\n\n * ``<package>/__version__.py`` (requests_ for example)\n\n * ``<package>/__init__.py`` (changes_, arrow_ for example)\n\n * ``src/`` is also examined (for those who like to have their packages under ``src``)\n\n * URLs can be simplified:\n\n * if ``url`` points to your general github repo (like: https://github.com/codrsquad),\n the ``name`` of your project is auto-appended to it\n\n * relative urls are auto-filled by prefixing them with ``url``\n\n * urls may use ``{name}`` and/or ``{version}`` markers, it will be expanded appropriately\n\n * ``author``, ``maintainer`` and ``contact`` names and emails can be combined into one line\n (setupmeta_ will figure out the email part and auto-fill it properly)\n\n * i.e.: ``author: Bob D bob@example.com`` will yield the proper ``author`` and ``author_email`` settings\n\n\nThis should hopefully work nicely for the vast majority of python projects out there.\nIf you need advanced stuff, you can still leverage setupmeta_ for all the usual stuff above, and go explicit wherever needed.\n\n\n.. _DRY: https://en.wikipedia.org/wiki/Don%27t_repeat_yourself\n\n.. _commands: https://github.com/codrsquad/setupmeta/blob/main/docs/commands.rst\n\n.. _requirements: https://github.com/codrsquad/setupmeta/blob/main/docs/requirements.rst\n\n.. _versioning: https://github.com/codrsquad/setupmeta/blob/main/docs/versioning.rst\n\n.. _community recommendation: https://packaging.python.org/discussions/install-requires-vs-requirements/\n\n.. _packaging: https://python-packaging.readthedocs.io/en/latest/\n\n.. _setuptools_scm: https://github.com/pypa/setuptools_scm\n\n.. _setupmeta: https://github.com/codrsquad/setupmeta\n\n.. _examples: https://github.com/codrsquad/setupmeta/tree/main/examples\n\n.. _rst comments: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#comments\n\n.. _requests: https://github.com/psf/requests/tree/main/src/requests\n\n.. _cryptography: https://github.com/pyca/cryptography/tree/main/src/cryptography\n\n.. _changes: https://github.com/michaeljoseph/changes/blob/main/changes/__init__.py\n\n.. _arrow: https://github.com/arrow-py/arrow/blob/master/arrow/__init__.py\n\n.. _mccabe: https://github.com/PyCQA/mccabe/blob/master/mccabe.py\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simplify your setup.py",
"version": "3.6.1",
"project_urls": {
"Download": "https://github.com/codrsquad/setupmeta/archive/v3.6.1.tar.gz",
"Homepage": "https://github.com/codrsquad/setupmeta"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "50b0b85f3d8bb092d626c8d643911bde2ba0a79747eba1473003d9c1ae8611dc",
"md5": "c2cdb2c19bf05ecaaad719ecefb49eda",
"sha256": "d1599a02da07bf737e15c211419330b3f3eca38b7600a68cf6702c7e8c3a3ba1"
},
"downloads": -1,
"filename": "setupmeta-3.6.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2cdb2c19bf05ecaaad719ecefb49eda",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 41217,
"upload_time": "2025-01-16T17:06:16",
"upload_time_iso_8601": "2025-01-16T17:06:16.297240Z",
"url": "https://files.pythonhosted.org/packages/50/b0/b85f3d8bb092d626c8d643911bde2ba0a79747eba1473003d9c1ae8611dc/setupmeta-3.6.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bcf5eaaa9231310c8276ad9e7edc5a2a6cb5de354d2b287b7ce436be8cc85739",
"md5": "8592a774f256b0de1bd531165717be6c",
"sha256": "d41ae99e92edefcebf79c35130f52123a6aa0e185ebf0724505379a76f0a8142"
},
"downloads": -1,
"filename": "setupmeta-3.6.1.tar.gz",
"has_sig": false,
"md5_digest": "8592a774f256b0de1bd531165717be6c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 89380,
"upload_time": "2025-01-16T17:06:19",
"upload_time_iso_8601": "2025-01-16T17:06:19.274056Z",
"url": "https://files.pythonhosted.org/packages/bc/f5/eaaa9231310c8276ad9e7edc5a2a6cb5de354d2b287b7ce436be8cc85739/setupmeta-3.6.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-16 17:06:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "codrsquad",
"github_project": "setupmeta",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "setupmeta"
}
JSON
