Informatics Matters Squonk2 Python Client
=========================================
.. image:: https://badge.fury.io/py/im-squonk2-client.svg
:target: https://badge.fury.io/py/im-squonk2-client
:alt: PyPI package (latest)
.. image:: https://readthedocs.org/projects/squonk2-python-client/badge/?version=latest
:target: https://squonk2-python-client.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
.. image:: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/build.yaml/badge.svg
:target: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/build.yaml
:alt: Build
.. image:: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/publish.yaml/badge.svg
:target: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/publish.yaml
:alt: Publish
A Python 3 package that provides simplified access to key parts of the
Informatics Matters Squonk2 service, consisting of the Authentication, and
Data Manager and Account Server REST interfaces. The functions provide
access to some of the key API methods, implemented initially to support
execution of Jobs from a Fragalysis stack `backend`_.
.. note::
Odd numbered *major* versions of the client are used for the *synchronous* API
and even-numbered *major* versions are used for the *asynchronous* API.
Version ``1.x.x`` of the client can only be used against the Data Manager
version ``1``. Version ``3.x.x`` must be used for Data Manager version ``2``
and later.
Simplified Authentication
=========================
The following Squonk2 Authentication functions are available: -
- ``Auth.get_access_token()``
Simplified Data Manager API
===========================
The following Squonk2 Data Manager API functions are available: -
- ``DmApi.set_api_url()``
- ``DmApi.get_api_url()``
- ``DmApi.ping()``
- ``DmApi.add_project_editor()``
- ``DmApi.add_project_observer()``
- ``DmApi.create_project()``
- ``DmApi.delete_instance()``
- ``DmApi.delete_instance_token()``
- ``DmApi.delete_project()``
- ``DmApi.delete_unmanaged_project_files()``
- ``DmApi.dry_run_job_instance()``
- ``DmApi.get_account_server_namespace()``
- ``DmApi.get_account_server_registration()``
- ``DmApi.get_available_instances()``
- ``DmApi.get_available_datasets()``
- ``DmApi.get_available_jobs()``
- ``DmApi.get_available_projects()``
- ``DmApi.get_available_tasks()``
- ``DmApi.get_job()``
- ``DmApi.get_job_exchange_rates()``
- ``DmApi.get_job_by_version()``
- ``DmApi.get_instance()``
- ``DmApi.get_project()``
- ``DmApi.get_project_instances()``
- ``DmApi.get_service_errors()``
- ``DmApi.get_task()``
- ``DmApi.get_tasks()``
- ``DmApi.get_unmanaged_project_file()``
- ``DmApi.get_unmanaged_project_file_with_token()``
- ``DmApi.get_version()``
- ``DmApi.list_project_files()``
- ``DmApi.put_unmanaged_project_files()``
- ``DmApi.put_job_manifest()``
- ``DmApi.remove_project_editor()``
- ``DmApi.remove_project_observer()``
- ``DmApi.set_admin_state()``
- ``DmApi.set_job_exchange_rates()``
- ``DmApi.start_job_instance()``
A ``dataclass`` is used as the return value for many of the methods: -
- ``DmApiRv``
It contains a boolean ``success`` field and a dictionary ``msg`` field. The
``msg`` typically contains the underlying REST API response content
(rendered as a Python dictionary), or an error message if the call failed.
Simplified Account Server API
=============================
The following Squonk2 Account Server API functions are available: -
- ``AsApi.set_api_url()``
- ``AsApi.get_api_url()``
- ``AsApi.ping()``
- ``AsApi.create_product()``
- ``AsApi.create_unit()``
- ``AsApi.create_organisation()``
- ``AsApi.delete_product()``
- ``AsApi.delete_unit()``
- ``AsApi.get_available_assets()``
- ``AsApi.get_available_units()``
- ``AsApi.get_available_products()``
- ``AsApi.get_merchants()``
- ``AsApi.get_organisation()``
- ``AsApi.get_product()``
- ``AsApi.get_products_for_unit()``
- ``AsApi.get_products_for_organisation()``
- ``AsApi.get_product_charges()``
- ``AsApi.get_organisations()``
- ``AsApi.get_unit()``
- ``AsApi.get_units()``
- ``AsApi.get_version()``
A ``dataclass`` is used as the return value for many of the methods: -
- ``AsApiRv``
It contains a boolean ``success`` field and a dictionary ``msg`` field. The
``msg`` typically contains the underlying REST API response content
(rendered as a Python dictionary), or an error message if the call failed.
Simplified UI API
=================
The following Squonk2 UI API functions are available: -
- ``UiApi.set_api_url()``
- ``UiApi.get_version()``
A ``namedtuple`` is used as the return value for many of the methods: -
- ``UiApiRv``
It contains a boolean ``success`` field and a dictionary ``msg`` field. The
``msg`` typically contains the underlying REST API response content
(rendered as a Python dictionary), or an error message if the call failed.
Examples
========
The package ships with some API examples that might be useful for your own work.
They are located in the package ``examples`` module, where the following imports
should be available: -
- ``from squonk2.examples.data_manager import job_chain``
Debugging the API requests
==========================
For development purposes you can expose detailed debug information relating to
the underlying API requests by setting the environment variable
``SQUONK2_API_DEBUG_REQUESTS``::
export SQUONK2_API_DEBUG_REQUESTS=yes
This will enable detailed debug of both the DM and AS API calls.
Installation
============
The Squonk2 package is published on `PyPI`_ and can be installed from
there::
pip install im-squonk2-client
Environment module
==================
The API contains a convenient ``Environment`` module that allows you to
keep your environment variables in a file so that you don't need to
declare them in the shell. The default location of the file is
``~/.squonk2/environments``. If you have multiple installations this
allows you to keep all your environment settings together in one file.
You can use an alternative file by setting ``SQUONK2_ENVIRONMENTS_FILE``,
e.g. ``export SQUONK2_ENVIRONMENTS_FILE=~/my-env'``
.. code-block:: yaml
---
# An example Squeck environments file.
#
# It provides all the connection details for one or more Squonk2 environments.
# It is expected to be found in the user's home directory
# as '~/.squonk2/environments' or the user can 'point' to it by setting
# 'SQUONK2_ENVIRONMENTS_FILE', e.g. 'export SQUONK2_ENVIRONMENTS_FILE=~/my-env'
# The 'environments' block defines one or more environments.
# Each has a name. Here we define an environment called 'site-a'
# but environments can be called anything YAML accepts as a key,
# although it would aid consistency if you restrict your names to letters
# and hyphens.
environments:
site-a:
# The hostname of the keycloak server, without a 'http' prefix
# and without a '/auth' suffix.
keycloak-hostname: example.com
# The realm name used for the Squonk2 environment.
keycloak-realm: squonk2
# The Keycloak client IDs of the Account Server and Data Manager.
# The Account Server client ID is optional.
keycloak-as-client-id: account-server-api
keycloak-dm-client-id: data-manager-api
# The hostnames of the Account Server and Data Manager APIs,
# without a 'http' prefix and without an 'api' suffix.
# If you have not provided an Account Server client ID its
# hostname value is not required.
as-hostname: as.example.com
dm-hostname: dm.example.com
# The username and password of an admin user that has access
# to the Account Server and Data Manager.
# The user *MUST* have admin rights.
admin-user: dlister
admin-password: blob1234
# The final part of the file is a 'default' property,
# which Squeck (Squonk Deck) uses to select the an environment from the block above
# when all else fails. It's simply the name of one of the environment
# declarations above.
default: site-a
To avoid placing ``admin-user`` and ``admin-password`` values into the Environment file
you can provide them through environment variables that are scoped to the
environment name. For example, in the above you could omit them both
and provide them as values using the following variables: -
- ``SQUONK2_ENVIRONMENT_SITE_A_ADMIN_USER``
- ``SQUONK2_ENVIRONMENT_SITE_A_ADMIN_PASSWORD``
**Using the Environment**
.. code-block:: python
from squonk2.environment import Environment
_ = Environment.load()
environment: Environment = Environment('site-a')
# Get the AS API for 'local'
# The hostname is augmented so you will get (for the above example)
# the value 'https://as.example.com/account-server-api'
as_api: str = environment.as_api()
Documentation
=============
Documentation is available in the `squonk2-python-client`_ project on
**Read the Docs**
Get in touch
============
- Report bugs, suggest features or view the source code `on GitHub`_.
.. _on GitHub: https://github.com/informaticsmatters/squonk2-python-client
.. _backend: https://github.com/xchem/fragalysis-backend
.. _squonk2-python-client: https://squonk2-python-client.readthedocs.io/en/latest/
.. _PyPI: https://pypi.org/project/im-squonk2-client
Raw data
{
"_id": null,
"home_page": "https://github.com/informaticsmatters/squonk2-python-client",
"name": "im-squonk2-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3",
"maintainer_email": null,
"keywords": "api",
"author": "Alan Christie",
"author_email": "achristie@informaticsmatters.com",
"download_url": "https://files.pythonhosted.org/packages/8b/f7/dfd5920803ce25075e1341e70b344481db8049469d292b13a72f8e9212fe/im_squonk2_client-4.0.0.tar.gz",
"platform": "any",
"description": "Informatics Matters Squonk2 Python Client\n=========================================\n\n.. image:: https://badge.fury.io/py/im-squonk2-client.svg\n :target: https://badge.fury.io/py/im-squonk2-client\n :alt: PyPI package (latest)\n\n.. image:: https://readthedocs.org/projects/squonk2-python-client/badge/?version=latest\n :target: https://squonk2-python-client.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/build.yaml/badge.svg\n :target: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/build.yaml\n :alt: Build\n\n.. image:: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/publish.yaml/badge.svg\n :target: https://github.com/InformaticsMatters/squonk2-python-client/actions/workflows/publish.yaml\n :alt: Publish\n\nA Python 3 package that provides simplified access to key parts of the\nInformatics Matters Squonk2 service, consisting of the Authentication, and\nData Manager and Account Server REST interfaces. The functions provide\naccess to some of the key API methods, implemented initially to support\nexecution of Jobs from a Fragalysis stack `backend`_.\n\n.. note::\n Odd numbered *major* versions of the client are used for the *synchronous* API\n and even-numbered *major* versions are used for the *asynchronous* API.\n Version ``1.x.x`` of the client can only be used against the Data Manager\n version ``1``. Version ``3.x.x`` must be used for Data Manager version ``2``\n and later.\n\nSimplified Authentication\n=========================\nThe following Squonk2 Authentication functions are available: -\n\n- ``Auth.get_access_token()``\n\nSimplified Data Manager API\n===========================\nThe following Squonk2 Data Manager API functions are available: -\n\n- ``DmApi.set_api_url()``\n- ``DmApi.get_api_url()``\n\n- ``DmApi.ping()``\n\n- ``DmApi.add_project_editor()``\n- ``DmApi.add_project_observer()``\n- ``DmApi.create_project()``\n- ``DmApi.delete_instance()``\n- ``DmApi.delete_instance_token()``\n- ``DmApi.delete_project()``\n- ``DmApi.delete_unmanaged_project_files()``\n- ``DmApi.dry_run_job_instance()``\n- ``DmApi.get_account_server_namespace()``\n- ``DmApi.get_account_server_registration()``\n- ``DmApi.get_available_instances()``\n- ``DmApi.get_available_datasets()``\n- ``DmApi.get_available_jobs()``\n- ``DmApi.get_available_projects()``\n- ``DmApi.get_available_tasks()``\n- ``DmApi.get_job()``\n- ``DmApi.get_job_exchange_rates()``\n- ``DmApi.get_job_by_version()``\n- ``DmApi.get_instance()``\n- ``DmApi.get_project()``\n- ``DmApi.get_project_instances()``\n- ``DmApi.get_service_errors()``\n- ``DmApi.get_task()``\n- ``DmApi.get_tasks()``\n- ``DmApi.get_unmanaged_project_file()``\n- ``DmApi.get_unmanaged_project_file_with_token()``\n- ``DmApi.get_version()``\n- ``DmApi.list_project_files()``\n- ``DmApi.put_unmanaged_project_files()``\n- ``DmApi.put_job_manifest()``\n- ``DmApi.remove_project_editor()``\n- ``DmApi.remove_project_observer()``\n- ``DmApi.set_admin_state()``\n- ``DmApi.set_job_exchange_rates()``\n- ``DmApi.start_job_instance()``\n\nA ``dataclass`` is used as the return value for many of the methods: -\n\n- ``DmApiRv``\n\nIt contains a boolean ``success`` field and a dictionary ``msg`` field. The\n``msg`` typically contains the underlying REST API response content\n(rendered as a Python dictionary), or an error message if the call failed.\n\nSimplified Account Server API\n=============================\nThe following Squonk2 Account Server API functions are available: -\n\n- ``AsApi.set_api_url()``\n- ``AsApi.get_api_url()``\n\n- ``AsApi.ping()``\n\n- ``AsApi.create_product()``\n- ``AsApi.create_unit()``\n- ``AsApi.create_organisation()``\n- ``AsApi.delete_product()``\n- ``AsApi.delete_unit()``\n- ``AsApi.get_available_assets()``\n- ``AsApi.get_available_units()``\n- ``AsApi.get_available_products()``\n- ``AsApi.get_merchants()``\n- ``AsApi.get_organisation()``\n- ``AsApi.get_product()``\n- ``AsApi.get_products_for_unit()``\n- ``AsApi.get_products_for_organisation()``\n- ``AsApi.get_product_charges()``\n- ``AsApi.get_organisations()``\n- ``AsApi.get_unit()``\n- ``AsApi.get_units()``\n- ``AsApi.get_version()``\n\nA ``dataclass`` is used as the return value for many of the methods: -\n\n- ``AsApiRv``\n\nIt contains a boolean ``success`` field and a dictionary ``msg`` field. The\n``msg`` typically contains the underlying REST API response content\n(rendered as a Python dictionary), or an error message if the call failed.\n\nSimplified UI API\n=================\nThe following Squonk2 UI API functions are available: -\n\n- ``UiApi.set_api_url()``\n\n- ``UiApi.get_version()``\n\nA ``namedtuple`` is used as the return value for many of the methods: -\n\n- ``UiApiRv``\n\nIt contains a boolean ``success`` field and a dictionary ``msg`` field. The\n``msg`` typically contains the underlying REST API response content\n(rendered as a Python dictionary), or an error message if the call failed.\n\nExamples\n========\nThe package ships with some API examples that might be useful for your own work.\nThey are located in the package ``examples`` module, where the following imports\nshould be available: -\n\n- ``from squonk2.examples.data_manager import job_chain``\n\nDebugging the API requests\n==========================\nFor development purposes you can expose detailed debug information relating to\nthe underlying API requests by setting the environment variable\n``SQUONK2_API_DEBUG_REQUESTS``::\n\n export SQUONK2_API_DEBUG_REQUESTS=yes\n\nThis will enable detailed debug of both the DM and AS API calls.\n\nInstallation\n============\nThe Squonk2 package is published on `PyPI`_ and can be installed from\nthere::\n\n pip install im-squonk2-client\n\nEnvironment module\n==================\nThe API contains a convenient ``Environment`` module that allows you to\nkeep your environment variables in a file so that you don't need to\ndeclare them in the shell. The default location of the file is\n``~/.squonk2/environments``. If you have multiple installations this\nallows you to keep all your environment settings together in one file.\n\nYou can use an alternative file by setting ``SQUONK2_ENVIRONMENTS_FILE``,\ne.g. ``export SQUONK2_ENVIRONMENTS_FILE=~/my-env'``\n\n.. code-block:: yaml\n\n ---\n\n # An example Squeck environments file.\n #\n # It provides all the connection details for one or more Squonk2 environments.\n # It is expected to be found in the user's home directory\n # as '~/.squonk2/environments' or the user can 'point' to it by setting\n # 'SQUONK2_ENVIRONMENTS_FILE', e.g. 'export SQUONK2_ENVIRONMENTS_FILE=~/my-env'\n\n # The 'environments' block defines one or more environments.\n # Each has a name. Here we define an environment called 'site-a'\n # but environments can be called anything YAML accepts as a key,\n # although it would aid consistency if you restrict your names to letters\n # and hyphens.\n environments:\n site-a:\n # The hostname of the keycloak server, without a 'http' prefix\n # and without a '/auth' suffix.\n keycloak-hostname: example.com\n # The realm name used for the Squonk2 environment.\n keycloak-realm: squonk2\n # The Keycloak client IDs of the Account Server and Data Manager.\n # The Account Server client ID is optional.\n keycloak-as-client-id: account-server-api\n keycloak-dm-client-id: data-manager-api\n # The hostnames of the Account Server and Data Manager APIs,\n # without a 'http' prefix and without an 'api' suffix.\n # If you have not provided an Account Server client ID its\n # hostname value is not required.\n as-hostname: as.example.com\n dm-hostname: dm.example.com\n # The username and password of an admin user that has access\n # to the Account Server and Data Manager.\n # The user *MUST* have admin rights.\n admin-user: dlister\n admin-password: blob1234\n\n # The final part of the file is a 'default' property,\n # which Squeck (Squonk Deck) uses to select the an environment from the block above\n # when all else fails. It's simply the name of one of the environment\n # declarations above.\n default: site-a\n\nTo avoid placing ``admin-user`` and ``admin-password`` values into the Environment file\nyou can provide them through environment variables that are scoped to the\nenvironment name. For example, in the above you could omit them both\nand provide them as values using the following variables: -\n\n- ``SQUONK2_ENVIRONMENT_SITE_A_ADMIN_USER``\n- ``SQUONK2_ENVIRONMENT_SITE_A_ADMIN_PASSWORD``\n\n**Using the Environment**\n\n.. code-block:: python\n\n from squonk2.environment import Environment\n\n _ = Environment.load()\n environment: Environment = Environment('site-a')\n # Get the AS API for 'local'\n # The hostname is augmented so you will get (for the above example)\n # the value 'https://as.example.com/account-server-api'\n as_api: str = environment.as_api()\n\nDocumentation\n=============\nDocumentation is available in the `squonk2-python-client`_ project on\n**Read the Docs**\n\nGet in touch\n============\n\n- Report bugs, suggest features or view the source code `on GitHub`_.\n\n.. _on GitHub: https://github.com/informaticsmatters/squonk2-python-client\n.. _backend: https://github.com/xchem/fragalysis-backend\n.. _squonk2-python-client: https://squonk2-python-client.readthedocs.io/en/latest/\n.. _PyPI: https://pypi.org/project/im-squonk2-client\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Squonk2 Python Client",
"version": "4.0.0",
"project_urls": {
"Homepage": "https://github.com/informaticsmatters/squonk2-python-client"
},
"split_keywords": [
"api"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "708d3f8a433172d7948730ac99c739cfad97973a70941333dff362079b3db28f",
"md5": "323757d527c975b35651e7e5dee9cfd8",
"sha256": "a2ba0382999999e605514505a1ed9d00054149da1a889bc8bc6fcb89ba3deaf1"
},
"downloads": -1,
"filename": "im_squonk2_client-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "323757d527c975b35651e7e5dee9cfd8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3",
"size": 30077,
"upload_time": "2024-08-12T10:48:09",
"upload_time_iso_8601": "2024-08-12T10:48:09.022109Z",
"url": "https://files.pythonhosted.org/packages/70/8d/3f8a433172d7948730ac99c739cfad97973a70941333dff362079b3db28f/im_squonk2_client-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8bf7dfd5920803ce25075e1341e70b344481db8049469d292b13a72f8e9212fe",
"md5": "c22b444a9d07eb5a383ff0549f24bb5a",
"sha256": "40b241e1424986e2e40235d5d59b62e654229807816b13bf7460a9c385e8538a"
},
"downloads": -1,
"filename": "im_squonk2_client-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c22b444a9d07eb5a383ff0549f24bb5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3",
"size": 27248,
"upload_time": "2024-08-12T10:48:10",
"upload_time_iso_8601": "2024-08-12T10:48:10.355347Z",
"url": "https://files.pythonhosted.org/packages/8b/f7/dfd5920803ce25075e1341e70b344481db8049469d292b13a72f8e9212fe/im_squonk2_client-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-12 10:48:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "informaticsmatters",
"github_project": "squonk2-python-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "authlib",
"specs": [
[
"<",
"2.0"
],
[
">=",
"1.0.1"
]
]
},
{
"name": "pyyaml",
"specs": [
[
"<",
"7.0"
],
[
">=",
"5.2"
]
]
},
{
"name": "requests",
"specs": [
[
">=",
"2.22.0"
]
]
},
{
"name": "wrapt",
"specs": [
[
"<",
"2.0"
],
[
">=",
"1.14.1"
]
]
}
],
"lcname": "im-squonk2-client"
}
JSON
