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:
- Put your client_id in an environment variable called HS_CLIENT_ID
- 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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6011152e8d56da89f75c8752ab6be3bafd51ebdbc37f697dff2f51d16d14d274 |
|
MD5 | 13669995e0b7f352f543a23e9f719ed5 |
|
BLAKE2b-256 | cf994ded86c5775b4b6998ff042844fd79ea41b3a32b381979ae90bc9e417734 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 939083c51cede56dca8617ee289aa6100790aa0cff51172b7cb69589ff326997 |
|
MD5 | 589c68f84d1bedc13c7751ce3119f609 |
|
BLAKE2b-256 | 87336438ba897cc4be4215a07c0042a96812ebab4e1ec8a02bb075706449db0e |