Hop Client
=============
[](https://codecov.io/gh/scimma/hop-client)
| | |
| ------------ | ------ |
| **Docs:** | https://hop-client.readthedocs.io/en/stable/ |
**hop-client** is a pub-sub client library for Multimessenger Astrophysics.
## Installation
You can install hop either via pip, conda, or from source.
To install with pip:
```
pip install -U hop-client
```
To install with conda:
```
conda install -c conda-forge hop-client
```
To install from source:
```
tar -xzf hop-client-x.y.z.tar.gz
cd hop-client-x.y.z
python setup.py install
```
## Quickstart
By default, authentication is enabled, reading in configuration settings
from `config.toml`. The path to this configuration can be found by running
`hop auth locate`. One can initialize this configuration with default
settings by running `hop auth setup`. To disable authentication in the CLI
client, one can run `--no-auth`.
### Command Line Interface
Publish a message:
```
hop publish kafka://hostname:port/gcn -f CIRCULAR example.gcn3
```
Example messages are provided in `tests/data` including:
* A GCN circular (`example.gcn3`)
* A VOEvent (`example_voevent.xml`)
Consume messages:
```
hop subscribe kafka://hostname:port/gcn -s EARLIEST
```
This will read messages from the gcn topic from the earliest offset
and read messages until an end of stream (EOS) is received.
### Python API
Publish messages:
Using the python API, we can publish various types of messages, including
structured messages such as GCN Circulars and VOEvents:
```python
from hop import stream
from hop.models import GCNCircular
# read in a GCN circular
with open("path/to/circular.gcn3", "r") as f:
circular = GCNCircular.load(f)
with stream.open("kafka://hostname:port/topic", "w") as s:
s.write(circular)
```
In addition, we can also publish unstructured messages as long as they are
JSON serializable:
```python
from hop import stream
with stream.open("kafka://hostname:port/topic", "w") as s:
s.write({"my": "message"})
```
By default, authentication is enabled for the Hop broker, reading in configuration
settings from `config.toml`. In order to modify various authentication options, one
can configure a `Stream` instance and pass in an `Auth` instance with credentials:
```python
from hop import Stream
from hop.auth import Auth
auth = Auth("my-username", "my-password")
stream = Stream(auth=auth)
with stream.open("kafka://hostname:port/topic", "w") as s:
s.write({"my": "message"})
```
To explicitly disable authentication one can set `auth` to `False`.
Consume messages:
```python
from hop import stream
with stream.open("kafka://hostname:port/topic", "r") as s:
for message in s:
print(message)
```
This will listen to the Hop broker, listening to new messages and printing them to
stdout as they arrive until there are no more messages in the stream.
By default, this will only process new messages since the connection was opened.
The `start_at` option lets you control where in the stream you can start listening
from. For example, if you'd like to listen to all messages stored in a topic, you can do:
```python
from hop import Stream
from hop.io import StartPosition
stream = Stream(start_at=StartPosition.EARLIEST)
with stream.open("kafka://hostname:port/topic", "r") as s:
for message in s:
print(message)
```
## Development
A Makefile is provided to ease in testing, deployment and generating documentation.
A list of commands can be listed with `make help`.
In addition, two extras are provided when installing the hop client that installs
the required test and documentation libraries:
* dev: dependencies required for testing, linting and packaging
* docs: dependencies required for building documentation
Assuming you've cloned the repository and are in the project's root directory, you can
install hop-client alongside all the required development dependencies by running:
```
pip install .[dev,docs]
```
### Releases
To create a new release, first make a Github Issue for the specific release using the [release template](https://github.com/scimma/hop-client/issues/new?assignees=&labels=&template=release-checklist.md&title=Release+version+%3Cversion%3E). Complete the steps in the `Pre-release` section; once that section is finished, complete the `Release` section. Ensure that the new version release string follows the [semver](https://semver.org/) conventions, e.g., `v0.0.1`.
These steps will result in a new Github release, as well as a new package version uploaded to `PyPI` and `conda-forge` via Github Actions.
Raw data
{
"_id": null,
"home_page": "https://github.com/scimma/hop-client",
"name": "hop-client",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Patrick Godwin",
"author_email": "patrick.godwin@psu.edu",
"download_url": "https://files.pythonhosted.org/packages/64/d1/108cea042128c7ea7790e15e12e3e5ed595bfcf4b051c34fe1064924beba/hop-client-0.9.0.tar.gz",
"platform": null,
"description": "Hop Client\n=============\n\n\n[](https://codecov.io/gh/scimma/hop-client)\n\n| | |\n| ------------ | ------ |\n| **Docs:** | https://hop-client.readthedocs.io/en/stable/ |\n\n**hop-client** is a pub-sub client library for Multimessenger Astrophysics.\n\n## Installation\n\nYou can install hop either via pip, conda, or from source.\n\nTo install with pip:\n\n```\npip install -U hop-client\n```\n\nTo install with conda:\n\n```\nconda install -c conda-forge hop-client\n```\n\nTo install from source:\n\n```\ntar -xzf hop-client-x.y.z.tar.gz\ncd hop-client-x.y.z\npython setup.py install\n```\n\n## Quickstart\n\nBy default, authentication is enabled, reading in configuration settings\nfrom `config.toml`. The path to this configuration can be found by running\n`hop auth locate`. One can initialize this configuration with default\nsettings by running `hop auth setup`. To disable authentication in the CLI\nclient, one can run `--no-auth`.\n\n### Command Line Interface\n\nPublish a message:\n\n```\nhop publish kafka://hostname:port/gcn -f CIRCULAR example.gcn3\n```\n\nExample messages are provided in `tests/data` including:\n* A GCN circular (`example.gcn3`)\n* A VOEvent (`example_voevent.xml`)\n\n\nConsume messages:\n\n```\nhop subscribe kafka://hostname:port/gcn -s EARLIEST\n```\n\nThis will read messages from the gcn topic from the earliest offset\nand read messages until an end of stream (EOS) is received.\n\n### Python API\n\nPublish messages:\n\nUsing the python API, we can publish various types of messages, including\nstructured messages such as GCN Circulars and VOEvents:\n\n```python\nfrom hop import stream\nfrom hop.models import GCNCircular\n\n# read in a GCN circular\nwith open(\"path/to/circular.gcn3\", \"r\") as f:\n circular = GCNCircular.load(f)\n\nwith stream.open(\"kafka://hostname:port/topic\", \"w\") as s:\n s.write(circular)\n```\n\nIn addition, we can also publish unstructured messages as long as they are\nJSON serializable:\n\n```python\nfrom hop import stream\n\nwith stream.open(\"kafka://hostname:port/topic\", \"w\") as s:\n s.write({\"my\": \"message\"})\n```\n\nBy default, authentication is enabled for the Hop broker, reading in configuration\nsettings from `config.toml`. In order to modify various authentication options, one\ncan configure a `Stream` instance and pass in an `Auth` instance with credentials:\n\n```python\nfrom hop import Stream\nfrom hop.auth import Auth\n\nauth = Auth(\"my-username\", \"my-password\")\nstream = Stream(auth=auth)\n\nwith stream.open(\"kafka://hostname:port/topic\", \"w\") as s:\n s.write({\"my\": \"message\"})\n```\n\nTo explicitly disable authentication one can set `auth` to `False`.\n\nConsume messages:\n\n\n```python\nfrom hop import stream\n\nwith stream.open(\"kafka://hostname:port/topic\", \"r\") as s:\n for message in s:\n print(message)\n```\n\nThis will listen to the Hop broker, listening to new messages and printing them to\nstdout as they arrive until there are no more messages in the stream.\nBy default, this will only process new messages since the connection was opened.\nThe `start_at` option lets you control where in the stream you can start listening\nfrom. For example, if you'd like to listen to all messages stored in a topic, you can do:\n\n```python\nfrom hop import Stream\nfrom hop.io import StartPosition\n\nstream = Stream(start_at=StartPosition.EARLIEST)\n\nwith stream.open(\"kafka://hostname:port/topic\", \"r\") as s:\n for message in s:\n print(message)\n```\n\n\n## Development\n\nA Makefile is provided to ease in testing, deployment and generating documentation.\n\nA list of commands can be listed with `make help`.\n\nIn addition, two extras are provided when installing the hop client that installs\nthe required test and documentation libraries:\n\n* dev: dependencies required for testing, linting and packaging\n* docs: dependencies required for building documentation\n\nAssuming you've cloned the repository and are in the project's root directory, you can\ninstall hop-client alongside all the required development dependencies by running:\n\n```\npip install .[dev,docs]\n```\n\n### Releases\n\nTo create a new release, first make a Github Issue for the specific release using the [release template](https://github.com/scimma/hop-client/issues/new?assignees=&labels=&template=release-checklist.md&title=Release+version+%3Cversion%3E). Complete the steps in the `Pre-release` section; once that section is finished, complete the `Release` section. Ensure that the new version release string follows the [semver](https://semver.org/) conventions, e.g., `v0.0.1`.\n\nThese steps will result in a new Github release, as well as a new package version uploaded to `PyPI` and `conda-forge` via Github Actions.\n\n",
"bugtrack_url": null,
"license": "BSD 3-Clause",
"summary": "A pub-sub client library for Multi-messenger Astrophysics",
"version": "0.9.0",
"project_urls": {
"Homepage": "https://github.com/scimma/hop-client"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b57ba495ccf756f4ab4a719b4b0f2ea1f89ec51841483503a76300b6e094a9c3",
"md5": "8061a41e49ee869d72a581ce49404795",
"sha256": "b172dcb4164f936c2f2b1b653e69332a321a9799e1e5cbcafdb44f75066f26c7"
},
"downloads": -1,
"filename": "hop_client-0.9.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "8061a41e49ee869d72a581ce49404795",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 37940,
"upload_time": "2023-11-10T19:41:05",
"upload_time_iso_8601": "2023-11-10T19:41:05.903231Z",
"url": "https://files.pythonhosted.org/packages/b5/7b/a495ccf756f4ab4a719b4b0f2ea1f89ec51841483503a76300b6e094a9c3/hop_client-0.9.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "64d1108cea042128c7ea7790e15e12e3e5ed595bfcf4b051c34fe1064924beba",
"md5": "2afceadbae563fd45e0228517693f61f",
"sha256": "88929f318e4205c649e806252d1d3fc9ad559e68b5cbea7755205d9590fcae55"
},
"downloads": -1,
"filename": "hop-client-0.9.0.tar.gz",
"has_sig": false,
"md5_digest": "2afceadbae563fd45e0228517693f61f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 92432,
"upload_time": "2023-11-10T19:41:07",
"upload_time_iso_8601": "2023-11-10T19:41:07.681943Z",
"url": "https://files.pythonhosted.org/packages/64/d1/108cea042128c7ea7790e15e12e3e5ed595bfcf4b051c34fe1064924beba/hop-client-0.9.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-10 19:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "scimma",
"github_project": "hop-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hop-client"
}
JSON
