| Name | marble-client JSON |
| Version |
1.3.0
JSON |
| download |
| home_page | None |
| Summary | A python client to access information about the Marble climate infomatics network |
| upload_time | 2025-08-07 15:21:50 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT License
Copyright (c) 2023 Data Analytics for Canadian Climate Services
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
|
| keywords |
climate
climate infomatics
climate data
daccs
marble
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
platformdirs
python-dateutil
requests
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Marble python client
A python library to access information about the Marble climate infomatics network. The library provides a pythonic interface to the Marble network's [central registry](https://github.com/DACCS-Climate/Marble-node-registry). Users of the network are encouraged to use this library to access the network information and avoid hardcoding URLs to various nodes or services.
## Installation
To install `marble_client` issue this command:
```shell
pip install marble-client
```
## Basic usage
The first thing to do is to get a `client` object:
```python
>>> from marble_client import MarbleClient
>>> client = MarbleClient()
```
All the information about the network can now be retrieved from the `client` object. E.g. the nodes available in the network can be accessed as:
```python
>>> client.nodes
{'UofTRedOak': <MarbleNode(id: 'UofTRedOak', name: 'Red Oak')>,
'PAVICS': <MarbleNode(id: 'PAVICS', name: 'PAVICS')>,
'Hirondelle': <MarbleNode(id: 'Hirondelle', name: 'Hirondelle')>}
```
The returned object is a python `dict` with node names for keys and `MarbleNode` objects as values. A particular node can be accessed as:
```python
>>> mynode = client['UofTRedOak']
>>> type(mynode)
marble_client.node.MarbleNode
```
Now that one has a Marble node of interest, a useful operation would be to check if that node is online in realtime, this can be done as:
```python
>>> mynode.is_online()
True
```
The URL for the node can be retrieved as:
```python
>>> mynode.url
'https://redoak.cs.toronto.edu'
```
Various other qualities about the node can be accessed as shown below (see [implementation](https://github.com/DACCS-Climate/marble_client_python/blob/main/marble_client/node.py) for the full list of available attributes).
```python
>>> mynode.affiliation
'University of Toronto'
>>> mynode.contact
'daccs-info@cs.toronto.edu'
>>> mynode.marble_version # The version of the software stack available on this node
'1.27.0'
>>> mynode.location
{'longitude': -79.39, 'latitude': 43.65}
```
The "services" that a Marble node offers can differ from one node to another. A list of which services are offered at a given node can be inquired as follows:
```python
>>> mynode.services
['geoserver',
'flyingpigeon',
'finch',
'raven',
'hummingbird',
'thredds',
'jupyterhub',
'weaver']
```
To get further information on one of the services, first retrieve that service. This can be done in one of two ways:
```python
>>> service = mynode['thredds']
>>> type(service)
marble_client.services.MarbleService
>>>
>>> service = mynode.thredds
>>> type(service)
marble_client.services.MarbleService
```
The most important thing one needs from the service is the endpoint at which the service is located:
```python
>>> service.url
'https://daccs.cs.toronto.edu/thredds/'
```
The service URL can also be accessed directly using the service object's name:
```python
>>> service
'https://daccs.cs.toronto.edu/thredds/'
```
Various attributes that can be accessed on the `MarbleService` object can be found by consulting the [implementation](https://github.com/DACCS-Climate/marble_client_python/blob/main/marble_client/services.py).
Of course, all operations can be chained, so if you don't need `MarbleClient`, `MarbleNode` or `MarbleService` objects for future operations, then to get, for example, the weaver service endpoint for the "PAVICS" node, one can do:
```python
>>> url = MarbleClient()["PAVICS"].weaver.url # returns a string object
>>> print(f"Weaver URL is {url}")
Weaver URL is https://pavics.ouranos.ca/weaver/
>>> # A MarbleService object is returned that can be used wherever a string can be used
>>> print(f"Weaver URL is {MarbleClient()['PAVICS'].weaver}")
Weaver URL is https://pavics.ouranos.ca/weaver/
```
## Jupyterlab functionality
When running in a Marble Jupyterlab environment, the client can take advantage of various environment variables and
Jupyter's API to provide some additional functionality.
> [!WARNING]
> Calling any of the methods described below outside a Marble Jupyterlab environment will raise a
> `JupyterEnvironmentError`.
Get the node your notebook/script is currently running on:
```python
>>> client = MarbleClient()
>>> client.this_node
<MarbleNode(id: 'UofTRedOak', name: 'Red Oak')>
```
Add session cookies to a `requests.Session` object. This means that any request made with that session variable will
be made as if you were logged in to the current Marble node. This is the recommended way to access protected resources
programmatically in your scripts:
```python
>>> client = MarbleClient()
>>> session = requests.Session()
>>> client.this_session(session)
>>> session.cookies.get_dict()
{...} # session cookiejar now includes cookies
```
You can also use the `this_session` method to create a new `requests.Session` object:
```python
>>> client = MarbleClient()
>>> session = client.this_session()
>>> session.cookies.get_dict()
{...} # now includes session cookies
```
You can now make a request to a protected resource on the current node using this session object. You will be able to
access the resource if you have permission:
```python
>>> session.get(f"{client.this_node.url}/some/protected/subpath")
```
## Interactively logging in to a node
In order to login to a different node or if you're running a script or notebook from outside a Marble
Jupyterlab environment, use the `MarbleNode.login` function to generate a `requests.Session` object.
This will prompt you to input your credentials to `stdin` or an input widget if you're in a compatible
Jupyter environment.
## Contributing
We welcome any contributions to this codebase. To submit suggested changes, please do the following:
- create a new feature branch off of `main`
- update the code, write/update tests, write/update documentation
- submit a pull request targetting the `main` branch
To develop this project locally, first clone this repository and install the testing and development
dependencies:
```sh
pip install -e .[dev,test]
```
### Testing
Tests are located in the `tests/` folder can be run using `pytest`:
```sh
pytest tests/
```
### Coding Style
This codebase uses the [`ruff`](https://docs.astral.sh/ruff/) formatter and linter to enforce style policies.
To check that your changes conform to these policies please run:
```sh
ruff format
ruff check
```
You can also set up pre-commit hooks that will run these checks before you create any commit in this repo:
```sh
pre-commit install
```
Raw data
{
"_id": null,
"home_page": null,
"name": "marble-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "climate, climate infomatics, climate data, DACCS, Marble",
"author": null,
"author_email": "Deepak Chandan <dchandan@cs.toronto.edu>",
"download_url": "https://files.pythonhosted.org/packages/e1/a1/37f3b4fc7a6f56f97868ed03effb644cc3d49cd4b48123c8dd3076c28685/marble_client-1.3.0.tar.gz",
"platform": null,
"description": "# Marble python client\nA python library to access information about the Marble climate infomatics network. The library provides a pythonic interface to the Marble network's [central registry](https://github.com/DACCS-Climate/Marble-node-registry). Users of the network are encouraged to use this library to access the network information and avoid hardcoding URLs to various nodes or services.\n\n## Installation\n\nTo install `marble_client` issue this command:\n```shell\npip install marble-client\n``` \n\n## Basic usage\n\nThe first thing to do is to get a `client` object:\n\n```python\n>>> from marble_client import MarbleClient\n\n>>> client = MarbleClient()\n```\n\nAll the information about the network can now be retrieved from the `client` object. E.g. the nodes available in the network can be accessed as:\n```python\n>>> client.nodes\n{'UofTRedOak': <MarbleNode(id: 'UofTRedOak', name: 'Red Oak')>, \n 'PAVICS': <MarbleNode(id: 'PAVICS', name: 'PAVICS')>, \n 'Hirondelle': <MarbleNode(id: 'Hirondelle', name: 'Hirondelle')>}\n```\nThe returned object is a python `dict` with node names for keys and `MarbleNode` objects as values. A particular node can be accessed as:\n\n```python\n>>> mynode = client['UofTRedOak']\n>>> type(mynode)\nmarble_client.node.MarbleNode\n```\n\nNow that one has a Marble node of interest, a useful operation would be to check if that node is online in realtime, this can be done as:\n\n```python\n>>> mynode.is_online()\nTrue\n```\n\nThe URL for the node can be retrieved as:\n```python\n>>> mynode.url\n'https://redoak.cs.toronto.edu'\n```\n\nVarious other qualities about the node can be accessed as shown below (see [implementation](https://github.com/DACCS-Climate/marble_client_python/blob/main/marble_client/node.py) for the full list of available attributes).\n\n```python\n>>> mynode.affiliation\n'University of Toronto'\n>>> mynode.contact\n'daccs-info@cs.toronto.edu'\n>>> mynode.marble_version # The version of the software stack available on this node\n'1.27.0'\n>>> mynode.location\n{'longitude': -79.39, 'latitude': 43.65}\n```\n\nThe \"services\" that a Marble node offers can differ from one node to another. A list of which services are offered at a given node can be inquired as follows:\n```python\n>>> mynode.services\n['geoserver',\n 'flyingpigeon',\n 'finch',\n 'raven',\n 'hummingbird',\n 'thredds',\n 'jupyterhub',\n 'weaver']\n```\n\nTo get further information on one of the services, first retrieve that service. This can be done in one of two ways:\n```python\n>>> service = mynode['thredds']\n>>> type(service)\nmarble_client.services.MarbleService\n>>> \n>>> service = mynode.thredds\n>>> type(service)\nmarble_client.services.MarbleService\n```\n\nThe most important thing one needs from the service is the endpoint at which the service is located:\n```python\n>>> service.url\n'https://daccs.cs.toronto.edu/thredds/'\n```\n\nThe service URL can also be accessed directly using the service object's name:\n```python\n>>> service\n'https://daccs.cs.toronto.edu/thredds/'\n```\n\nVarious attributes that can be accessed on the `MarbleService` object can be found by consulting the [implementation](https://github.com/DACCS-Climate/marble_client_python/blob/main/marble_client/services.py).\n\nOf course, all operations can be chained, so if you don't need `MarbleClient`, `MarbleNode` or `MarbleService` objects for future operations, then to get, for example, the weaver service endpoint for the \"PAVICS\" node, one can do:\n```python\n>>> url = MarbleClient()[\"PAVICS\"].weaver.url # returns a string object\n>>> print(f\"Weaver URL is {url}\")\nWeaver URL is https://pavics.ouranos.ca/weaver/\n>>> # A MarbleService object is returned that can be used wherever a string can be used\n>>> print(f\"Weaver URL is {MarbleClient()['PAVICS'].weaver}\")\nWeaver URL is https://pavics.ouranos.ca/weaver/\n```\n\n## Jupyterlab functionality\n\nWhen running in a Marble Jupyterlab environment, the client can take advantage of various environment variables and \nJupyter's API to provide some additional functionality. \n\n> [!WARNING]\n> Calling any of the methods described below outside a Marble Jupyterlab environment will raise a \n> `JupyterEnvironmentError`.\n\nGet the node your notebook/script is currently running on:\n\n```python\n>>> client = MarbleClient()\n>>> client.this_node\n<MarbleNode(id: 'UofTRedOak', name: 'Red Oak')>\n```\n\nAdd session cookies to a `requests.Session` object. This means that any request made with that session variable will\nbe made as if you were logged in to the current Marble node. This is the recommended way to access protected resources\nprogrammatically in your scripts:\n\n```python\n>>> client = MarbleClient()\n>>> session = requests.Session()\n>>> client.this_session(session)\n>>> session.cookies.get_dict()\n{...} # session cookiejar now includes cookies\n```\n\nYou can also use the `this_session` method to create a new `requests.Session` object:\n\n```python\n>>> client = MarbleClient()\n>>> session = client.this_session()\n>>> session.cookies.get_dict()\n{...} # now includes session cookies\n```\n\nYou can now make a request to a protected resource on the current node using this session object. You will be able to \naccess the resource if you have permission:\n\n```python\n>>> session.get(f\"{client.this_node.url}/some/protected/subpath\")\n```\n\n## Interactively logging in to a node\n\nIn order to login to a different node or if you're running a script or notebook from outside a Marble\nJupyterlab environment, use the `MarbleNode.login` function to generate a `requests.Session` object.\n\nThis will prompt you to input your credentials to `stdin` or an input widget if you're in a compatible \nJupyter environment.\n\n## Contributing\n\nWe welcome any contributions to this codebase. To submit suggested changes, please do the following:\n\n- create a new feature branch off of `main`\n- update the code, write/update tests, write/update documentation\n- submit a pull request targetting the `main` branch\n\nTo develop this project locally, first clone this repository and install the testing and development\ndependencies:\n\n```sh\npip install -e .[dev,test]\n```\n\n### Testing\n\nTests are located in the `tests/` folder can be run using `pytest`:\n\n```sh\npytest tests/\n```\n\n### Coding Style\n\nThis codebase uses the [`ruff`](https://docs.astral.sh/ruff/) formatter and linter to enforce style policies.\n\nTo check that your changes conform to these policies please run:\n\n```sh\nruff format\nruff check\n```\n\nYou can also set up pre-commit hooks that will run these checks before you create any commit in this repo:\n\n```sh\npre-commit install\n```\n",
"bugtrack_url": null,
"license": "MIT License\n \n Copyright (c) 2023 Data Analytics for Canadian Climate Services\n \n Permission is hereby granted, free of charge, to any person obtaining a copy\n of this software and associated documentation files (the \"Software\"), to deal\n in the Software without restriction, including without limitation the rights\n to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n copies of the Software, and to permit persons to whom the Software is\n furnished to do so, subject to the following conditions:\n \n The above copyright notice and this permission notice shall be included in all\n copies or substantial portions of the Software.\n \n THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\n LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\n OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\n SOFTWARE.\n ",
"summary": "A python client to access information about the Marble climate infomatics network",
"version": "1.3.0",
"project_urls": {
"Bug Tracker": "https://github.com/DACCS-Climate/marble_client_python/issues",
"Homepage": "https://github.com/DACCS-Climate/marble_client_python"
},
"split_keywords": [
"climate",
" climate infomatics",
" climate data",
" daccs",
" marble"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "7bb3d4d7b05d2c3727ddcf9569122ed07af0a7315e818a561675384e8d264e65",
"md5": "9d482a54c3f3937526107a733190f223",
"sha256": "9aaac64bd7be5dcd1bc7d51e4efde622cfc29ddbcadefe3235f482131985c97a"
},
"downloads": -1,
"filename": "marble_client-1.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d482a54c3f3937526107a733190f223",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 13797,
"upload_time": "2025-08-07T15:21:49",
"upload_time_iso_8601": "2025-08-07T15:21:49.195077Z",
"url": "https://files.pythonhosted.org/packages/7b/b3/d4d7b05d2c3727ddcf9569122ed07af0a7315e818a561675384e8d264e65/marble_client-1.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e1a137f3b4fc7a6f56f97868ed03effb644cc3d49cd4b48123c8dd3076c28685",
"md5": "b29f7836f16535752ccbadff57c1bb36",
"sha256": "fc5472bb45a48f5de3c6960227fde62560770ce9b1186cbda5d3fa41f30c1499"
},
"downloads": -1,
"filename": "marble_client-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "b29f7836f16535752ccbadff57c1bb36",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 17399,
"upload_time": "2025-08-07T15:21:50",
"upload_time_iso_8601": "2025-08-07T15:21:50.277061Z",
"url": "https://files.pythonhosted.org/packages/e1/a1/37f3b4fc7a6f56f97868ed03effb644cc3d49cd4b48123c8dd3076c28685/marble_client-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-07 15:21:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DACCS-Climate",
"github_project": "marble_client_python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "platformdirs",
"specs": [
[
"~=",
"4.2"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"~=",
"2.8"
]
]
},
{
"name": "requests",
"specs": [
[
"~=",
"2.31"
]
]
}
],
"lcname": "marble-client"
}
