`CLU <https://tron.fandom.com/wiki/Clu>`__
==========================================
|py| |pypi| |black| |Build Status| |docs| |Coverage Status| |zenodo|
`CLU <https://tron.fandom.com/wiki/Clu>`_ implements a new protocol for SDSS actor while providing support for legacy-style actor.
Features
--------
- Asynchronous API based on `asyncio <https://docs.python.org/3/library/asyncio.html>`_.
- New-style actor with message passing based on `AMQP <https://www.amqp.org/>`_ and `RabbitMQ <https://rabbitmq.com>`_.
- Legacy-style actor for TCP socket communication via `tron <https://github.com/sdss/tron>`__.
- Tools for device handling.
- Messages are validated JSON strings.
- `click <https://click.palletsprojects.com/en/7.x/>`__-enabled command parser.
Installation
------------
``CLU`` can be installed using ``pip`` as
.. code-block:: console
pip install sdss-clu
or from source
.. code-block:: console
git clone https://github.com/sdss/clu
cd clu
pip install .
Development
^^^^^^^^^^^
``clu`` uses `poetry <http://poetry.eustace.io/>`__ for dependency management and packaging. To work with an editable install it's recommended that you setup ``poetry`` and install ``clu`` in a virtual environment by doing
.. code-block:: console
poetry install
Pip does not support editable installs with PEP-517 yet. That means that running ``pip install -e .`` will fail because ``poetry`` doesn't use a ``setup.py`` file. As a workaround, you can use the ``create_setup.py`` file to generate a temporary ``setup.py`` file. To install ``clu`` in editable mode without ``poetry``, do
.. code-block:: console
pip install --pre poetry
pip install -U setuptools
python create_setup.py
pip install -e .
Quick start
-----------
Creating a new actor with ``CLU`` is easy. To instantiate and run an actor you can simply do
.. code-block:: python
import asyncio
from clu import AMQPActor
async def main(loop):
actor = await Actor('my_actor').start()
await actor.run_forever()
asyncio.run(main(loop))
Next, head to the `Getting started <https://clu.readthedocs.io/en/latest/getting-started.html>`__ section for more information about using actors. More examples are available `here <https://clu.readthedocs.io/en/latest/examples.html>`__.
Why a new messaging protocol for SDSS?
--------------------------------------
Say whatever you want about it, the `current SDSS message passing protocol <https://clu.readthedocs.io/en/latest/legacy.html>`_ based on ``Tron``, ``opscore``, and ``actorcore`` is stable and robust. So, why should we replace it? Here is a list of reasons:
- It reinvents the wheel. Ok, in all honesty ``Tron`` and ``opscore`` were written when wheel were still not completely circular, but the truth is that nowadays there are more robust, standard, and better documented technologies out there for message passing.
- We can remove the need for a central hub product by relying in open-source message brokers such as `RabbitMQ <https://rabbitmq.com>`__.
- ``Tron`` and ``opscore`` are Python 2 and it's unclear the amount of effort that would be needed to convert them to Python 3.
- While there is some documentation for ``Tron`` and ``opscore``, and the code is well written, it's also cumbersome and difficult to modify by people that didn't write it. It's ultimately non-maintainable.
- The ``opsctore``/``actorkeys`` datamodel is custom-built and extremely difficult to maintain. Standard solutions such as JSON with a `JSON schema <https://json-schema.org/>`__ validator should be preferred.
- `asyncio <https://docs.python.org/3/library/asyncio.html>`__ provides an asynchronous API that is cleaner and easier to code than using threads. It is also more readable and less convoluted than `twisted <https://twistedmatrix.com/trac/>`__ and it's a Python core library with very active development.
- CLU uses `click <https://click.palletsprojects.com/en/7.x>`__ for parsing commands, providing a well-defined, easy to use parser.
.. |Build Status| image:: https://github.com/sdss/clu/actions/workflows/test.yml/badge.svg
:alt: Build Status
:target: https://github.com/sdss/clu/actions
.. |Coverage Status| image:: https://codecov.io/gh/sdss/clu/graph/badge.svg?token=HMjFocCIql
:alt: Coverage Status
:target: https://codecov.io/gh/sdss/clu
.. |py| image:: https://img.shields.io/badge/python-%3E=3.8-blue
:alt: Python Versions
:target: https://docs.python.org/3/
.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest
:alt: Documentation Status
:target: https://clu.readthedocs.io/en/latest/?badge=latest
.. |pypi| image:: https://badge.fury.io/py/sdss-clu.svg
:alt: PyPI version
:target: https://badge.fury.io/py/sdss-clu
.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
.. |zenodo| image:: https://zenodo.org/badge/183817446.svg
:target: https://zenodo.org/badge/latestdoi/183817446
Raw data
{
"_id": null,
"home_page": "https://github.com/sdss/clu",
"name": "sdss-clu",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "",
"keywords": "astronomy,software",
"author": "Jos\u00e9 S\u00e1nchez-Gallego",
"author_email": "gallegoj@uw.edu",
"download_url": "https://files.pythonhosted.org/packages/4e/8b/1ca6c78a40014f65f6c17ffd294b292115d5feb3ecea1e8584c8052fd368/sdss_clu-2.2.3.tar.gz",
"platform": null,
"description": "`CLU <https://tron.fandom.com/wiki/Clu>`__\n==========================================\n\n|py| |pypi| |black| |Build Status| |docs| |Coverage Status| |zenodo|\n\n\n`CLU <https://tron.fandom.com/wiki/Clu>`_ implements a new protocol for SDSS actor while providing support for legacy-style actor.\n\n\nFeatures\n--------\n\n- Asynchronous API based on `asyncio <https://docs.python.org/3/library/asyncio.html>`_.\n- New-style actor with message passing based on `AMQP <https://www.amqp.org/>`_ and `RabbitMQ <https://rabbitmq.com>`_.\n- Legacy-style actor for TCP socket communication via `tron <https://github.com/sdss/tron>`__.\n- Tools for device handling.\n- Messages are validated JSON strings.\n- `click <https://click.palletsprojects.com/en/7.x/>`__-enabled command parser.\n\n\nInstallation\n------------\n\n``CLU`` can be installed using ``pip`` as\n\n.. code-block:: console\n\n pip install sdss-clu\n\nor from source\n\n.. code-block:: console\n\n git clone https://github.com/sdss/clu\n cd clu\n pip install .\n\n\nDevelopment\n^^^^^^^^^^^\n\n``clu`` uses `poetry <http://poetry.eustace.io/>`__ for dependency management and packaging. To work with an editable install it's recommended that you setup ``poetry`` and install ``clu`` in a virtual environment by doing\n\n.. code-block:: console\n\n poetry install\n\nPip does not support editable installs with PEP-517 yet. That means that running ``pip install -e .`` will fail because ``poetry`` doesn't use a ``setup.py`` file. As a workaround, you can use the ``create_setup.py`` file to generate a temporary ``setup.py`` file. To install ``clu`` in editable mode without ``poetry``, do\n\n.. code-block:: console\n\n pip install --pre poetry\n pip install -U setuptools\n python create_setup.py\n pip install -e .\n\n\nQuick start\n-----------\n\nCreating a new actor with ``CLU`` is easy. To instantiate and run an actor you can simply do\n\n.. code-block:: python\n\n import asyncio\n from clu import AMQPActor\n\n async def main(loop):\n actor = await Actor('my_actor').start()\n await actor.run_forever()\n\n asyncio.run(main(loop))\n\nNext, head to the `Getting started <https://clu.readthedocs.io/en/latest/getting-started.html>`__ section for more information about using actors. More examples are available `here <https://clu.readthedocs.io/en/latest/examples.html>`__.\n\n\nWhy a new messaging protocol for SDSS?\n--------------------------------------\n\nSay whatever you want about it, the `current SDSS message passing protocol <https://clu.readthedocs.io/en/latest/legacy.html>`_ based on ``Tron``, ``opscore``, and ``actorcore`` is stable and robust. So, why should we replace it? Here is a list of reasons:\n\n- It reinvents the wheel. Ok, in all honesty ``Tron`` and ``opscore`` were written when wheel were still not completely circular, but the truth is that nowadays there are more robust, standard, and better documented technologies out there for message passing.\n- We can remove the need for a central hub product by relying in open-source message brokers such as `RabbitMQ <https://rabbitmq.com>`__.\n- ``Tron`` and ``opscore`` are Python 2 and it's unclear the amount of effort that would be needed to convert them to Python 3.\n- While there is some documentation for ``Tron`` and ``opscore``, and the code is well written, it's also cumbersome and difficult to modify by people that didn't write it. It's ultimately non-maintainable.\n- The ``opsctore``/``actorkeys`` datamodel is custom-built and extremely difficult to maintain. Standard solutions such as JSON with a `JSON schema <https://json-schema.org/>`__ validator should be preferred.\n- `asyncio <https://docs.python.org/3/library/asyncio.html>`__ provides an asynchronous API that is cleaner and easier to code than using threads. It is also more readable and less convoluted than `twisted <https://twistedmatrix.com/trac/>`__ and it's a Python core library with very active development.\n- CLU uses `click <https://click.palletsprojects.com/en/7.x>`__ for parsing commands, providing a well-defined, easy to use parser.\n\n\n.. |Build Status| image:: https://github.com/sdss/clu/actions/workflows/test.yml/badge.svg\n :alt: Build Status\n :target: https://github.com/sdss/clu/actions\n\n.. |Coverage Status| image:: https://codecov.io/gh/sdss/clu/graph/badge.svg?token=HMjFocCIql\n :alt: Coverage Status\n :target: https://codecov.io/gh/sdss/clu\n\n.. |py| image:: https://img.shields.io/badge/python-%3E=3.8-blue\n :alt: Python Versions\n :target: https://docs.python.org/3/\n\n.. |docs| image:: https://readthedocs.org/projects/docs/badge/?version=latest\n :alt: Documentation Status\n :target: https://clu.readthedocs.io/en/latest/?badge=latest\n\n.. |pypi| image:: https://badge.fury.io/py/sdss-clu.svg\n :alt: PyPI version\n :target: https://badge.fury.io/py/sdss-clu\n\n.. |black| image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n\n.. |zenodo| image:: https://zenodo.org/badge/183817446.svg\n :target: https://zenodo.org/badge/latestdoi/183817446\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "A new protocol for SDSS actors.",
"version": "2.2.3",
"project_urls": {
"Documentation": "https://clu.readthedocs.io/en/latest/",
"Homepage": "https://github.com/sdss/clu",
"Repository": "https://github.com/sdss/clu"
},
"split_keywords": [
"astronomy",
"software"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80adc1469aee2eb1986bf23aa524c2aa5e1c126c7c780dd31ca46bd2e4a0f877",
"md5": "ff9df1cd692e3b0ae2dd4ad9e22f0bf5",
"sha256": "dc374df9c6293a5ba1ba34e53f40fe7625fccd1c7be67d91fb5c3d1ad659475e"
},
"downloads": -1,
"filename": "sdss_clu-2.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff9df1cd692e3b0ae2dd4ad9e22f0bf5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 142264,
"upload_time": "2024-01-20T19:08:06",
"upload_time_iso_8601": "2024-01-20T19:08:06.180065Z",
"url": "https://files.pythonhosted.org/packages/80/ad/c1469aee2eb1986bf23aa524c2aa5e1c126c7c780dd31ca46bd2e4a0f877/sdss_clu-2.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4e8b1ca6c78a40014f65f6c17ffd294b292115d5feb3ecea1e8584c8052fd368",
"md5": "9e8be8f48618c60e7107803ae4cd55d1",
"sha256": "743b14429c0c6564e7c6e73f9f9bdedaf04bbe5c07fa83c2494ab1e4617d3572"
},
"downloads": -1,
"filename": "sdss_clu-2.2.3.tar.gz",
"has_sig": false,
"md5_digest": "9e8be8f48618c60e7107803ae4cd55d1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 126938,
"upload_time": "2024-01-20T19:08:08",
"upload_time_iso_8601": "2024-01-20T19:08:08.898867Z",
"url": "https://files.pythonhosted.org/packages/4e/8b/1ca6c78a40014f65f6c17ffd294b292115d5feb3ecea1e8584c8052fd368/sdss_clu-2.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-20 19:08:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sdss",
"github_project": "clu",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sdss-clu"
}
JSON
