| Name | galv-harvester JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | None |
| upload_time | 2024-05-01 10:17:28 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | Copyright (c) 2020-2023, The Chancellor, Masters and Scholars of the University of Oxford, and the 'Galv' Developers. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
battery
cycler
galv
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Galv Harvester (Python program)
> A metadata secretary for battery science
[](https://github.com/pypa/hatch)
[](https://github.com/Battery-Intelligence-Lab/galv-harvester/actions/workflows/publish.yml)
## Galv Project
- [Specification](https://github.com/Battery-Intelligence-Lab/galv-spec)
- [Backend](https://github.com/Battery-Intelligence-Lab/galv-backend)
- [Frontend](https://github.com/Battery-Intelligence-Lab/galv-frontend)
- [**Harvester**](https://github.com/Battery-Intelligence-Lab/galv-harvester)
## Installation
The Galv Harvester can be installed from the [Python Package Index](https://pypi.org/project/galv-harvester/).
```bash
pip install galv-harvester
```
This will install the harvester and its dependencies, and make the `galv-harvester` command available.
## Usage
Run the harvester using the following command:
```bash
galv-harvester
```
The harvester will prompt you for the necessary settings to connect to the Galv server (see [Initial Setup](#initial-setup)).
Alternatively, you can specify the settings as environment variables
(see [Using Environment Variables](#using-environment-variables))
or as [command line arguments](#using-command-line-arguments) to the `galv-harvester` program.
## Initial Setup
There are three ways to set up the harvester: using the [setup wizard](#using-the-setup-wizard),
using [command line arguments](#using-command-line-arguments),
or by specifying [environment variables](#using-environment-variables).
You can use a combination of both methods, specifying some settings in the environment and others in the wizard.
If you launch the program using the commands above, you will be prompted to enter the necessary settings by the wizard.
### Using the setup wizard
First, you'll be asked for the [Galv server](https://github.com/Battery-Intelligence-Lab/galv-backend) URL.
This should be the URL of the Galv server you have set up.
Providing a frontend URL will not work, as the harvester needs to communicate with the backend.
Next, you'll be asked for your API token.
This can be generated in either the Galv frontend or backend.
The token should be for a User who administers the Lab the Harvester will belong to.
Next, you'll be asked to specify a name for the new Harvester.
Finally, you'll be asked if you want to monitor a directory.
If you answer 'yes', you'll be asked for the path to the directory you want to monitor,
and the Team that the monitored path will belong to.
The Harvester will register itself with the Galv server and begin to monitor for data files.
The `--run_foreground` flag is optional, and will keep the harvester running in the foreground.
### Using environment variables
You can specify harvester properties as environment variables.
If you are using docker-compose, you can specify these in the `docker-compose.yml` file (see below),
or you can specify them in your shell environment before running the harvester if you are running it as a standalone Python program.
Any environment variables can be omitted, and the harvester will prompt you for them when you start it if they are necessary.
For details on the variables you can set, and whether they are necessary, see the [variable details](#variable-details) section.
```yaml
# .env
GALV_HARVESTER_RESTART=1
GALV_HARVESTER_SERVER_URL=<your_server_url>
GALV_HARVESTER_NAME=<your_harvester_name>
GALV_HARVESTER_API_TOKEN=<your_api_token>
GALV_HARVESTER_LAB_ID=<your_lab_id>
GALV_HARVESTER_TEAM_ID=<your_team_id>
GALV_HARVESTER_MONITOR_PATH=<your_monitor_path>
GALV_HARVESTER_MONITOR_PATH_REGEX=<your_monitor_path_regex>
GALV_HARVESTER_SKIP_WIZARD=<true_or_omit>
GALV_HARVESTER_RUN_FOREGROUND=<true_or_omit>
```
If you don't want to have to specify the path to the data directory every time you start the harvester,
you can also edit the `docker-compose.yml` file to include the path as a volume.
### Using command line arguments
You can also specify harvester properties as command line arguments:
```text
Usage: galv-harvester [OPTIONS]
Options:
--version Show the version and exit.
--url TEXT API URL to register harvester with.
--name TEXT Name for the harvester.
--api_token TEXT Your API token. You must have admin access to at
least one Lab.
--lab_id INTEGER Id of the Lab to assign the Harvester to. Only
required if you administrate multiple Labs.
--team_id INTEGER Id of the Team to create a Monitored Path for.
Only required if you administrate multiple Teams
and wish to create a monitored path.
--monitor_path TEXT Path to harvest files from.
--monitor_path_regex TEXT Regex to match files to harvest. Other options
can be specified using the frontend.
--run_foreground On completion, run the harvester in the
foreground (will not close the thread, useful for
Dockerized application).
--restart Ignore other options and run harvester if config
file already exists.
--help Show this message and exit.
```
For details on the variables you can set, and when they are necessary, see the [variable details](#variable-details) section.
## Variable details
- `GALV_HARVESTER_RESTART`: If set to 1, the harvester will attempt to resume from a previous configuration file.
If not restarting from a previous configuration, the following variables are required,
and will be prompted for by the wizard if not set (unless `GALV_HARVESTER_SKIP_WIZARD` is set to `true`).
If `GALV_HARVESTER_SKIP_WIZARD` is set to `true`, you must provide these variables in the environment or the docker-compose file:
- `GALV_HARVESTER_SERVER_URL`: The URL of the Galv server.
- `GALV_HARVESTER_NAME`: The name of the harvester.
- `GALV_HARVEST_API_TOKEN`: The API token for a User who administers the Lab the Harvester will be associated with.
- `GALV_HARVESTER_LAB_ID`: The ID of the lab the harvester belongs to. Only required if the User administers multiple Labs.
If you want to set up a monitored path, the following variables are required:
- `GALV_HARVESTER_TEAM_ID`: The ID of the team the monitored path will belong to. Only required if the User has multiple Teams.
- `GALV_HARVESTER_MONITOR_PATH`: The path to the directory you want to monitor.
You may also optionally specify the following variables:
- `GALV_HARVESTER_MONITOR_PATH_REGEX`: A regex pattern to match files in the monitored path. Only files that match this pattern will be uploaded to the Galv server.
- `GALV_HARVESTER_SKIP_WIZARD`: If set to `true`, the harvester will not prompt you for any missing variables and setup will fail if necessary variables are not set.
- `GALV_HARVESTER_RUN_FOREGROUND`: If set to `true`, the harvester will run in the foreground.
## Further setup
Further setup can be done in the web frontend.
When you log into the frontend as a User who belongs to the same Lab as the Harvester,
you'll see the Harvester listed in the 'Harvesters' tab.
You can add new monitored paths to the Harvester, or change the Harvester's settings (if you have appropriate permissions).
Monitored Paths can only be created and edited by Team administrators, as a security measure.
## Restarting the harvester
If you need to restart the harvester, you can do so by running the following command:
```bash
galv-harvester --restart
```
This will restart the harvester using the previously-configured settings.
Raw data
{
"_id": null,
"home_page": null,
"name": "galv-harvester",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "battery, cycler, galv",
"author": null,
"author_email": "Matt Jaquiery <matt.jaquiery@dtc.ox.ac.uk>",
"download_url": "https://files.pythonhosted.org/packages/f5/b1/2a71211f61464b648860d71d4e4ca75ebdae2bb3e893e9867b6a0dcf2dd9/galv_harvester-0.1.0.tar.gz",
"platform": null,
"description": "# Galv Harvester (Python program)\n> A metadata secretary for battery science\n\n[](https://github.com/pypa/hatch)\n[](https://github.com/Battery-Intelligence-Lab/galv-harvester/actions/workflows/publish.yml)\n\n## Galv Project\n- [Specification](https://github.com/Battery-Intelligence-Lab/galv-spec)\n- [Backend](https://github.com/Battery-Intelligence-Lab/galv-backend)\n- [Frontend](https://github.com/Battery-Intelligence-Lab/galv-frontend)\n- [**Harvester**](https://github.com/Battery-Intelligence-Lab/galv-harvester)\n\n## Installation\n\nThe Galv Harvester can be installed from the [Python Package Index](https://pypi.org/project/galv-harvester/).\n\n```bash\npip install galv-harvester\n```\n\nThis will install the harvester and its dependencies, and make the `galv-harvester` command available.\n\n## Usage\n\nRun the harvester using the following command:\n\n```bash\ngalv-harvester\n```\n\nThe harvester will prompt you for the necessary settings to connect to the Galv server (see [Initial Setup](#initial-setup)).\n\nAlternatively, you can specify the settings as environment variables \n(see [Using Environment Variables](#using-environment-variables))\nor as [command line arguments](#using-command-line-arguments) to the `galv-harvester` program.\n\n## Initial Setup\n\nThere are three ways to set up the harvester: using the [setup wizard](#using-the-setup-wizard), \nusing [command line arguments](#using-command-line-arguments),\nor by specifying [environment variables](#using-environment-variables).\nYou can use a combination of both methods, specifying some settings in the environment and others in the wizard.\n\nIf you launch the program using the commands above, you will be prompted to enter the necessary settings by the wizard.\n\n### Using the setup wizard\n\nFirst, you'll be asked for the [Galv server](https://github.com/Battery-Intelligence-Lab/galv-backend) URL.\nThis should be the URL of the Galv server you have set up.\nProviding a frontend URL will not work, as the harvester needs to communicate with the backend.\n\nNext, you'll be asked for your API token. \nThis can be generated in either the Galv frontend or backend.\nThe token should be for a User who administers the Lab the Harvester will belong to.\n\nNext, you'll be asked to specify a name for the new Harvester. \n\nFinally, you'll be asked if you want to monitor a directory.\nIf you answer 'yes', you'll be asked for the path to the directory you want to monitor,\nand the Team that the monitored path will belong to.\n\nThe Harvester will register itself with the Galv server and begin to monitor for data files.\n\nThe `--run_foreground` flag is optional, and will keep the harvester running in the foreground.\n\n### Using environment variables\n\nYou can specify harvester properties as environment variables.\nIf you are using docker-compose, you can specify these in the `docker-compose.yml` file (see below),\nor you can specify them in your shell environment before running the harvester if you are running it as a standalone Python program.\nAny environment variables can be omitted, and the harvester will prompt you for them when you start it if they are necessary.\nFor details on the variables you can set, and whether they are necessary, see the [variable details](#variable-details) section.\n\n```yaml\n# .env\nGALV_HARVESTER_RESTART=1\nGALV_HARVESTER_SERVER_URL=<your_server_url>\nGALV_HARVESTER_NAME=<your_harvester_name>\nGALV_HARVESTER_API_TOKEN=<your_api_token>\nGALV_HARVESTER_LAB_ID=<your_lab_id>\nGALV_HARVESTER_TEAM_ID=<your_team_id>\nGALV_HARVESTER_MONITOR_PATH=<your_monitor_path>\nGALV_HARVESTER_MONITOR_PATH_REGEX=<your_monitor_path_regex>\nGALV_HARVESTER_SKIP_WIZARD=<true_or_omit>\nGALV_HARVESTER_RUN_FOREGROUND=<true_or_omit>\n```\n\nIf you don't want to have to specify the path to the data directory every time you start the harvester,\nyou can also edit the `docker-compose.yml` file to include the path as a volume.\n\n### Using command line arguments\n\nYou can also specify harvester properties as command line arguments:\n\n```text\nUsage: galv-harvester [OPTIONS]\n\nOptions:\n --version Show the version and exit.\n --url TEXT API URL to register harvester with.\n --name TEXT Name for the harvester.\n --api_token TEXT Your API token. You must have admin access to at\n least one Lab.\n --lab_id INTEGER Id of the Lab to assign the Harvester to. Only\n required if you administrate multiple Labs.\n --team_id INTEGER Id of the Team to create a Monitored Path for.\n Only required if you administrate multiple Teams\n and wish to create a monitored path.\n --monitor_path TEXT Path to harvest files from.\n --monitor_path_regex TEXT Regex to match files to harvest. Other options\n can be specified using the frontend.\n --run_foreground On completion, run the harvester in the\n foreground (will not close the thread, useful for\n Dockerized application).\n --restart Ignore other options and run harvester if config\n file already exists.\n --help Show this message and exit.\n```\n\nFor details on the variables you can set, and when they are necessary, see the [variable details](#variable-details) section.\n\n## Variable details\n\n- `GALV_HARVESTER_RESTART`: If set to 1, the harvester will attempt to resume from a previous configuration file.\n\nIf not restarting from a previous configuration, the following variables are required, \nand will be prompted for by the wizard if not set (unless `GALV_HARVESTER_SKIP_WIZARD` is set to `true`).\nIf `GALV_HARVESTER_SKIP_WIZARD` is set to `true`, you must provide these variables in the environment or the docker-compose file:\n\n- `GALV_HARVESTER_SERVER_URL`: The URL of the Galv server.\n- `GALV_HARVESTER_NAME`: The name of the harvester.\n- `GALV_HARVEST_API_TOKEN`: The API token for a User who administers the Lab the Harvester will be associated with.\n- `GALV_HARVESTER_LAB_ID`: The ID of the lab the harvester belongs to. Only required if the User administers multiple Labs.\n\nIf you want to set up a monitored path, the following variables are required:\n- `GALV_HARVESTER_TEAM_ID`: The ID of the team the monitored path will belong to. Only required if the User has multiple Teams.\n- `GALV_HARVESTER_MONITOR_PATH`: The path to the directory you want to monitor.\n\nYou may also optionally specify the following variables:\n- `GALV_HARVESTER_MONITOR_PATH_REGEX`: A regex pattern to match files in the monitored path. Only files that match this pattern will be uploaded to the Galv server.\n- `GALV_HARVESTER_SKIP_WIZARD`: If set to `true`, the harvester will not prompt you for any missing variables and setup will fail if necessary variables are not set.\n- `GALV_HARVESTER_RUN_FOREGROUND`: If set to `true`, the harvester will run in the foreground.\n\n## Further setup\n\nFurther setup can be done in the web frontend.\n\nWhen you log into the frontend as a User who belongs to the same Lab as the Harvester,\nyou'll see the Harvester listed in the 'Harvesters' tab.\n\nYou can add new monitored paths to the Harvester, or change the Harvester's settings (if you have appropriate permissions).\nMonitored Paths can only be created and edited by Team administrators, as a security measure.\n\n## Restarting the harvester\n\nIf you need to restart the harvester, you can do so by running the following command:\n\n```bash\ngalv-harvester --restart\n```\n\nThis will restart the harvester using the previously-configured settings.\n",
"bugtrack_url": null,
"license": "Copyright (c) 2020-2023, The Chancellor, Masters and Scholars of the University of Oxford, and the 'Galv' Developers. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.",
"summary": null,
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/unknown/galv-harvester#readme",
"Issues": "https://github.com/unknown/galv-harvester/issues",
"Source": "https://github.com/unknown/galv-harvester"
},
"split_keywords": [
"battery",
" cycler",
" galv"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5faf95c27f095b22d625300e17600870321fbcb51f395f6562ff65b0cf295549",
"md5": "95812c3b5e3b90462d4fbed628b9f2b9",
"sha256": "219de487785890d2c712ff0549a3d4961367f55bafe13c16d2cb0a159dbd8883"
},
"downloads": -1,
"filename": "galv_harvester-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "95812c3b5e3b90462d4fbed628b9f2b9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 35271,
"upload_time": "2024-05-01T10:17:27",
"upload_time_iso_8601": "2024-05-01T10:17:27.216328Z",
"url": "https://files.pythonhosted.org/packages/5f/af/95c27f095b22d625300e17600870321fbcb51f395f6562ff65b0cf295549/galv_harvester-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f5b12a71211f61464b648860d71d4e4ca75ebdae2bb3e893e9867b6a0dcf2dd9",
"md5": "9084ddb2fd0d671b53293dd621e36fa9",
"sha256": "23e4f54b087bb6bf5aa1985696b236d5ba5278b2f0eb30f85d15e82c8e8b10e0"
},
"downloads": -1,
"filename": "galv_harvester-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "9084ddb2fd0d671b53293dd621e36fa9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32379,
"upload_time": "2024-05-01T10:17:28",
"upload_time_iso_8601": "2024-05-01T10:17:28.845929Z",
"url": "https://files.pythonhosted.org/packages/f5/b1/2a71211f61464b648860d71d4e4ca75ebdae2bb3e893e9867b6a0dcf2dd9/galv_harvester-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-05-01 10:17:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "unknown",
"github_project": "galv-harvester#readme",
"github_not_found": true,
"lcname": "galv-harvester"
}
