| Name | marble-client JSON |
| Version |
1.1.2
JSON |
| download |
| home_page | None |
| Summary | A python client to access information about the Marble climate infomatics network |
| upload_time | 2024-04-01 13:48:46 |
| 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
bump2version
|
| 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
{'UofT': <marble_client.node.MarbleNode at 0x10c129990>,
'PAVICS': <marble_client.node.MarbleNode at 0x10c6dd690>,
'Hirondelle': <marble_client.node.MarbleNode at 0x10c6dd890>}
```
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['UofT']
>>> 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://daccs.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
<marble_client.node.MarbleNode at 0x10c129990>
```
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")
```
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/d0/a8/3d98f2c216451c5fe028bf21ad9e093ede9745cf12387418c230185c7b2d/marble_client-1.1.2.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{'UofT': <marble_client.node.MarbleNode at 0x10c129990>,\n 'PAVICS': <marble_client.node.MarbleNode at 0x10c6dd690>,\n 'Hirondelle': <marble_client.node.MarbleNode at 0x10c6dd890>}\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['UofT']\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://daccs.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<marble_client.node.MarbleNode at 0x10c129990>\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",
"bugtrack_url": null,
"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. ",
"summary": "A python client to access information about the Marble climate infomatics network",
"version": "1.1.2",
"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": "",
"digests": {
"blake2b_256": "230435ec2e5fc35c0db0720990803772e3225b31d14b22ec9024016c018b50f1",
"md5": "53e484454e40396841676b89048d2d5b",
"sha256": "7ede1dc344db5a9b7ccfd3cfee43543810024459c04ddc925f45b7ef26551a58"
},
"downloads": -1,
"filename": "marble_client-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "53e484454e40396841676b89048d2d5b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9922,
"upload_time": "2024-04-01T13:48:45",
"upload_time_iso_8601": "2024-04-01T13:48:45.214842Z",
"url": "https://files.pythonhosted.org/packages/23/04/35ec2e5fc35c0db0720990803772e3225b31d14b22ec9024016c018b50f1/marble_client-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d0a83d98f2c216451c5fe028bf21ad9e093ede9745cf12387418c230185c7b2d",
"md5": "9832a0daf2c28fa57bdb835e2af79d32",
"sha256": "3ed98cbf6b8b7a70b43fbb319073c93e5d115ead8249cbd1afe33e44419ee22b"
},
"downloads": -1,
"filename": "marble_client-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "9832a0daf2c28fa57bdb835e2af79d32",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 10442,
"upload_time": "2024-04-01T13:48:46",
"upload_time_iso_8601": "2024-04-01T13:48:46.798780Z",
"url": "https://files.pythonhosted.org/packages/d0/a8/3d98f2c216451c5fe028bf21ad9e093ede9745cf12387418c230185c7b2d/marble_client-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-01 13:48:46",
"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.0"
]
]
},
{
"name": "python-dateutil",
"specs": [
[
"==",
"2.8.2"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "bump2version",
"specs": [
[
">=",
"1.0.1"
]
]
}
],
"lcname": "marble-client"
}
