Arkindex API Client

Index - Module Index - Search Page

arkindex-client provides an API client and a command-line tool to interact with Arkindex servers.

Setup

Install the client using pip:

pip install arkindex-client

Command-line tool

Once installed, a arkindex script should be in your PATH. Two commands are currently available:

arkindex login
Login to an Arkindex server with an email and a password, then save API tokens to a configuration file.
arkindex upload
Upload and import files into an Arkindex server.

Main options

These options are available for all arkindex subcommands and should be applied before the subcommand name, like so:

arkindex --no-verify-ssl login
--profile [name]
Name of the configuration profile to use. Defaults to default.
--verify-ssl / --no-verify-ssl
Enable or disable SSL certificate checks (enabled by default). Useful when the Arkindex server uses self-signed certificates.

Login

To perform authenticated requests against the API, the client must obtain a user’s API token. The arkindex login commands allows to log in to an Arkindex server, fetch the API token and save it to the configuration file.

--host [name]
Host name of the Arkindex server. Defaults to arkindex.teklia.com.
--email
Email to use for logging in. If this setting is omitted, a prompt will be shown asking for the email.

The script will ask for your password, then login and save tokens.

Upload

The upload subcommand allows to upload files and optionally start import processes in batch:

arkindex upload --mode images Himanis ./himanis/*.jpg

This example will try to find a corpus that contains Himanis in its name, then upload all .jpg files from the himanis folder and start an import process for each file automatically.

Options

arkindex upload
    [--mode pdf|images]
    [--start/--no-start]
    [--volume <name or ID>]
    [--verbose]
    [corpus]
    [files]
corpus
UUID or part of the name of a corpus to upload files to. If a name is specified, corpus name matching is done in a case-insensitive manner. If there are multiple matching corpora for a name, the matching corpora names are printed and the script exits.
files
Paths of all files to upload/import. Compatible shells may allow the use of wildcards (* or **) to specify multiple paths at once.
--start / --no-start
Start (or do not start) an import process for each uploaded file. Enabled by default. With the --volume option, a single import process will be run with all files. Without this option, files are imported separately.
--mode pdf / --mode images
Set the import process mode. Defaults to pdf. Is ignored if --no-start is specified.
--volume <name or ID>
UUID or part of the name of a volume to import to. When left unspecified, the Arkindex server will automatically create a volume for each import. Is ignored if --no-start is specified.
--verbose
Print all import UUIDs when the upload is complete.

Package reference

API client

class arkindex.client.ArkindexAPI(token=None, host='arkindex.teklia.com', verify_ssl=True)[source]
auth = None

An instance of ArkindexTokenAuth if there is a token available, or None.

bad_request_handler(json)[source]

Custom handler for HTTP 400 Bad Request when the request has a JSON body.

Parameters:json – Parsed JSON data returned by the server.
Raises:ArkindexAPIError – Always raises, with a potentially easier to read error message.
base_url = None

The API endpoints base URL to which endpoint names are appended.

create_bulk_transcriptions(**kwargs)[source]

Create multiple transcriptions at once.

Parameters:**kwargs – Transcriptions data to send as a JSON body.
Returns:Parsed JSON data for the resulting created transcriptions.
Raises:ArkindexAPIError – If the client is missing a valid API token.
create_transcription(**kwargs)[source]

Create a single transcription.

Parameters:**kwargs – Transcription data to send as a JSON body.
Returns:Parsed JSON data for the resulting created transcription.
Raises:ArkindexAPIError – If the client is missing a valid API token.
get(endpoint, params={}, requires_auth=False)[source]

Perform a GET request on an Arkindex API endpoint.

Parameters:
  • endpoint (str) – Endpoint to perform requests on, without /api/v1/.
  • params (dict) – GET parameters to send in the URL.
  • requires_auth (bool) – Set to True to raise ArkindexAPIError if the client does not have an available API token.
Returns:

Parsed JSON data returned by the server.

Return type:

Any type returned by json.loads.

Raises:
  • ArkindexAPIError – If requires_auth is set to True and the client is missing an API token.
  • HTTPError – If the request did not give a success HTTP status code (4xx or 5xx)
get_corpora()[source]

List all available corpora with the available access rights.

Returns:List of corpora.
Return type:list(dict)
get_elements(type='volume', corpus_id=None)[source]

List all elements in a single corpus or all corpora by element type.

Parameters:
  • str (type) – The element type (volume, page, etc) to list.
  • corpus_id (str or None) – UUID of a corpus to filter on. If set to None, will list elements of all corpora.
Returns:

Generator yielding a dict for each element.

Return type:

ResponsePaginator

get_pages(id)[source]

List all pages marked as children of a single element.

Parameters:str (id) – UUID of the element to find child pages on.
Returns:Generator yield a dict for each page.
Return type:ResponsePaginator

List parent and children elements of a single element by ID, filtered by type.

Parameters:
  • str (type) – UUID of the element to list related elements from.
  • str – Element type (volume, page) to list.
Returns:

Generator yielding a dict for each element.

Return type:

ResponsePaginator

import_from_files(mode, file_ids, volume_id=None, volume_name=None)[source]

Start an import process with some files.

Parameters:
  • str (mode) – The import mode (pdf or images). Defaults to images.
  • file_ids (list(str)) – List of uploaded file UUIDs.
  • volume_id (str or None) – UUID of an existing volume to import into. When None, a new volume will be automatically created. If volume_name is not set, the volume’s name will be automatically generated.
  • volume_name (str or None) – Name of a new volume to create then import into. Is ignored if the volume_id parameter is set.
Returns:

Parsed JSON data for the started process.

Return type:

dict

Raises:

ArkindexAPIError – If the client is missing a valid API token.

login(email, password)[source]

Login on an Arkindex server with an email and a password. This does not automatically save the API token.

Parameters:
  • str (password) – The email address to login with.
  • str – The password to login with.
Returns:

User information, including a auth_token key with the API token to use.

Return type:

dict

Raises:
  • ArkindexAPIError – The response has a HTTP 400 status code and a JSON error body.
  • HTTPError – The response has a HTTP 4xx or 5xx status code.
post(endpoint, params=None, json=None, files=None, requires_auth=False)[source]

Perform a POST request on an Arkindex API endpoint.

Parameters:
  • endpoint (str) – Endpoint to perform requests on, without /api/v1/.
  • params (dict or None) – GET parameters to send in the URL.
  • json – Optional JSON body to send with the request.
  • files (dict(str, object) or None) – File-like objects to send with the request.
  • requires_auth (bool) – Set to True to raise ArkindexAPIError if the client does not have an available API token.
Returns:

Parsed JSON data returned by the server.

Return type:

Any type returned by json.loads.

Raises:
  • ArkindexAPIError – If requires_auth is set to True and the client is missing an API token or if the response has a HTTP 400 code and has an error JSON body.
  • HTTPError – If the request did not give a success HTTP status code (4xx or 5xx)
upload_file(corpus_id, file_path)[source]

Upload a file to a corpus.

Parameters:
  • str (file_path) – UUID of a corpus with write access to upload files on.
  • str – Path of a file to upload.
Returns:

Parsed JSON data for the saved file.

Raises:

ArkindexAPIError – If the client is missing a valid API token.

verify_ssl = None

str or bool to set requests’ HTTPS certificate checking.

whoami()[source]

Fetch user information from the server.

Returns:

User information, including a auth_token key with the API token to use.

Return type:

dict

Raises:
  • ArkindexAPIError – The API client does not have a valid API token.
  • HTTPError – The response has a HTTP 4xx or 5xx status code.

Exceptions

exception arkindex.client.ArkindexAPIError[source]

Describes any handled error from the Arkindex API.

Helper classes

class arkindex.client.ResponsePaginator(client, *request_args, **request_kwargs)[source]

A lazy generator to handle paginated Arkindex API endpoints. Does not perform any requests to the API until it is required.

client = None

The Arkindex API client used to perform requests on each page.

current_page = None

The current page number. 0 if no pages have been requested yet.

data = None

Stored data from the last performed request.

request_args = None

Arguments to send to ArkindexAPI.get() with each request.

request_kwargs = None

Keyword arguments to send to ArkindexAPI.get() with each request. ['params']['page'] is overriden to set the page number.

results = None

Stored results from the last performed request.

class arkindex.conf.LocalConf(path=None)[source]

Manages local configuration for current user. Allows multiple configuration profiles.

config = None

Cached configuration data from the INI file.

path = None

Configuration file path

profiles = None

Available configuration profiles.

read()[source]

Read configuration data from the INI file.

Returns:A loaded ConfigParser.
Return type:configparser.ConfigParser
save_profile(profile_name, **kwargs)[source]

Save profile configuration to the in-memory configuration. Does not write to the INI file.

Parameters:
  • str (profile_name) – Name of the profile to store.
  • **kwargs – Configuration data for the profile.
write()[source]

Write configuration data to the INI file.