| Name | jaws-libp JSON |
| Version |
4.8.3
JSON |
| download |
| home_page | None |
| Summary | Jefferson Lab Alarm Warning System API |
| upload_time | 2024-03-27 13:55:57 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | ==3.9.* |
| license | MIT License |
| keywords |
kafka
alarm
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# jaws-libp [](https://github.com/JeffersonLab/jaws-libp/actions/workflows/ci.yml) [](https://pypi.org/project/jaws-libp/) [](https://hub.docker.com/r/jeffersonlab/jaws-libp)
Reusable Python classes for [JAWS](https://github.com/JeffersonLab/jaws) plus admin scripts to setup and manage a deployment.
---
- [Quick Start with Compose](https://github.com/JeffersonLab/jaws-libp#quick-start-with-compose)
- [Install](https://github.com/JeffersonLab/jaws-libp#install)
- [API](https://github.com/JeffersonLab/jaws-libp#api)
- [Configure](https://github.com/JeffersonLab/jaws-libp#configure)
- [Build](https://github.com/JeffersonLab/jaws-libp#build)
- [Develop](https://github.com/JeffersonLab/jaws-libp#develop)
- [Test](https://github.com/JeffersonLab/jaws-libp#test)
- [Release](https://github.com/JeffersonLab/jaws-libp#release)
- [See Also](https://github.com/JeffersonLab/jaws-libp#see-also)
---
## Quick Start with Compose
1. Grab project
```
git clone https://github.com/JeffersonLab/jaws-libp
cd jaws-libp
```
2. Launch [Compose](https://github.com/docker/compose)
```
docker compose up
```
3. Monitor active alarms
```
docker exec -it jaws list_activations --monitor
```
4. Trip an alarm
```
docker exec jaws set_activation alarm1
```
**Note**: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.
**See**: [Docker Compose Strategy](https://gist.github.com/slominskir/a7da801e8259f5974c978f9c3091d52c)
## Install
Requires [Python 3.9+](https://www.python.org/)
```
pip install jaws-libp
```
**Note**: Using newer versions of Python may be problematic because the dependency `confluent-kafka` uses librdkafka, which often does not have a wheel file prepared for later versions of Python, meaning setuptools will attempt to compile it for you, and that often doesn't work (especially on Windows). Python 3.9 does have a wheel file for confluent-kafka so that's your safest bet. Wheel files also generally only are prepared for Windows, MacOS, and Linux. Plus only for architectures x86_64 and arm64, also only for glibc. If you use with musl libc or linux-aarch64 then you'll likely have to compile librdkafka yourself from source.
## API
[Sphinx Docs](https://jeffersonlab.github.io/jaws-libp/)
## Configure
Environment variables are used to configure jaws-libp:
| Name | Description |
|------------------|----------------------------------------------------------------------------------------------------------------------------|
| BOOTSTRAP_SERVER | Host and port pair pointing to a Kafka server to bootstrap the client connection to a Kafka Cluster; example: `kafka:9092` |
| SCHEMA_REGISTRY | URL to Confluent Schema Registry; example: `http://registry:8081` |
The Docker container can optionally handle the following environment variables as well:
| Name | Description |
|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ALARM_LOCATIONS | Path to an alarm locations file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/locations)), else an https URL to a file, else a comma separated list of location definitions with fields separated by the pipe symbol. Example Inline CSV: `name\|parent` |
| ALARM_CATEGORIES | Path to an alarm categories file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/categories)), else an https URL to a file, else a comma separated list of catgory definitions with fields. Example Inline CSV: `name` |
| ALARM_CLASSES | Path to an alarm classes file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/classes)), else an https URL to a file, else a comma separated list of class definitions with fields separated by the pipe symbol. Example Inline CSV: `name\|category\|priority\|rationale\|correctiveaction\|pointofcontactusername\|latching\|filterable\|ondelayseconds\|offdelayseconds` |
| ALARM_INSTANCES | Path to an alarm instances file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/instances)), else an https URL to a file, else a comma separated list of instance definitions with fields separated by the pipe symbol. Leave epicspv field empty for SimpleProducer. Example Inline CSV: `name\|class\|epicspv\|location\|maskedby\|screencommand` |
| ALARM_INSTANCES_URL_CSV | If provided, is a comma separated list of file names to append to ALARM_INSTANCES; ignored if ALARM_INSTANCES doesn't start with `https`; [Example](https://github.com/JeffersonLab/jaws-libp/blob/cc56789a68009f71988ba98f5f55d822c240cd9d/build.yml#L25-L26). |
| ALARM_OVERRIDES | Path to an alarm overrides file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/overrides)), else an https URL to a file. |
## Build
This [Python 3.9+](https://www.python.org/) project is built with [setuptools](https://setuptools.pypa.io/en/latest/setuptools.html) and may be run using the Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) feature to isolate dependencies. The [pip](https://pypi.org/project/pip/) tool can be used to download dependencies.
```
git clone https://github.com/JeffersonLab/jaws-libp
cd jaws-libp
python -m venv .venv_dev --upgrade-deps
```
Activate the virtual env using your [shell specific command](https://gist.github.com/slominskir/e7ed71317ea24fc19b97a0ec006ff4f1#activate-dev-virtual-environment), then install in editable mode with dev deps and run build:
```
# Windows
.venv_dev\Scripts\activate.bat
# Linux (SH Shell)
source .venv_dev/bin/activate
#MacOS (CSH Shell)
source .venv_dev/bin/activate.csh
pip install -e .[dev]
python -m build
pylint --recursive=y src/*
```
**Note for JLab On-Site Users**: Jefferson Lab has an intercepting [proxy](https://gist.github.com/slominskir/92c25a033db93a90184a5994e71d0b78)
**See**: [Python Development Notes](https://gist.github.com/slominskir/e7ed71317ea24fc19b97a0ec006ff4f1)
## Develop
Set up the build environment following the [Build](https://github.com/JeffersonLab/jaws-libp#build) instructions.
In order to iterate rapidly when making changes it's often useful to run the Python scripts directly on the local workstation, perhaps leveraging an IDE. In this scenario run the service dependencies with Docker Compose:
```
docker compose -f deps.yaml up
```
**Note**: The environment variable defaults work in this scenario and are defined as:
`BOOTSTRAP_SERVERS=localhost:9094` and `SCHEMA_REGISTRY=http://localhost:8081`
## Test
The integration tests depend on a running Kafka instance, generally in Docker. The tests run automatically via the [CI](https://github.com/JeffersonLab/jaws-libp/actions/workflows/ci.yml) GitHub Action on every commit (unless `[no ci]` is included in the commit message). The tests can be run locally during development. Set up the development environment following the [Develop](https://github.com/JeffersonLab/jaws-libp#develop) instructions. Then with the `deps.yaml` Docker containers running and the build virtual environment activated run:
```
pytest
```
## Release
1. Bump the version number in the VERSION file and commit and push to GitHub (using [Semantic Versioning](https://semver.org/)).
2. The [CD](https://github.com/JeffersonLab/jaws-libp/blob/main/.github/workflows/cd.yml) GitHub Action should run automatically invoking:
- The [Create release](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/gh-release.yml) GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
- The [Publish artifact](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/pypi-publish.yml) GitHub Action to create a deployment artifact on PyPi.
- The [Publish docs](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/gh-pages-publish.yml) GitHub Action to create Sphinx docs.
- The [Publish docker image](https://github.com/JeffersonLab/container-workflows/blob/main/.github/workflows/docker-publish.yml) GitHub Action to create a new demo Docker image, and bump the [compose.override.yaml](https://github.com/JeffersonLab/jaws-libp/blob/main/compose.override.yaml) to use the new image.
## See Also
- [jaws-libj (Java)](https://github.com/JeffersonLab/jaws-libj)
- [Developer Notes](https://github.com/JeffersonLab/jaws-libp/wiki/Developer-Notes)
Raw data
{
"_id": null,
"home_page": null,
"name": "jaws-libp",
"maintainer": null,
"docs_url": null,
"requires_python": "==3.9.*",
"maintainer_email": null,
"keywords": "kafka, alarm",
"author": null,
"author_email": "Ryan Slominski <ryans@jlab.org>",
"download_url": "https://files.pythonhosted.org/packages/87/3b/523f8fe1454d8d20f7f235578916c47058d1fba929c3369c39ede375f772/jaws-libp-4.8.3.tar.gz",
"platform": null,
"description": "# jaws-libp [](https://github.com/JeffersonLab/jaws-libp/actions/workflows/ci.yml) [](https://pypi.org/project/jaws-libp/) [](https://hub.docker.com/r/jeffersonlab/jaws-libp)\nReusable Python classes for [JAWS](https://github.com/JeffersonLab/jaws) plus admin scripts to setup and manage a deployment.\n\n---\n- [Quick Start with Compose](https://github.com/JeffersonLab/jaws-libp#quick-start-with-compose)\n- [Install](https://github.com/JeffersonLab/jaws-libp#install) \n- [API](https://github.com/JeffersonLab/jaws-libp#api)\n- [Configure](https://github.com/JeffersonLab/jaws-libp#configure) \n- [Build](https://github.com/JeffersonLab/jaws-libp#build)\n- [Develop](https://github.com/JeffersonLab/jaws-libp#develop)\n- [Test](https://github.com/JeffersonLab/jaws-libp#test)\n- [Release](https://github.com/JeffersonLab/jaws-libp#release) \n- [See Also](https://github.com/JeffersonLab/jaws-libp#see-also)\n---\n\n## Quick Start with Compose\n1. Grab project\n```\ngit clone https://github.com/JeffersonLab/jaws-libp\ncd jaws-libp\n```\n2. Launch [Compose](https://github.com/docker/compose)\n```\ndocker compose up\n```\n3. Monitor active alarms\n```\ndocker exec -it jaws list_activations --monitor\n```\n4. Trip an alarm\n```\ndocker exec jaws set_activation alarm1\n```\n**Note**: The docker-compose services require significant system resources - tested with 4 CPUs and 4GB memory.\n\n**See**: [Docker Compose Strategy](https://gist.github.com/slominskir/a7da801e8259f5974c978f9c3091d52c)\n\n## Install\nRequires [Python 3.9+](https://www.python.org/)\n\n```\npip install jaws-libp\n```\n\n**Note**: Using newer versions of Python may be problematic because the dependency `confluent-kafka` uses librdkafka, which often does not have a wheel file prepared for later versions of Python, meaning setuptools will attempt to compile it for you, and that often doesn't work (especially on Windows). Python 3.9 does have a wheel file for confluent-kafka so that's your safest bet. Wheel files also generally only are prepared for Windows, MacOS, and Linux. Plus only for architectures x86_64 and arm64, also only for glibc. If you use with musl libc or linux-aarch64 then you'll likely have to compile librdkafka yourself from source.\n\n## API\n[Sphinx Docs](https://jeffersonlab.github.io/jaws-libp/)\n\n## Configure\nEnvironment variables are used to configure jaws-libp:\n\n| Name | Description |\n|------------------|----------------------------------------------------------------------------------------------------------------------------|\n| BOOTSTRAP_SERVER | Host and port pair pointing to a Kafka server to bootstrap the client connection to a Kafka Cluster; example: `kafka:9092` |\n| SCHEMA_REGISTRY | URL to Confluent Schema Registry; example: `http://registry:8081` |\n\nThe Docker container can optionally handle the following environment variables as well:\n\n| Name | Description |\n|-------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| ALARM_LOCATIONS | Path to an alarm locations file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/locations)), else an https URL to a file, else a comma separated list of location definitions with fields separated by the pipe symbol. Example Inline CSV: `name\\|parent` |\n| ALARM_CATEGORIES | Path to an alarm categories file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/categories)), else an https URL to a file, else a comma separated list of catgory definitions with fields. Example Inline CSV: `name` |\n| ALARM_CLASSES | Path to an alarm classes file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/classes)), else an https URL to a file, else a comma separated list of class definitions with fields separated by the pipe symbol. Example Inline CSV: `name\\|category\\|priority\\|rationale\\|correctiveaction\\|pointofcontactusername\\|latching\\|filterable\\|ondelayseconds\\|offdelayseconds` |\n| ALARM_INSTANCES | Path to an alarm instances file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/instances)), else an https URL to a file, else a comma separated list of instance definitions with fields separated by the pipe symbol. Leave epicspv field empty for SimpleProducer. Example Inline CSV: `name\\|class\\|epicspv\\|location\\|maskedby\\|screencommand` |\n| ALARM_INSTANCES_URL_CSV | If provided, is a comma separated list of file names to append to ALARM_INSTANCES; ignored if ALARM_INSTANCES doesn't start with `https`; [Example](https://github.com/JeffersonLab/jaws-libp/blob/cc56789a68009f71988ba98f5f55d822c240cd9d/build.yml#L25-L26). |\n| ALARM_OVERRIDES | Path to an alarm overrides file to import ([example file](https://github.com/JeffersonLab/jaws/blob/main/examples/data/overrides)), else an https URL to a file. |\n\n## Build\nThis [Python 3.9+](https://www.python.org/) project is built with [setuptools](https://setuptools.pypa.io/en/latest/setuptools.html) and may be run using the Python [virtual environment](https://docs.python.org/3/tutorial/venv.html) feature to isolate dependencies. The [pip](https://pypi.org/project/pip/) tool can be used to download dependencies.\n\n```\ngit clone https://github.com/JeffersonLab/jaws-libp\ncd jaws-libp\npython -m venv .venv_dev --upgrade-deps\n```\n\nActivate the virtual env using your [shell specific command](https://gist.github.com/slominskir/e7ed71317ea24fc19b97a0ec006ff4f1#activate-dev-virtual-environment), then install in editable mode with dev deps and run build:\n```\n# Windows\n.venv_dev\\Scripts\\activate.bat\n# Linux (SH Shell)\nsource .venv_dev/bin/activate\n#MacOS (CSH Shell)\nsource .venv_dev/bin/activate.csh\n\n\npip install -e .[dev]\npython -m build\npylint --recursive=y src/*\n```\n\n**Note for JLab On-Site Users**: Jefferson Lab has an intercepting [proxy](https://gist.github.com/slominskir/92c25a033db93a90184a5994e71d0b78)\n\n**See**: [Python Development Notes](https://gist.github.com/slominskir/e7ed71317ea24fc19b97a0ec006ff4f1)\n\n## Develop\nSet up the build environment following the [Build](https://github.com/JeffersonLab/jaws-libp#build) instructions.\n\nIn order to iterate rapidly when making changes it's often useful to run the Python scripts directly on the local workstation, perhaps leveraging an IDE. In this scenario run the service dependencies with Docker Compose:\n```\ndocker compose -f deps.yaml up\n```\n\n**Note**: The environment variable defaults work in this scenario and are defined as:\n`BOOTSTRAP_SERVERS=localhost:9094` and `SCHEMA_REGISTRY=http://localhost:8081`\n\n## Test\nThe integration tests depend on a running Kafka instance, generally in Docker. The tests run automatically via the [CI](https://github.com/JeffersonLab/jaws-libp/actions/workflows/ci.yml) GitHub Action on every commit (unless `[no ci]` is included in the commit message). The tests can be run locally during development. Set up the development environment following the [Develop](https://github.com/JeffersonLab/jaws-libp#develop) instructions. Then with the `deps.yaml` Docker containers running and the build virtual environment activated run:\n```\npytest\n```\n\n## Release\n1. Bump the version number in the VERSION file and commit and push to GitHub (using [Semantic Versioning](https://semver.org/)).\n2. The [CD](https://github.com/JeffersonLab/jaws-libp/blob/main/.github/workflows/cd.yml) GitHub Action should run automatically invoking:\n - The [Create release](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/gh-release.yml) GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.\n - The [Publish artifact](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/pypi-publish.yml) GitHub Action to create a deployment artifact on PyPi.\n - The [Publish docs](https://github.com/JeffersonLab/python-workflows/blob/main/.github/workflows/gh-pages-publish.yml) GitHub Action to create Sphinx docs.\n - The [Publish docker image](https://github.com/JeffersonLab/container-workflows/blob/main/.github/workflows/docker-publish.yml) GitHub Action to create a new demo Docker image, and bump the [compose.override.yaml](https://github.com/JeffersonLab/jaws-libp/blob/main/compose.override.yaml) to use the new image.\n\n## See Also\n - [jaws-libj (Java)](https://github.com/JeffersonLab/jaws-libj)\n - [Developer Notes](https://github.com/JeffersonLab/jaws-libp/wiki/Developer-Notes)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Jefferson Lab Alarm Warning System API",
"version": "4.8.3",
"project_urls": {
"Repository": "https://github.com/jeffersonlab/jaws-libp.git"
},
"split_keywords": [
"kafka",
" alarm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0a380a457d080f8eabe12f64b27f0b380c1dd3323ef62f47acce70d5c9e7aeba",
"md5": "bc6a47a9590b14227f0c0f10468afa61",
"sha256": "cf82f8eb4df155f056dbd25bc05f3d564a3348cb85024f6d3e0148ef20e12512"
},
"downloads": -1,
"filename": "jaws_libp-4.8.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc6a47a9590b14227f0c0f10468afa61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "==3.9.*",
"size": 63583,
"upload_time": "2024-03-27T13:55:55",
"upload_time_iso_8601": "2024-03-27T13:55:55.682617Z",
"url": "https://files.pythonhosted.org/packages/0a/38/0a457d080f8eabe12f64b27f0b380c1dd3323ef62f47acce70d5c9e7aeba/jaws_libp-4.8.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "873b523f8fe1454d8d20f7f235578916c47058d1fba929c3369c39ede375f772",
"md5": "8f439686a2d7bab4d166cf3e413d513e",
"sha256": "ab860cc5d35a8d8f743128243d2aa4d877d7b802ec7190ae325d30f0dd4fc3f5"
},
"downloads": -1,
"filename": "jaws-libp-4.8.3.tar.gz",
"has_sig": false,
"md5_digest": "8f439686a2d7bab4d166cf3e413d513e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "==3.9.*",
"size": 41899,
"upload_time": "2024-03-27T13:55:57",
"upload_time_iso_8601": "2024-03-27T13:55:57.578715Z",
"url": "https://files.pythonhosted.org/packages/87/3b/523f8fe1454d8d20f7f235578916c47058d1fba929c3369c39ede375f772/jaws-libp-4.8.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 13:55:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jeffersonlab",
"github_project": "jaws-libp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jaws-libp"
}
