Minchin.Releaser
================
Tools to make releasing Python packages easier.
.. image:: https://img.shields.io/pypi/v/minchin.releaser.svg?style=flat
:target: https://pypi.python.org/pypi/minchin.releaser/
:alt: PyPI version number
.. image:: https://img.shields.io/badge/-Changelog-success?style=flat
:target: https://github.com/MinchinWeb/minchin.releaser/blob/master/changelog.rst
:alt: Changelog
.. image:: https://img.shields.io/pypi/pyversions/minchin.releaser?style=flat
:target: https://pypi.python.org/pypi/minchin.releaser/
:alt: Supported Python version
.. image:: https://img.shields.io/pypi/l/minchin.releaser.svg?style=flat&color=green
:target: https://github.com/MinchinWeb/minchin.releaser/blob/master/LICENSE.txt
:alt: License
.. image:: https://img.shields.io/pypi/dm/minchin.releaser.svg?style=flat
:target: https://pypi.python.org/pypi/minchin.releaser/
:alt: Download Count
*Minchin dot Releaser* is currently set up as an
`invoke <http://www.pyinvoke.org/>`_ task. It is designed to provide a single
command to make and publish a release of your Python package. An extra
configuration file is an one-time set up requirement to be able to make use of
this.
Once set up, *Minchin dot Releaser*, when run, will:
- check the configuration
- confirm all items in the project directory have been added to Git (i.e. that
the repo is clean)
- check that your Readme will render on PyPI
- sort your import statements
- vendorize required packages
- run the test suite
- update the version number within your code
- add the release to your changelog
- build project documentation
- build your project as a Python distribution
- confirm your project can be installed from the local machine to the local
machine
- confirm your project can be uploaded to the test PyPI server and then
downloaded and installed from this server.
- confirm your project can be uploaded to the main PyPI server and then
downloaded and installed from this server.
- create a Git tag for your release
- update your version number to a pre-release version
*Minchin dot Releaser* relies on features added in the more recent versions of
Python, and thus is Python 3 only.
Assumptions
-----------
This package makes several assumptions. This is not the only way to do these
things, but I have found these choices work well for my use-cases. If you have
chosen a different way to set up your project, most of the applicable features
will just not work, but the rest of *Minchin dot Releaser* should continue to
work.
It is assumed:
- this is a Python project.
- your version is stored in one place in your project, as a string assigned to
the variable ``__version__``, that this is one line and there is nothing else
on this line. If this is not the case, *Minchin dot Releaser* will be unable
to determine your project's version number and so won't be much use to you.
This is the project's one hard requirement in how you organize your code.
- your version number is importable by Python at
``<some_module_name>.__version__``.
- source control is done using Git. The Git functionality will be ignored if
this is not the case.
*Minchin dot Releaser* will support both ``setup.py`` and ``pyproject.toml``
(i.e. PEP 518?) based builds.
Setting Up Your Project
-----------------------
Step 1. Install ``minchin.releaser``.
"""""""""""""""""""""""""""""""""""""
The simplest way is to use ``pip``::
pip install minchin.releaser
This will also install all the other packages ``minchin.releaser`` depends
on.
You will also want to add ``minchin.releaser`` to the list of your
project's requirements.
Step 2. Create a ``tasks.py`` file.
"""""""""""""""""""""""""""""""""""
This is where ``invoke`` determine was tasks are available to run. This file
should be created in the root folder of your project. If you are not using
``invoke`` for other tasks, this file can be four lines:
.. code-block:: python
# tasks.py
try:
from minchin.releaser import make_release
except ImportError:
print("[WARN] minchin.releaser not installed.")
# your other Invoke tasks...
To confirm that this is working, go to the command line in the root folder
of your project, and run:
.. code-block:: sh
$ invoke --list
which will now list ``make-release`` as an available task.
Step 3. Configure your project.
"""""""""""""""""""""""""""""""
Project configuration is actually ``invoke`` configuration, so it is stored
in the ``invoke.yaml`` folder in the project root (or anywhere else
``invoke`` can load configuration from) under the ``releaser`` key.
Available sub-keys:
module_name
(required) the name of your project. It is assumed that your project's
version number is importable at ``module_name.__version__`` (see
project assumptions).
pypi_name
(optional) the name of your project as uploaded to PyPI. This only needs to
be set if it differs from ``module_name``.
here
(required) the base location to build your package from. To set to the
current directory, set to ``.``
docs
(required, but can be set to ``None``) the base documentation
directory. This is relative to ``here``.
test
(required, but can be set to ``None``) the base test directory. This is
relative to ``here``.
source
(required) the base directory of your Python source code. This is
relative to ``here``.
changelog
(required, but can be set to ``None``) the location of your changelog
file. This is relative to ``here``.
version
(required) the location of where your version string is stored. This is
relative to ``here``.
test_command
(required, but can be set to ``None``) command, run from the command
line with the current directory set to ``here``, to run your test suite.
version_bump
(optional) default *level* to bump your version. If set to ``none``,
this will be requested at runtime. Valid options include ``major``,
``minor``, ``bug``, and ``none``.
extra_packages
(optional) Used to install packages before installing your module from
the server. Useful particularly for packages that need to be installed
from cache (rather than re-downloaded and compiled each time) or for
packages that are not available on the test PyPI server. Valid server
keys are ``local``, ``test``, and ``pypi``. Under the server key,
create a list of the packages you want explicitly installed.
(vendorize keys are not listed here.)
Step 4. Set up Invoke command shell (Windows).
""""""""""""""""""""""""""""""""""""""""""""""
.. Note::
Recent version of ``invoke`` seem to have resolved this, and this not
longer seems to be needed.
*Minchin dot Releaser* runs certain commands at the command line. ``Invoke``,
regardless of platform, tries to run these on ``/bin/bash`` which doesn't exist
in Windows and thus these commands fail.
To fix this, create a ``.invoke.yaml`` file in the root of your user directory
(so the file is ``C:\Users\<your_username>\.invoke.yaml``) and add:
.. code-block:: yaml
run:
shell: C:\Windows\system32\CMD.exe
Step 5. Set up twine configuration.
"""""""""""""""""""""""""""""""""""
Create or modify ``$HOME/.pypirc`` to include the ``testpypi`` server:
.. code-block:: ini
[distutils]
index-servers=
pypi
testpypi
[testpypi]
repository: https://test.pypi.org/legacy/
username: your testpypi username
.. warning::
Do not store passwords in the .pypirc file. Storing passwords in plain text
is never a good idea.
*Minchin dot Releaser* is automated, and so needs access to your password. This
can be done using ``keyring``. Keyring can be installed by ``pip`` and then
passwords are added from the command-line.
.. code-block:: sh
$ pip install keyring
$ keyring set https://test.pypi.org/legacy/ your-username
$ keyring set https://upload.pypi.org/legacy/ your-username
See `Twine Keyring Support
<https://twine.readthedocs.io/en/latest/#keyring-support>`_ for more details.
Step 6. Register your package on PyPI.
""""""""""""""""""""""""""""""""""""""
(On the new infrastructure, this no longer needs to be done explicitly. Just
upload your package.)
Step 7. Upload your package.
""""""""""""""""""""""""""""
.. code-block:: sh
$ invoke make-release
And then work through the prompts. If this process breaks half-way through,
you can re-start.
In particular, many packages are not available on the test version of PyPI, and
will need to iteratively be added to the configuration under the
``extra_packages\test`` key.
Credits
-------
Inspired (in part) by
https://hynek.me/articles/sharing-your-labor-of-love-pypi-quick-and-dirty/
Sample ``invoke.yaml``
----------------------
.. code-block:: yaml
releaser:
module_name: minchin.releaser
here: .
docs: .
test: None
source: minchin
changelog: changelog.rst
version: minchin\releaser\constants.py
test_command: "green -kq"
version_bump: none
extra_packages:
test:
- gitdb
- invoke
- isort
- pkginfo
- semantic_version
- twine
- wheel
pypi:
- invoke
vendor_dest: minchin\releaser\_vendor
vendor_packages:
"minchin.text":
src: ..\minchin.text\minchin
dest: .
requirements: ..\minchin.text\requirements.in
vendor_override_src: vendor_src
Raw data
{
"_id": null,
"home_page": "https://github.com/MinchinWeb/minchin.releaser",
"name": "minchin.releaser",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "William Minchin",
"author_email": "w_minchin@hotmail.com",
"download_url": "https://files.pythonhosted.org/packages/ed/25/94a2e4e6113801251cb4c6761b359917c22a0b484bccb2640c3698fbd048/minchin.releaser-0.9.1.tar.gz",
"platform": "any",
"description": "Minchin.Releaser\r\n================\r\n\r\nTools to make releasing Python packages easier.\r\n\r\n.. image:: https://img.shields.io/pypi/v/minchin.releaser.svg?style=flat\r\n :target: https://pypi.python.org/pypi/minchin.releaser/\r\n :alt: PyPI version number\r\n\r\n.. image:: https://img.shields.io/badge/-Changelog-success?style=flat\r\n :target: https://github.com/MinchinWeb/minchin.releaser/blob/master/changelog.rst\r\n :alt: Changelog\r\n\r\n.. image:: https://img.shields.io/pypi/pyversions/minchin.releaser?style=flat\r\n :target: https://pypi.python.org/pypi/minchin.releaser/\r\n :alt: Supported Python version\r\n\r\n.. image:: https://img.shields.io/pypi/l/minchin.releaser.svg?style=flat&color=green\r\n :target: https://github.com/MinchinWeb/minchin.releaser/blob/master/LICENSE.txt\r\n :alt: License\r\n\r\n.. image:: https://img.shields.io/pypi/dm/minchin.releaser.svg?style=flat\r\n :target: https://pypi.python.org/pypi/minchin.releaser/\r\n :alt: Download Count\r\n\r\n*Minchin dot Releaser* is currently set up as an\r\n`invoke <http://www.pyinvoke.org/>`_ task. It is designed to provide a single\r\ncommand to make and publish a release of your Python package. An extra\r\nconfiguration file is an one-time set up requirement to be able to make use of\r\nthis.\r\n\r\nOnce set up, *Minchin dot Releaser*, when run, will:\r\n\r\n- check the configuration\r\n- confirm all items in the project directory have been added to Git (i.e. that\r\n the repo is clean)\r\n- check that your Readme will render on PyPI\r\n- sort your import statements\r\n- vendorize required packages\r\n- run the test suite\r\n- update the version number within your code\r\n- add the release to your changelog\r\n- build project documentation\r\n- build your project as a Python distribution\r\n- confirm your project can be installed from the local machine to the local\r\n machine\r\n- confirm your project can be uploaded to the test PyPI server and then\r\n downloaded and installed from this server.\r\n- confirm your project can be uploaded to the main PyPI server and then\r\n downloaded and installed from this server.\r\n- create a Git tag for your release\r\n- update your version number to a pre-release version\r\n\r\n*Minchin dot Releaser* relies on features added in the more recent versions of\r\nPython, and thus is Python 3 only.\r\n\r\nAssumptions\r\n-----------\r\n\r\nThis package makes several assumptions. This is not the only way to do these\r\nthings, but I have found these choices work well for my use-cases. If you have\r\nchosen a different way to set up your project, most of the applicable features\r\nwill just not work, but the rest of *Minchin dot Releaser* should continue to\r\nwork.\r\n\r\nIt is assumed:\r\n\r\n- this is a Python project.\r\n- your version is stored in one place in your project, as a string assigned to\r\n the variable ``__version__``, that this is one line and there is nothing else\r\n on this line. If this is not the case, *Minchin dot Releaser* will be unable\r\n to determine your project's version number and so won't be much use to you.\r\n This is the project's one hard requirement in how you organize your code.\r\n- your version number is importable by Python at\r\n ``<some_module_name>.__version__``.\r\n- source control is done using Git. The Git functionality will be ignored if\r\n this is not the case.\r\n\r\n*Minchin dot Releaser* will support both ``setup.py`` and ``pyproject.toml``\r\n(i.e. PEP 518?) based builds.\r\n\r\nSetting Up Your Project\r\n-----------------------\r\n\r\nStep 1. Install ``minchin.releaser``.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\nThe simplest way is to use ``pip``::\r\n\r\n pip install minchin.releaser\r\n\r\nThis will also install all the other packages ``minchin.releaser`` depends\r\non.\r\n\r\nYou will also want to add ``minchin.releaser`` to the list of your\r\nproject's requirements.\r\n\r\nStep 2. Create a ``tasks.py`` file.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\nThis is where ``invoke`` determine was tasks are available to run. This file\r\nshould be created in the root folder of your project. If you are not using\r\n``invoke`` for other tasks, this file can be four lines:\r\n\r\n.. code-block:: python\r\n\r\n # tasks.py\r\n\r\n try:\r\n from minchin.releaser import make_release\r\n except ImportError:\r\n print(\"[WARN] minchin.releaser not installed.\")\r\n\r\n # your other Invoke tasks...\r\n\r\nTo confirm that this is working, go to the command line in the root folder\r\nof your project, and run:\r\n\r\n.. code-block:: sh\r\n\r\n $ invoke --list\r\n\r\nwhich will now list ``make-release`` as an available task.\r\n\r\nStep 3. Configure your project.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\nProject configuration is actually ``invoke`` configuration, so it is stored\r\nin the ``invoke.yaml`` folder in the project root (or anywhere else\r\n``invoke`` can load configuration from) under the ``releaser`` key.\r\n\r\nAvailable sub-keys:\r\n\r\nmodule_name\r\n (required) the name of your project. It is assumed that your project's\r\n version number is importable at ``module_name.__version__`` (see\r\n project assumptions).\r\npypi_name\r\n (optional) the name of your project as uploaded to PyPI. This only needs to\r\n be set if it differs from ``module_name``.\r\nhere\r\n (required) the base location to build your package from. To set to the\r\n current directory, set to ``.``\r\ndocs\r\n (required, but can be set to ``None``) the base documentation\r\n directory. This is relative to ``here``.\r\ntest\r\n (required, but can be set to ``None``) the base test directory. This is\r\n relative to ``here``.\r\nsource\r\n (required) the base directory of your Python source code. This is\r\n relative to ``here``.\r\nchangelog\r\n (required, but can be set to ``None``) the location of your changelog\r\n file. This is relative to ``here``.\r\nversion\r\n (required) the location of where your version string is stored. This is\r\n relative to ``here``.\r\ntest_command\r\n (required, but can be set to ``None``) command, run from the command\r\n line with the current directory set to ``here``, to run your test suite.\r\nversion_bump\r\n (optional) default *level* to bump your version. If set to ``none``,\r\n this will be requested at runtime. Valid options include ``major``,\r\n ``minor``, ``bug``, and ``none``.\r\nextra_packages\r\n (optional) Used to install packages before installing your module from\r\n the server. Useful particularly for packages that need to be installed\r\n from cache (rather than re-downloaded and compiled each time) or for\r\n packages that are not available on the test PyPI server. Valid server\r\n keys are ``local``, ``test``, and ``pypi``. Under the server key,\r\n create a list of the packages you want explicitly installed.\r\n\r\n(vendorize keys are not listed here.)\r\n\r\nStep 4. Set up Invoke command shell (Windows).\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\n.. Note::\r\n\r\n Recent version of ``invoke`` seem to have resolved this, and this not\r\n longer seems to be needed.\r\n\r\n*Minchin dot Releaser* runs certain commands at the command line. ``Invoke``,\r\nregardless of platform, tries to run these on ``/bin/bash`` which doesn't exist\r\nin Windows and thus these commands fail.\r\n\r\nTo fix this, create a ``.invoke.yaml`` file in the root of your user directory\r\n(so the file is ``C:\\Users\\<your_username>\\.invoke.yaml``) and add:\r\n\r\n.. code-block:: yaml\r\n\r\n run:\r\n shell: C:\\Windows\\system32\\CMD.exe\r\n\r\nStep 5. Set up twine configuration.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\nCreate or modify ``$HOME/.pypirc`` to include the ``testpypi`` server:\r\n\r\n.. code-block:: ini\r\n\r\n [distutils]\r\n index-servers=\r\n pypi\r\n testpypi\r\n\r\n [testpypi]\r\n repository: https://test.pypi.org/legacy/\r\n username: your testpypi username\r\n\r\n.. warning::\r\n\r\n Do not store passwords in the .pypirc file. Storing passwords in plain text\r\n is never a good idea.\r\n\r\n*Minchin dot Releaser* is automated, and so needs access to your password. This\r\ncan be done using ``keyring``. Keyring can be installed by ``pip`` and then\r\npasswords are added from the command-line.\r\n\r\n.. code-block:: sh\r\n\r\n $ pip install keyring\r\n $ keyring set https://test.pypi.org/legacy/ your-username\r\n $ keyring set https://upload.pypi.org/legacy/ your-username\r\n\r\nSee `Twine Keyring Support\r\n<https://twine.readthedocs.io/en/latest/#keyring-support>`_ for more details.\r\n\r\n\r\nStep 6. Register your package on PyPI.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\n(On the new infrastructure, this no longer needs to be done explicitly. Just\r\nupload your package.)\r\n\r\nStep 7. Upload your package.\r\n\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\"\r\n\r\n.. code-block:: sh\r\n\r\n $ invoke make-release\r\n\r\nAnd then work through the prompts. If this process breaks half-way through,\r\nyou can re-start.\r\n\r\nIn particular, many packages are not available on the test version of PyPI, and\r\nwill need to iteratively be added to the configuration under the\r\n``extra_packages\\test`` key.\r\n\r\n\r\nCredits\r\n-------\r\n\r\nInspired (in part) by\r\nhttps://hynek.me/articles/sharing-your-labor-of-love-pypi-quick-and-dirty/\r\n\r\n\r\nSample ``invoke.yaml``\r\n----------------------\r\n\r\n.. code-block:: yaml\r\n\r\n releaser:\r\n module_name: minchin.releaser\r\n here: .\r\n docs: .\r\n test: None\r\n source: minchin\r\n changelog: changelog.rst\r\n version: minchin\\releaser\\constants.py\r\n test_command: \"green -kq\"\r\n version_bump: none\r\n extra_packages:\r\n test:\r\n - gitdb\r\n - invoke\r\n - isort\r\n - pkginfo\r\n - semantic_version\r\n - twine\r\n - wheel\r\n pypi:\r\n - invoke\r\n vendor_dest: minchin\\releaser\\_vendor\r\n vendor_packages:\r\n \"minchin.text\":\r\n src: ..\\minchin.text\\minchin\r\n dest: .\r\n requirements: ..\\minchin.text\\requirements.in\r\n vendor_override_src: vendor_src\r\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Minchin.Releaser is a collection of tools designed to make releasing Python packages easier.",
"version": "0.9.1",
"project_urls": {
"Bug Tracker": "https://github.com/MinchinWeb/minchin.releaser/issues",
"Changelog": "https://github.com/MinchinWeb/minchin.releaser/blob/master/changelog.rst",
"Homepage": "https://github.com/MinchinWeb/minchin.releaser"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e28dc371120f9a9868413cde7c88a91e6b355f94b095478b7ced1c8b7d100665",
"md5": "7238b7dba1fe06766dbd69f46b778d91",
"sha256": "313f941c19c4a2349bb69a17ea63cbe611c8537915de7c4b4a75856511206865"
},
"downloads": -1,
"filename": "minchin.releaser-0.9.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "7238b7dba1fe06766dbd69f46b778d91",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 22896,
"upload_time": "2023-10-04T20:26:11",
"upload_time_iso_8601": "2023-10-04T20:26:11.076245Z",
"url": "https://files.pythonhosted.org/packages/e2/8d/c371120f9a9868413cde7c88a91e6b355f94b095478b7ced1c8b7d100665/minchin.releaser-0.9.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ed2594a2e4e6113801251cb4c6761b359917c22a0b484bccb2640c3698fbd048",
"md5": "ac0f4c5432c86f8dd2030f17a53c23e7",
"sha256": "be40e0df79d8867ae475e8794a8dd748618e8a096332f695319b40552e23062a"
},
"downloads": -1,
"filename": "minchin.releaser-0.9.1.tar.gz",
"has_sig": false,
"md5_digest": "ac0f4c5432c86f8dd2030f17a53c23e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 28504,
"upload_time": "2023-10-04T20:25:32",
"upload_time_iso_8601": "2023-10-04T20:25:32.248086Z",
"url": "https://files.pythonhosted.org/packages/ed/25/94a2e4e6113801251cb4c6761b359917c22a0b484bccb2640c3698fbd048/minchin.releaser-0.9.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-04 20:25:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "MinchinWeb",
"github_project": "minchin.releaser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "minchin.releaser"
}
JSON
