pyXcute
=======
.. image:: http://readthedocs.org/projects/pyxcute/badge/?version=latest
:target: http://pyxcute.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/eight04/pyXcute/actions/workflows/build.yml/badge.svg
:target: https://github.com/eight04/pyXcute/actions/workflows/build.yml
:alt: .github/workflows/build.yml
A small task runner inspired by npm scripts.
Features
--------
* Use it like setuptools.
* Chain tasks with ``_pre``, ``_err``, ``_post``, ``_fin`` suffix.
* A builtin Bump task which can bump version with `semver <https://github.com/k-bx/python-semver>`_.
* A small set of cross-platform CLI utils.
Installation
------------
From `pypi <https://pypi.org/project/pyxcute/>`__
.. code:: bash
pip install pyxcute
Usage
-----
Basic
~~~~~
Create a ``cute.py`` file:
.. code:: python
from xcute import cute
cute(
hello = 'echo hello xcute!'
)
then run:
.. code:: bash
$ cute hello
> Task: hello
> Cmd: echo hello xcute!
hello xcute!
..
If you got a "not a command" error, see `How do I make Python scripts executable? <https://docs.python.org/3/faq/windows.html#how-do-i-make-python-scripts-executable>`_)
"hello" is the name of the task that should be executed. If ``cute.py`` is executed without a task name, it will run the "default" task.
Provide additional arguments:
.. code:: bash
$ cute hello 123
> Task: hello
> Cmd: echo hello xcute! 123
hello xcute! 123
The arguments will be passed into the executor, which is ``xcute.Cmd.__call__`` in this case.
Tasks
~~~~~
It can be a str:
.. code:: python
from xcute import cute
cute(
hello = 'echo hello'
)
If it match the name of another task, pyxcute will execute that task:
.. code:: python
from xcute import cute
cute(
hello = 'world', # execute "world" task when "hello" task is executed
world = 'echo I am world task'
)
Use a list:
.. code:: python
from xcute import cute
cute(
hello = ['echo task1', 'echo task2']
)
Using an Exception would make the task fail:
.. code:: python
from xcute import cute
cute(
hello = Exception("error message")
)
Use anything that is callable:
.. code:: python
from xcute import cute
cute(
hello = lambda: print('say hello')
)
Actually, when you assign a non-callable value as a task, pyXcute converts it into a callable according to its type.
Task chain
~~~~~~~~~~
Define the workflow with ``_pre``, ``_err``, ``_post``, ``_fin`` suffix:
.. code:: python
from xcute import cute
cute(
hello_pre = 'echo _pre runs before the task',
hello = 'echo say hello',
hello_err = 'echo _err runs if there is an error in task, i.e, an uncaught exception or non-zero return code',
hello_post = 'echo _post runs after the task if task successfully returned',
hello_fin = 'echo _fin always runs after _post, _err just like finally'
)
When a task is executed, the task runner try to execute ``_pre`` task first, then the task itself, then the ``_post`` task. If the task raised an exception, then it goes to the ``_err`` task. ``_fin`` task would be executed whenever the task failed or not.
Pseudo code:
.. code:: python
run(name + "_pre")
try:
run(name, args)
except Exception:
run(name + "_err")
else:
run(name + "_post")
finally:
run(name + "_fin")
Format string
~~~~~~~~~~~~~
pyXcute expands the command string with ``xcute.conf`` dictionary. The expansion is happened at run-time:
.. code:: python
from xcute import conf, cute
conf["my_name"] = "world"
def change_my_name():
conf["my_name"] = "bad world"
cute(
hello = [
"echo hello {my_name}",
change_my_name,
"echo hello {my_name}"
]
)
.. code:: bash
$ cute hello
> Task: hello
> Cmd: echo hello world
hello world
> Cmd: echo hello bad world
hello bad world
Cross-platform utils
--------------------
There are some CLI utils inspired by `npm-build-tools <https://www.npmjs.com/package/npm-build-tools>`_, including:
* x-clean
* x-cat
* x-copy
* x-pipe
Run each command with ``-h`` to see the help message.
Live example
------------
Checkout `the cute file <https://github.com/eight04/pyXcute/blob/master/cute.py>`_ of pyXcute itself.
Documentation
-------------
http://pyxcute.readthedocs.io/en/latest/
Changelog
---------
* 0.8.0 (Feb 4, 2024)
- Change: drop natsort, implement filename sorting by ourselves.
* 0.7.0 (Oct 22, 2023)
- Change: now we only test pyxcute on Python>=3.7.
- Add: ``cfg`` argument in ``Bump``.
* 0.6.0 (Nov 1, 2019)
- Add: ``LiveReload``.
* 0.5.2 (Jun 14, 2018)
- Add: support ``bumper`` argument in ``Bump``.
- Add: support Python 3.4. Drop ``subprocess32``.
* 0.5.1 (May 12, 2018)
- Add: ``conf["py"]`` variable.
* 0.5.0 (May 11, 2018)
- Add: support Python 2.
- Add: documentation.
- Add: ``Skip``, ``run_task``, ``task_converter``.
- **Add: `Bump` task now update the version number inside `setup.cfg`.**
- Fix: ``Cmd`` task failed on Unix due to ``shell=True`` and passing ``args`` as a list.
- **Change: the command of `Cmd` is now logged. The log message is also changed.**
- **Drop: `noop`.**
* 0.4.1 (Apr 3, 2017)
- Better description for x-clean.
- Fix broken pipe error in x-pipe.
* 0.4.0 (Mar 28, 2017)
- Switch to setup.cfg.
- Add log, exc, noop, Throw, Try.
- **Drop Exc, Exit.**
- Add ``x-*`` utils.
* 0.3.1 (Mar 23, 2017)
- Find version from ``{pkg_name}/__pkginfo__.py``.
* 0.3.0 (Jul 21, 2016)
- Add ``pkg_name`` task.
- Add default tasks ``bump``, ``version``.
* 0.2.0 (May 14, 2016)
- Add _fin tag, which represent ``finally`` clause.
- Add Exc and Exit tasks.
* 0.1.2 (Apr 20, 2016)
- Move _pre out of try clause.
* 0.1.1 (Apr 20, 2016)
- Bump dev status.
* 0.1.0 (Apr 20, 2016)
- First release.
Raw data
{
"_id": null,
"home_page": "https://github.com/eight04/pyXcute",
"name": "pyxcute",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "run,task,runner,execute,bump,bumper,build,tool,npm",
"author": "eight",
"author_email": "eight04@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/b5/7d/794f57a18f40b15caa71d4ed77f6f3c3e0e53e7a97362e3d18ca95441b9f/pyxcute-0.8.1.tar.gz",
"platform": null,
"description": "pyXcute\r\n=======\r\n\r\n.. image:: http://readthedocs.org/projects/pyxcute/badge/?version=latest\r\n :target: http://pyxcute.readthedocs.io/en/latest/?badge=latest\r\n :alt: Documentation Status\r\n\r\n.. image:: https://github.com/eight04/pyXcute/actions/workflows/build.yml/badge.svg\r\n :target: https://github.com/eight04/pyXcute/actions/workflows/build.yml\r\n :alt: .github/workflows/build.yml\r\n\r\nA small task runner inspired by npm scripts.\r\n\r\nFeatures\r\n--------\r\n\r\n* Use it like setuptools.\r\n* Chain tasks with ``_pre``, ``_err``, ``_post``, ``_fin`` suffix.\r\n* A builtin Bump task which can bump version with `semver <https://github.com/k-bx/python-semver>`_.\r\n* A small set of cross-platform CLI utils.\r\n\r\nInstallation\r\n------------\r\n\r\nFrom `pypi <https://pypi.org/project/pyxcute/>`__\r\n\r\n.. code:: bash\r\n\r\n\tpip install pyxcute\r\n\r\nUsage\r\n-----\r\n\r\nBasic\r\n~~~~~\r\n\r\nCreate a ``cute.py`` file:\r\n\r\n.. code:: python\r\n\r\n from xcute import cute\r\n \r\n cute(\r\n hello = 'echo hello xcute!'\r\n )\r\n\t\r\nthen run:\r\n\r\n.. code:: bash\r\n\r\n $ cute hello\r\n > Task: hello\r\n > Cmd: echo hello xcute!\r\n hello xcute!\r\n\t\r\n..\r\n \r\n If you got a \"not a command\" error, see `How do I make Python scripts executable? <https://docs.python.org/3/faq/windows.html#how-do-i-make-python-scripts-executable>`_)\r\n\r\n\"hello\" is the name of the task that should be executed. If ``cute.py`` is executed without a task name, it will run the \"default\" task.\r\n\t\r\nProvide additional arguments:\r\n\r\n.. code:: bash\r\n\r\n $ cute hello 123\r\n > Task: hello\r\n > Cmd: echo hello xcute! 123\r\n hello xcute! 123\r\n\r\nThe arguments will be passed into the executor, which is ``xcute.Cmd.__call__`` in this case.\r\n\r\nTasks\r\n~~~~~\r\n\r\nIt can be a str:\r\n\r\n.. code:: python\r\n\t\r\n from xcute import cute\r\n\r\n cute(\r\n hello = 'echo hello'\r\n )\r\n\t\r\nIf it match the name of another task, pyxcute will execute that task:\r\n\r\n.. code:: python\r\n\r\n from xcute import cute\r\n\r\n cute(\r\n hello = 'world', # execute \"world\" task when \"hello\" task is executed\r\n world = 'echo I am world task'\r\n )\r\n\t\r\nUse a list:\r\n\r\n.. code:: python\r\n\r\n from xcute import cute\r\n \r\n cute(\r\n hello = ['echo task1', 'echo task2']\r\n )\r\n \r\nUsing an Exception would make the task fail:\r\n\r\n.. code:: python\r\n\r\n from xcute import cute\r\n cute(\r\n hello = Exception(\"error message\")\r\n )\r\n\t\r\nUse anything that is callable:\r\n\r\n.. code:: python\r\n\r\n from xcute import cute\r\n\r\n cute(\r\n hello = lambda: print('say hello')\r\n )\r\n \r\nActually, when you assign a non-callable value as a task, pyXcute converts it into a callable according to its type.\r\n\r\nTask chain\r\n~~~~~~~~~~\r\n\t\r\nDefine the workflow with ``_pre``, ``_err``, ``_post``, ``_fin`` suffix:\r\n\r\n.. code:: python\r\n\r\n\tfrom xcute import cute\r\n\t\r\n\tcute(\r\n\t\thello_pre = 'echo _pre runs before the task',\r\n\t\thello = 'echo say hello',\r\n\t\thello_err = 'echo _err runs if there is an error in task, i.e, an uncaught exception or non-zero return code',\r\n\t\thello_post = 'echo _post runs after the task if task successfully returned',\r\n\t\thello_fin = 'echo _fin always runs after _post, _err just like finally'\r\n\t)\r\n\t\r\nWhen a task is executed, the task runner try to execute ``_pre`` task first, then the task itself, then the ``_post`` task. If the task raised an exception, then it goes to the ``_err`` task. ``_fin`` task would be executed whenever the task failed or not.\r\n\r\nPseudo code:\r\n\r\n.. code:: python\r\n\r\n\trun(name + \"_pre\")\r\n\ttry:\r\n\t\trun(name, args)\r\n\texcept Exception:\r\n\t\trun(name + \"_err\")\r\n\telse:\r\n\t\trun(name + \"_post\")\r\n\tfinally:\r\n\t\trun(name + \"_fin\")\r\n\r\nFormat string\r\n~~~~~~~~~~~~~\r\n\r\npyXcute expands the command string with ``xcute.conf`` dictionary. The expansion is happened at run-time:\r\n\r\n.. code:: python\r\n\r\n from xcute import conf, cute\r\n \r\n conf[\"my_name\"] = \"world\"\r\n \r\n def change_my_name():\r\n conf[\"my_name\"] = \"bad world\"\r\n\r\n cute(\r\n hello = [\r\n \"echo hello {my_name}\",\r\n change_my_name,\r\n \"echo hello {my_name}\"\r\n ]\r\n )\r\n \r\n.. code:: bash\r\n\r\n $ cute hello\r\n > Task: hello\r\n > Cmd: echo hello world\r\n hello world\r\n > Cmd: echo hello bad world\r\n hello bad world\r\n \r\nCross-platform utils\r\n--------------------\r\n\r\nThere are some CLI utils inspired by `npm-build-tools <https://www.npmjs.com/package/npm-build-tools>`_, including:\r\n\r\n* x-clean\r\n* x-cat\r\n* x-copy\r\n* x-pipe\r\n\r\nRun each command with ``-h`` to see the help message.\r\n\r\nLive example\r\n------------\r\n\t\r\nCheckout `the cute file <https://github.com/eight04/pyXcute/blob/master/cute.py>`_ of pyXcute itself.\r\n\r\nDocumentation\r\n-------------\r\n\r\nhttp://pyxcute.readthedocs.io/en/latest/\r\n \r\nChangelog\r\n---------\r\n\r\n* 0.8.0 (Feb 4, 2024)\r\n\r\n - Change: drop natsort, implement filename sorting by ourselves.\r\n\r\n* 0.7.0 (Oct 22, 2023)\r\n\r\n - Change: now we only test pyxcute on Python>=3.7.\r\n - Add: ``cfg`` argument in ``Bump``.\r\n\r\n* 0.6.0 (Nov 1, 2019)\r\n\r\n - Add: ``LiveReload``.\r\n\r\n* 0.5.2 (Jun 14, 2018)\r\n\r\n - Add: support ``bumper`` argument in ``Bump``.\r\n - Add: support Python 3.4. Drop ``subprocess32``.\r\n\r\n* 0.5.1 (May 12, 2018)\r\n\r\n - Add: ``conf[\"py\"]`` variable.\r\n\r\n* 0.5.0 (May 11, 2018)\r\n\r\n - Add: support Python 2.\r\n - Add: documentation.\r\n - Add: ``Skip``, ``run_task``, ``task_converter``.\r\n - **Add: `Bump` task now update the version number inside `setup.cfg`.**\r\n - Fix: ``Cmd`` task failed on Unix due to ``shell=True`` and passing ``args`` as a list.\r\n - **Change: the command of `Cmd` is now logged. The log message is also changed.**\r\n - **Drop: `noop`.**\r\n\r\n* 0.4.1 (Apr 3, 2017)\r\n\r\n - Better description for x-clean.\r\n - Fix broken pipe error in x-pipe.\r\n\r\n* 0.4.0 (Mar 28, 2017)\r\n\r\n - Switch to setup.cfg.\r\n - Add log, exc, noop, Throw, Try.\r\n - **Drop Exc, Exit.**\r\n - Add ``x-*`` utils.\r\n\r\n* 0.3.1 (Mar 23, 2017)\r\n\r\n - Find version from ``{pkg_name}/__pkginfo__.py``.\r\n\r\n* 0.3.0 (Jul 21, 2016)\r\n\r\n - Add ``pkg_name`` task.\r\n - Add default tasks ``bump``, ``version``.\r\n\r\n* 0.2.0 (May 14, 2016)\r\n\r\n - Add _fin tag, which represent ``finally`` clause.\r\n - Add Exc and Exit tasks.\r\n\r\n* 0.1.2 (Apr 20, 2016)\r\n\r\n - Move _pre out of try clause.\r\n\r\n* 0.1.1 (Apr 20, 2016)\r\n\r\n - Bump dev status.\r\n\r\n* 0.1.0 (Apr 20, 2016)\r\n\r\n - First release.\r\n\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A small task runner inspired by npm scripts.",
"version": "0.8.1",
"project_urls": {
"Homepage": "https://github.com/eight04/pyXcute"
},
"split_keywords": [
"run",
"task",
"runner",
"execute",
"bump",
"bumper",
"build",
"tool",
"npm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "986789acc3bcce47edc6ec60b6f90a6ab1b362211614f3e771dbf8a9a871dbf9",
"md5": "a513f038e84c8d408985b2bb3c178fdc",
"sha256": "35a7283edadf6166a985c28a7c39fe69d15e583c8e59143beb7fb488983771d1"
},
"downloads": -1,
"filename": "pyxcute-0.8.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a513f038e84c8d408985b2bb3c178fdc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 12126,
"upload_time": "2024-02-03T17:39:12",
"upload_time_iso_8601": "2024-02-03T17:39:12.790808Z",
"url": "https://files.pythonhosted.org/packages/98/67/89acc3bcce47edc6ec60b6f90a6ab1b362211614f3e771dbf8a9a871dbf9/pyxcute-0.8.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b57d794f57a18f40b15caa71d4ed77f6f3c3e0e53e7a97362e3d18ca95441b9f",
"md5": "46942b84813db189d3b493832d2a3a4e",
"sha256": "a35929ec27cb7a5f34aaf54beca56b370eabc224d020ea3c24c37888d6311a13"
},
"downloads": -1,
"filename": "pyxcute-0.8.1.tar.gz",
"has_sig": false,
"md5_digest": "46942b84813db189d3b493832d2a3a4e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12121,
"upload_time": "2024-02-03T17:39:15",
"upload_time_iso_8601": "2024-02-03T17:39:15.151127Z",
"url": "https://files.pythonhosted.org/packages/b5/7d/794f57a18f40b15caa71d4ed77f6f3c3e0e53e7a97362e3d18ca95441b9f/pyxcute-0.8.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 17:39:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eight04",
"github_project": "pyXcute",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "pyxcute"
}
JSON
