Skip to main content

hyperscience saas client library

Project description

Hyperscience SaaS Client Library

With the Hyperscience SaaS client library, you can authenticate to SaaS instances of Hyperscience and make API requests.

Quickstart Guide

1. Install Hyperscience SaaS Client Library

Install the Hyperscience SAAS Client Library from PyPI:

pip install hyperscience-saas-client

To upgrade the package:

pip install hyperscience-saas-client --upgrade

2. Set Up API Credentials

Retrieve your API credentials from your Hyperscience SaaS instance. To learn more, see API Access for SaaS Instances.

3. Configure Authentication Parameters

To configure authentication, the ApiController uses a Configuration class. A configuration object contains:

  • Authentication domain ("auth_server”)
  • Hyperscience's domain to make the requests to ("hs_domain")
  • Timeout for requests in seconds (optional) ("request_timeout")

By default, these values are used:

{
    "auth_server": "login.hyperscience.net",
    "hs_domain": "cloud.hyperscience.net",
    "request_timeout": 120 
}

You can set your Configuration object in one of the following three ways:

Passing a JSON object

from hyperscience import Configuration

config = '{ "auth_server": "login.hyperscience.net", "hs_domain": "cloud.hyperscience.net" }'
configuration = Configuration.from_json_string(config)

Full path to a JSON file containing the configuration

from hyperscience import Configuration

configuration = Configuration.from_file('/absolute/path/to/config.json')

Specifying the parameters

from hyperscience import Configuration
configuration = Configuration(hs_domain='cloud.hyperscience.net')
# or
configuration = Configuration(hs_domain='cloud.hyperscience.net', auth_server='login.hyperscience.net')
# or 
configuration = Configuration(
    hs_domain='cloud.hyperscience.net', auth_server='login.hyperscience.net', request_timeout=60
)

4. Provide Credentials

There are two options for providing credentials:

a. Environment Variables (Recommended)

To use environment variables to store your credentials:

  1. Put your client_id in an environment variable called HS_CLIENT_ID
  2. Put the client_secret in an environment variable called HS_CLIENT_SECRET

To load them and pass them to ApiController, you can do it with:

from hyperscience import EnvironmentCredentialsProvider, Configuration, ApiController

credentials = EnvironmentCredentialsProvider()
configuration = Configuration('<hyperscience.domain>')
api_controller = ApiController(configuration, credentials)

b. Pass them via a CredentialsProvider object

If you prefer having credentials loaded from a different place instead of environment variables, you can create an instance of the CredentialsProvider class and pass it to ApiController:

from hyperscience import CredentialsProvider, Configuration, ApiController
credentials = CredentialsProvider('client_id', 'client_secret')
configuration = Configuration('<hyperscience.domain>')
api_controller = ApiController(configuration, credentials)

WARNING: Keeping credentials in code is a bad practice. CredentialsProvider is best used when loading credentials from secret stores.

5. Make a Test Call

Finally, ensure that your setup is correct by making a test call to GET submissions from your instance.

from hyperscience import ApiController, CredentialsProvider, Configuration

credentials = CredentialsProvider('<client_id>', '<client_secret>')
configuration = Configuration('<hyperscience.domain>')
api_controller = ApiController(configuration, credentials)

response = api_controller.get('/api/v5/submissions')

Using the ApiController

The ApiController allows users to interact with the Hyperscience API using easy-to-use wrapper methods. You can find Hyperscience’s API documentation here.

Supported HTTP Methods

GET, POST and PUT operations are supported by the ApiController.
Content (query params, encoded url parameters or files input) is accepted in the form of Dict[str, str] or List[Tuple[str, str]].
To support multiple parameters of the same type (e.g. 'file' for submitting multiple files), parameters should be passed as List[Tuple[str, str]].

Examples

Configuration and Setup
from hyperscience import ApiController, Configuration
from hyperscience.api import DataSupportedMediaType, PayloadSupportedMediaType

# Create an ApiController instance 
api_controller = ApiController(Configuration('cloud.hyperscience.net'))

GET Submissions

# GET request with query params provided in dictionary
query_params = {'state': 'complete'}
res = api_controller.get('/api/v5/submissions', query_params)
print(res, res.content)

# GET request with query params provided in List[Tuple] format
query_params = [('state', 'complete')]
res = api_controller.get('/api/v5/submissions', query_params)
print(res, res.content)

POST a New Submission using URL-Encoded Form.

# POST request with WwwFormUrlEncoded content-type to submit files from remote servers
# with List[Tuple] (multiple identical keys, e.g. multiple files)
data = [
    ('file', 'https://www.dropbox.com/demo-long.pdf'),
    (
        'file',
        's3://hyperscience/bucket/form1.pdf',
    ),
    ('machine_only', True),
]
res = api_controller.post('/api/v5/submissions', data, DataSupportedMediaType.FORM_URL_ENCODED)
print(res, res.content)

# POST request to submit files from remote servers with a dictionary (unique keys)
data = {
    'file': 'https://www.dropbox.com/demo-long.pdf',
    'machine_only': True,
}
res = api_controller.post('/api/v5/submissions', data, DataSupportedMediaType.FORM_URL_ENCODED)
print(res, res.content)

# POST request to submit files from remote servers with a dictionary (unique keys)
data = {
    'file': 'https://www.dropbox.com/demo-long.pdf',
    'machine_only': True,
}
res = api_controller.post('/api/v5/submissions', data, DataSupportedMediaType.FORM_URL_ENCODED)
print(res, res.content)

POST a New Submission Using MultipartFormData

# POST request with MultipartFormData content-type to upload files from local filesystem with dictionary (unique keys)
data = {'file': '/absolute/path/to/file.pdf', 'machine_only': True}
res = api_controller.post('/api/v5/submissions', data, DataSupportedMediaType.MULTIPART_FORM_DATA)
print(res, res.content)

# POST request with MultipartFormData content-type to upload files from local filesystem with List[Tuple] (multiple identical keys, e.g. multiple files)
data = [
    ('file', '/absolute/path/to/file.pdf'),
    ('file', '/absolute/path/to/file2.pdf'),
    ('machine_only', True),
]
res = api_controller.post('/api/v5/submissions', data, DataSupportedMediaType.MULTIPART_FORM_DATA)
print(res, res.content)

POST a New Submission Using JSON

POST request with ApplicationJson content-type to submit base 64 encoded files using a dictionary

json_data = {
    "metadata": {},
    "machine_only": True,
    "goal_duration_minutes": 5,
    "single_document_per_page": True,
    "restrictions": [],
    "source_routing_tags": ["tag1", "tag2"],
    "files": [
        {
            "file_content_base64": "data:image/png;base64,iVBORw0KGgoAAA…II=",
            "filename": "image.png"
        }
    ],
    "cases": [
        {
            "external_case_id": "case_1",
            "filenames": ["image.png"]
        }
    ]
}
res = api_controller.post('/api/v5/submissions', json_data, PayloadSupportedMediaType.APPLICATION_JSON)
print(res, res.content)

Logging

The library implements HyperscienceLogging class to log messages related to the library. To set a different logging level, you can use the function HyperscienceLogging.set_hyperscience_logging_level() and choose from the following list of logging levels: CRITICAL, FATAL, ERROR, WARNING, INFO, DEBUG.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hyperscience-saas-client-1.0.10.tar.gz (21.0 kB view details)

Uploaded Source

Built Distribution

hyperscience_saas_client-1.0.10-py2.py3-none-any.whl (23.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file hyperscience-saas-client-1.0.10.tar.gz.

File metadata

  • Download URL: hyperscience-saas-client-1.0.10.tar.gz
  • Upload date:
  • Size: 21.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/8.4.0 pkginfo/1.11.1 requests/2.32.3 requests-toolbelt/1.0.0 tqdm/4.66.5 CPython/3.8.13

File hashes

Hashes for hyperscience-saas-client-1.0.10.tar.gz
Algorithm Hash digest
SHA256 6011152e8d56da89f75c8752ab6be3bafd51ebdbc37f697dff2f51d16d14d274
MD5 13669995e0b7f352f543a23e9f719ed5
BLAKE2b-256 cf994ded86c5775b4b6998ff042844fd79ea41b3a32b381979ae90bc9e417734

See more details on using hashes here.

File details

Details for the file hyperscience_saas_client-1.0.10-py2.py3-none-any.whl.

File metadata

  • Download URL: hyperscience_saas_client-1.0.10-py2.py3-none-any.whl
  • Upload date:
  • Size: 23.0 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.4.1 importlib_metadata/8.4.0 pkginfo/1.11.1 requests/2.32.3 requests-toolbelt/1.0.0 tqdm/4.66.5 CPython/3.8.13

File hashes

Hashes for hyperscience_saas_client-1.0.10-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 939083c51cede56dca8617ee289aa6100790aa0cff51172b7cb69589ff326997
MD5 589c68f84d1bedc13c7751ce3119f609
BLAKE2b-256 87336438ba897cc4be4215a07c0042a96812ebab4e1ec8a02bb075706449db0e

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page