|pypi| |build status| |pyver| |huckle| |hc| |hg|
HCLI Core
=========
An HCLI Connector that can be used to expose a REST API with a built-in CLI, via hypertext
command line interface (HCLI) semantics.
----
HCLI Core implements an HCLI Connector, a type of Service Connector, as a WSGI application and provides a way
for developers to expose a service hosted CLI, as a REST API, via HCLI semantics. Such an API exposes a "built-in"
CLI that can be interacted with dynamically with any HCLI client. Up to date, in-band, man page style API/CLI
documentation is readily available for use to help understand how to interact with the API.
Most, if not all, programming languages have a way to issue shell commands. With the help
of a generic HCLI client, such as Huckle [1], APIs that make use of HCLI semantics are readily consumable
anywhere via the familiar command line (CLI) mode of operation, and this, without there being a need to write
a custom and dedicated CLI to interact with a specific HCLI API.
You can find out more about HCLI on hcli.io [2]
The HCLI Internet-Draft [3] is a work in progress by the author and
the current implementation leverages hal+json alongside a static form of ALPS
(semantic profile) [4] to help enable widespread cross media-type support.
Help shape HCLI and it's ecosystem by raising issues on github!
[1] https://github.com/cometaj2/huckle
[2] http://hcli.io
[3] https://github.com/cometaj2/I-D/tree/master/hcli
[4] http://alps.io
Related HCLI Projects
---------------------
- hcli-hc, a python package for an HCL (hc) that can act both as a gcode streamer (e.g. for OpenBuilds Blackbox controller v1.1g) and CNC interface. In other words, this HCLI acts in the same capacity as the OpenBuilds CONTROL software and OpenBuilds Interface CNC Touch hardware to help control a GRBL v1.1g controlled CNC. [5]
- hcli-hg, a python package wrapper for an HCLI (hg) that can interact with GPT-3.5-Turbo via terminal input and output streams. [6]
[5] https://github.com/cometaj2/hcli_hc
[6] https://github.com/cometaj2/hcli_hg
Installation
------------
hcli_core requires a supported version of Python and pip.
You'll need an WSGI compliant application server to run hcli_core. For example, you can use Green Unicorn (https://gunicorn.org/), and an
HCLI client such as Huckle (https://github.com/cometaj2/huckle). The following runs the default *jsonf* HCLI bundled with HCLI Core.
.. code-block:: console
pip install hcli-core
pip install gunicorn
pip install huckle
gunicorn --workers=5 --threads=2 -b 127.0.0.1:8000 --chdir `hcli_core path` "hcli_core:connector()"
Usage
-----
Open a different shell window.
Setup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. jsonf).
Note that no CLI is actually installed by Huckle. Huckle reads the HCLI semantics exposed by the API and ends up behaving *like* the CLI it targets.
.. code-block:: console
huckle cli install http://127.0.0.1:8000
eval $(huckle env)
jsonf help
3rd Party HCLI Installation
---------------------------
If you want to load a sample HCLI other than the default sample application, you can try loading one of the other sample HCLIs
developped independently of HCLI Core. For example, the *hc* HCLI (hypertext GPT-3.5-Turbo command line chat application).
A folder path to any other 3rd party HCLI can be provided in the same way to the HCLI Connector, provided the 3rd party HCLI meets
CLI interface (cli.py) and HCLI template (template.json) requirements:
.. code-block:: console
pip install hcli-hg
pip install hcli-core
pip install gunicorn
pip install huckle
gunicorn --workers=5 --threads=2 "hcli_core:connector(\"`hcli_hg path`\")"
3rd Party HCLI Usage
--------------------
Open a different shell window.
Setup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. hg).
.. code-block:: console
huckle cli install http://127.0.0.1:8000
eval $(huckle env)
hg help
Versioning
----------
This project makes use of semantic versioning (http://semver.org) and may make use of the "devx",
"prealphax", "alphax" "betax", and "rcx" extensions where x is a number (e.g. 0.3.0-prealpha1)
on github. Only full major.minor.patch releases will be pushed to pip from now on.
Supports
--------
- HTTP/HTTPS.
- HCLI version 1.0 server semantics for hal+json
- Web Server Gateway Interface (WSGI) through PEP 3333 and Falcon.
- Bundled Sample HCLIs:
- jsonf - a simple formatter for JSON.
- hfm - a file upload and download manager that works with \*nix terminal shell input and output streams.
- hptt - a rudimentary HCLI Push To Talk (PTT) channel management service.
- hub - a rudimentary HCLI service discovery hub.
- nw - a flexible IP Address Management (IPAM) service.
- Support for use of any 3rd party HCLI code that meets CLI interface requirements and HCLI template requirements (i.e. see sample HCLIs).
- Support large input and output streams as application/octet-stream.
To Do
-----
- Automated tests for all bundled HCLI samples.
- Separate out HCLI applications from HCLI Core to help avoid application dependencies bleeding onto HCLI Core.
Bugs
----
- No good handling of control over request and response in cli code which can lead to exceptions and empty response client side.
- The hfm sample HCLI fails disgracefully when copying a remote file name that doesn't exist (server error).
.. |build status| image:: https://circleci.com/gh/cometaj2/hcli_core.svg?style=shield
:target: https://circleci.com/gh/cometaj2/hcli_core
.. |pypi| image:: https://img.shields.io/pypi/v/hcli-core?label=hcli-core
:target: https://pypi.org/project/hcli-core
.. |pyver| image:: https://img.shields.io/pypi/pyversions/hcli-core.svg
:target: https://pypi.org/project/hcli-core
.. |huckle| image:: https://img.shields.io/pypi/v/huckle?label=huckle
:target: https://pypi.org/project/huckle
.. |hc| image:: https://img.shields.io/pypi/v/hcli-hc?label=hcli-hc
:target: https://pypi.org/project/hcli-hc
.. |hg| image:: https://img.shields.io/pypi/v/hcli-hg?label=hcli-hg
:target: https://pypi.org/project/hcli-hg
Raw data
{
"_id": null,
"home_page": "https://github.com/cometaj2/hcli_core",
"name": "hcli-core",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "cli client server connector hypermedia rest generic development",
"author": "Jeff Michaud",
"author_email": "cometaj2@comcast.net",
"download_url": "https://files.pythonhosted.org/packages/48/31/13b607e95df3b6963472a9f1722b5aad2b159b5992eba3f3ada1e59710e6/hcli_core-0.20.2.tar.gz",
"platform": null,
"description": "|pypi| |build status| |pyver| |huckle| |hc| |hg|\n\nHCLI Core\n=========\n\nAn HCLI Connector that can be used to expose a REST API with a built-in CLI, via hypertext\ncommand line interface (HCLI) semantics.\n\n----\n\nHCLI Core implements an HCLI Connector, a type of Service Connector, as a WSGI application and provides a way\nfor developers to expose a service hosted CLI, as a REST API, via HCLI semantics. Such an API exposes a \"built-in\"\nCLI that can be interacted with dynamically with any HCLI client. Up to date, in-band, man page style API/CLI\ndocumentation is readily available for use to help understand how to interact with the API.\n\nMost, if not all, programming languages have a way to issue shell commands. With the help\nof a generic HCLI client, such as Huckle [1], APIs that make use of HCLI semantics are readily consumable\nanywhere via the familiar command line (CLI) mode of operation, and this, without there being a need to write\na custom and dedicated CLI to interact with a specific HCLI API.\n\nYou can find out more about HCLI on hcli.io [2]\n\nThe HCLI Internet-Draft [3] is a work in progress by the author and \nthe current implementation leverages hal+json alongside a static form of ALPS\n(semantic profile) [4] to help enable widespread cross media-type support.\n\nHelp shape HCLI and it's ecosystem by raising issues on github!\n\n[1] https://github.com/cometaj2/huckle\n\n[2] http://hcli.io\n\n[3] https://github.com/cometaj2/I-D/tree/master/hcli\n\n[4] http://alps.io\n\nRelated HCLI Projects\n---------------------\n\n- hcli-hc, a python package for an HCL (hc) that can act both as a gcode streamer (e.g. for OpenBuilds Blackbox controller v1.1g) and CNC interface. In other words, this HCLI acts in the same capacity as the OpenBuilds CONTROL software and OpenBuilds Interface CNC Touch hardware to help control a GRBL v1.1g controlled CNC. [5]\n\n- hcli-hg, a python package wrapper for an HCLI (hg) that can interact with GPT-3.5-Turbo via terminal input and output streams. [6]\n\n[5] https://github.com/cometaj2/hcli_hc\n\n[6] https://github.com/cometaj2/hcli_hg\n\nInstallation\n------------\n\nhcli_core requires a supported version of Python and pip.\n\nYou'll need an WSGI compliant application server to run hcli_core. For example, you can use Green Unicorn (https://gunicorn.org/), and an\nHCLI client such as Huckle (https://github.com/cometaj2/huckle). The following runs the default *jsonf* HCLI bundled with HCLI Core.\n\n\n.. code-block:: console\n\n pip install hcli-core\n pip install gunicorn\n pip install huckle\n gunicorn --workers=5 --threads=2 -b 127.0.0.1:8000 --chdir `hcli_core path` \"hcli_core:connector()\"\n\nUsage\n-----\n\nOpen a different shell window.\n\nSetup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. jsonf).\n\nNote that no CLI is actually installed by Huckle. Huckle reads the HCLI semantics exposed by the API and ends up behaving *like* the CLI it targets.\n\n\n.. code-block:: console\n\n huckle cli install http://127.0.0.1:8000\n eval $(huckle env)\n jsonf help\n\n3rd Party HCLI Installation\n---------------------------\n\nIf you want to load a sample HCLI other than the default sample application, you can try loading one of the other sample HCLIs\ndevelopped independently of HCLI Core. For example, the *hc* HCLI (hypertext GPT-3.5-Turbo command line chat application).\n\nA folder path to any other 3rd party HCLI can be provided in the same way to the HCLI Connector, provided the 3rd party HCLI meets\nCLI interface (cli.py) and HCLI template (template.json) requirements:\n\n.. code-block:: console\n\n pip install hcli-hg\n pip install hcli-core\n pip install gunicorn\n pip install huckle\n gunicorn --workers=5 --threads=2 \"hcli_core:connector(\\\"`hcli_hg path`\\\")\"\n\n3rd Party HCLI Usage\n--------------------\n\nOpen a different shell window.\n\nSetup the huckle env eval in your .bash_profile (or other bash configuration) to avoid having to execute eval everytime you want to invoke HCLIs by name (e.g. hg).\n\n.. code-block:: console\n \n huckle cli install http://127.0.0.1:8000\n eval $(huckle env)\n hg help\n\nVersioning\n----------\n \nThis project makes use of semantic versioning (http://semver.org) and may make use of the \"devx\",\n\"prealphax\", \"alphax\" \"betax\", and \"rcx\" extensions where x is a number (e.g. 0.3.0-prealpha1)\non github. Only full major.minor.patch releases will be pushed to pip from now on.\n\nSupports\n--------\n\n- HTTP/HTTPS.\n- HCLI version 1.0 server semantics for hal+json\n- Web Server Gateway Interface (WSGI) through PEP 3333 and Falcon.\n- Bundled Sample HCLIs:\n - jsonf - a simple formatter for JSON.\n - hfm - a file upload and download manager that works with \\*nix terminal shell input and output streams.\n - hptt - a rudimentary HCLI Push To Talk (PTT) channel management service.\n - hub - a rudimentary HCLI service discovery hub.\n - nw - a flexible IP Address Management (IPAM) service.\n- Support for use of any 3rd party HCLI code that meets CLI interface requirements and HCLI template requirements (i.e. see sample HCLIs).\n- Support large input and output streams as application/octet-stream.\n\nTo Do\n-----\n\n- Automated tests for all bundled HCLI samples.\n- Separate out HCLI applications from HCLI Core to help avoid application dependencies bleeding onto HCLI Core.\n\nBugs\n----\n\n- No good handling of control over request and response in cli code which can lead to exceptions and empty response client side.\n- The hfm sample HCLI fails disgracefully when copying a remote file name that doesn't exist (server error).\n\n.. |build status| image:: https://circleci.com/gh/cometaj2/hcli_core.svg?style=shield\n :target: https://circleci.com/gh/cometaj2/hcli_core\n.. |pypi| image:: https://img.shields.io/pypi/v/hcli-core?label=hcli-core\n :target: https://pypi.org/project/hcli-core\n.. |pyver| image:: https://img.shields.io/pypi/pyversions/hcli-core.svg\n :target: https://pypi.org/project/hcli-core\n.. |huckle| image:: https://img.shields.io/pypi/v/huckle?label=huckle\n :target: https://pypi.org/project/huckle\n.. |hc| image:: https://img.shields.io/pypi/v/hcli-hc?label=hcli-hc\n :target: https://pypi.org/project/hcli-hc\n.. |hg| image:: https://img.shields.io/pypi/v/hcli-hg?label=hcli-hg\n :target: https://pypi.org/project/hcli-hg\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "An HCLI connector that can be used to expose any CLI expressed through hypertext command line interface (HCLI) semantics.",
"version": "0.20.2",
"project_urls": {
"Homepage": "https://github.com/cometaj2/hcli_core"
},
"split_keywords": [
"cli",
"client",
"server",
"connector",
"hypermedia",
"rest",
"generic",
"development"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "eec0a929bdb00d77f8dd64c75a833a928bf070efb4a687f4be9fb89f36472480",
"md5": "74fe9538c1d41744a89abb23327cde4d",
"sha256": "e6e1e2adf1dfa0b5c26f5a414a68de664dd3e2dcc07fd0b4c0b98a6150b16b45"
},
"downloads": -1,
"filename": "hcli_core-0.20.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "74fe9538c1d41744a89abb23327cde4d",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 35980,
"upload_time": "2024-04-29T23:28:02",
"upload_time_iso_8601": "2024-04-29T23:28:02.933602Z",
"url": "https://files.pythonhosted.org/packages/ee/c0/a929bdb00d77f8dd64c75a833a928bf070efb4a687f4be9fb89f36472480/hcli_core-0.20.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "483113b607e95df3b6963472a9f1722b5aad2b159b5992eba3f3ada1e59710e6",
"md5": "8871fe9b872c67bcaf81060b9e11616e",
"sha256": "297a8091252add82044404e0b2ea09ae74a5d3d440160a1135c55edf36b2931e"
},
"downloads": -1,
"filename": "hcli_core-0.20.2.tar.gz",
"has_sig": false,
"md5_digest": "8871fe9b872c67bcaf81060b9e11616e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 25495,
"upload_time": "2024-04-29T23:28:05",
"upload_time_iso_8601": "2024-04-29T23:28:05.427048Z",
"url": "https://files.pythonhosted.org/packages/48/31/13b607e95df3b6963472a9f1722b5aad2b159b5992eba3f3ada1e59710e6/hcli_core-0.20.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-29 23:28:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "cometaj2",
"github_project": "hcli_core",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"lcname": "hcli-core"
}
JSON
