Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/omnilib/thx

Simple, composable command runner for Python projects
https://github.com/omnilib/thx

command-runner python task-runner

Last synced: 5 days ago
JSON representation

Simple, composable command runner for Python projects

Awesome Lists containing this project

README 

        
thx

===



Rapid development assistant, and fast command runner for Python projects.



.. image:: https://img.shields.io/pypi/v/thx.svg

   :target: https://pypi.org/project/thx

   :alt: PyPI Release

.. image:: https://readthedocs.org/projects/thx/badge/?version=stable

   :target: https://thx.readthedocs.io/

   :alt: Documentation Status

.. image:: https://img.shields.io/badge/change-log-blue

   :target: https://github.com/omnilib/thx/blob/main/CHANGELOG.md

   :alt: Changelog

.. image:: https://img.shields.io/pypi/l/thx.svg

   :target: https://github.com/omnilib/thx/blob/main/LICENSE

   :alt: MIT Licensed



`thx` ("thanks") is capable of running arbitrary jobs, configured via simple options

in the `PEP 518 `_ standardized ``pyproject.toml``.

Jobs can be run on multiple Python versions at once, and independent steps can be

executed in parallel for faster results.



Watch `thx` format the codebase, build sphinx docs, run the test and linter suites on

five Python versions, and generate a final coverage report:



.. image:: https://asciinema.org/a/ZoT8qYbQ2g8wl1FrR9JSpRqRZ.svg

    :target: https://asciinema.org/a/ZoT8qYbQ2g8wl1FrR9JSpRqRZ

    :alt: Demo of thx



`thx` can also watch for modifications to your project, and automatically run jobs

every time changes are detected—it will even reload its configuration when your

``pyproject.toml`` changes:



.. image:: https://asciinema.org/a/uE79pfl07YzTiDmGnNzgY1GWG.svg

    :target: https://asciinema.org/a/uE79pfl07YzTiDmGnNzgY1GWG

    :alt: Demo of thx in watch mode



Usage

-----



Configuration uses standard `TOML `_ elements, and jobs can

reference shared values, which will be interpolated at runtime:



.. code-block:: toml



    [tool.thx.values]

    module = "thx"



    [tool.thx.jobs]

    lint = [

        "flake8 {module}",

        "ufmt check {module}",

    ]

    test = "python -m unittest -v {module}.tests"



The configuration above defines two jobs, "lint" and "test"; the "lint" job defines

two steps, and these can optionally be run in parallel. Both jobs present themselves

as separate commands in `thx`. Note the automatic replacement of ``{module}`` with

the configured value ``thx`` when running jobs:



.. code-block:: shell-session



    $ thx lint

    > flake8 thx

    > ufmt check thx



.. code-block:: shell-session



    $ thx test

    > python -m unittest thx.tests



They can also be run together in order, similar to `makefiles`:



.. code-block:: shell-session

    

    $ thx test lint

    > python -m unittest thx.tests

    > flake8 thx

    > ufmt check thx



By default, `thx` uses the active Python runtime for jobs, but can also run jobs on 

multiple runtimes in parallel:



.. code-block:: toml



    [tool.thx]

    python_versions = ["3.7", "3.8", "3.9"]



.. code-block:: shell-session



    $ thx test

    3.9> python -m unittest thx.tests

    3.8> python -m unittest thx.tests

    3.7> python -m unittest thx.tests



See the `user guide `_ for details on all available

configuration options.



Install

-------



.. note::



    `thx` is still in active development. Configuration options should be stable, but

    compatibility between minor releases is not guaranteed. For important production

    cases, please be sure to pin yourself to a single version, and test any new releases

    thoroughly.



`thx` is available on `PyPI `_:



.. code-block:: shell-session



    $ pip install thx



See the `user guide `_ for help getting started.



License

-------



`thx` is copyright `Amethyst Reese `_, and licensed under

the MIT license. I am providing code in this repository to you under an open

source license. This is my personal repository; the license you receive to my

code is from me and not from my employer. See the `LICENSE`_ file for details.



.. _LICENSE: https://github.com/omnilib/thx/blob/main/LICENSE