API Reference#

The package is mainly composed of a low level API Client parble.ParbleAPIClient and a higher level SDK class parble.ParbleSDK exposing useful features on top on the API CLient.

It is recommended to use the SDK as it provides an abstraction over the API; however it is possible to use the API Client directly in rare cases requiring finer control over the API usage.

CLI#

parble#

Parble CLI tool

The CLI relies on the following 2 environment variables:
- PARBLE_URL: URL of the tenant to use
- PARBLE_API_KEY: API-Key to use

They must be exported and available in the shell where the command is invoked.

parble [OPTIONS] COMMAND [ARGS]...

Options

--version#: Show the version and exit.

-v, --verbose#: Increase the verbosity. Can be stacked (-vvv)

file#

Group all file-related operations

parble file [OPTIONS] COMMAND [ARGS]...

get#

Get the processing result of the given FILE_ID

This command get a previously processed file and returns it’s attributes.

parble file get [OPTIONS] FILE_ID

Options

-f, --format <output_format>#

Output format

Options:: pdf | json

-o, --output <output>#: Save the output to this file

Arguments

FILE_ID#: Required argument

upload#

Upload and process FILE.

This command upload the file FILE and waits for its processing to complete then returns it attributes.

If waiting for the processing timed-out on the server side (300s) it will return a redirection to the file and the command will return the (incomplete) attributes of the file.

parble file upload [OPTIONS] FILE

Options

-f, --format <output_format>#

Output format

Options:: pdf | json

-o, --output <output>#: Save the output to this file

-i, --inbox <inbox>#: Optional inbox id to upload to

Arguments

FILE#: Required argument

SDK#

class parble.ParbleSDK#

High Level SDK Class

This class exposes primitives built on top of the ParbleAPIClient

class Files#

Files helper to upload, get processed elements, etc

__init__(sdk)#

Parameters:: sdk (ParbleSDK) –

create(**attrs)#

Create a File object from a dict of attributes

On top of the attributes from the API, Files require to be bound to an active SDK instance, which this helper function makes sure.

Parameters:: attrs (Any) – Attributes payload from the API Call
Returns:: parsed File object
Return type:: File

get(file_id)#

Retrieve the given File payload

Parameters:: file_id (str) – File ID to get
Returns:: Matching File
Return type:: File

get_pdf(file_id)#

Retrieve the given File PDF content

Parameters:: file_id (str) – File ID to get
Returns:: File-like PDF content
Return type:: BinaryIO

post(path, inbox_id=None)#

Upload and process the file at the given local path

Parameters:

path (str | Path) – local path of the file to upload
inbox_id (ConstrainedStrValue | None) – optional uuid of the inbox to upload to

Returns:

Processed File response

Return type:

File

post_file(file, file_name, file_type='application/octet-stream', inbox_id=None)#

Upload and process the given file-like

This function requires you to specify the filename which will be sent. You can also specify the file type as a hint to help inferring the proper payload content type; else this will be treated as an octet stream.

Parameters:

file (BinaryIO) – File-like object
file_name (str) – Filename to be used
inbox_id (ConstrainedStrValue | None) – optional uuid of the inbox to upload to
file_type – Content Type of the file

Returns:

Processed File data

Return type:

File

__init__(url=None, api_key=None)#

Client#

class parble.ParbleAPIClient#

Low level REST API Client This thin layer exposes the API resources

__init__(url=None, api_key=None)#

delete(url, **kwargs)#

Send a DELETE request

Parameters:

url – absolute or relative resource uri
**kwargs –

Returns:

API Response

get(url, **kwargs)#

Send a GET request

Parameters:

url – absolute or relative resource uri
**kwargs –

Returns:

API Response

patch(url, **kwargs)#

Send a PATCH request

Parameters:

url – absolute or relative resource uri
**kwargs –

Returns:

API Response

post(url, **kwargs)#

Send a POST request

Parameters:

url – absolute or relative resource uri
**kwargs –

Returns:

API Response

Models#

class parble.models.Classification#: Classification information about a single document

class parble.models.Document#: A single classified and predicted document

class parble.models.Field#: A single field that’s contained inside a document

class parble.models.File#

This model represents a File datastructure from Parble API.

A File contains a list of identified and classified documents - each one containing predictions.

__init__(sdk, **data)#

Create a new model by parsing and validating input data from keyword arguments.

Raises ValidationError if the input data cannot be parsed to form a valid model.

Parameters:

sdk (ParbleSDK) –
data (Any) –

static from_json(json_data)#

decoding a json string to a File object

Parameters:: json_data (str) –

property name: str#: Return the filename of this file

property pdf: BinaryIO#

Fetch and return the PDF representation of the processed File.

The content is fetched from the API and cached. Explicitly calling del on this property will clear the cache

to_json()#: Convert a File object to a json string

class parble.models.Timings#: Timings information for a file

Session#

class parble.session.BaseSession#

Base requests session with shared behavior for the API Calls.

Provides base url support, custom headers and common error handling.

__init__(settings)#

Parameters:: settings (Settings) –

build_url(url)#

Join the base URL with the provided URI

Parameters:

url (str) – resource part to add to the base url
**kwargs – timeout: overwrite the default timeout

Returns:

Full concatenated URL

Return type:

str

initialize()#: Initialize the session by setting the headers to use

prepare_request(request)#

Constructs a PreparedRequest for transmission and returns it. The PreparedRequest has settings merged from the Request instance and those of the Session.

Parameters:: request (Request) – Request instance to prepare with this session’s settings.
Return type:: requests.PreparedRequest

request(method, url, *args, **kwargs)#

Constructs a Request, prepares it and sends it. Returns Response object.

Parameters:

method (str) – method for the new Request object.
url (str) – URL for the new Request object.
params – (optional) Dictionary or bytes to be sent in the query string for the Request.
data – (optional) Dictionary, list of tuples, bytes, or file-like object to send in the body of the Request.
json – (optional) json to send in the body of the Request.
headers – (optional) Dictionary of HTTP Headers to send with the Request.
cookies – (optional) Dict or CookieJar object to send with the Request.
files – (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload.
auth – (optional) Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth.
timeout (float or tuple) – (optional) How long to wait for the server to send data before giving up, as a float, or a (connect timeout, read timeout) tuple.
allow_redirects (bool) – (optional) Set to True by default.
proxies – (optional) Dictionary mapping protocol or protocol and hostname to the URL of the proxy.
stream – (optional) whether to immediately download the response content. Defaults to False.
verify – (optional) Either a boolean, in which case it controls whether we verify the server’s TLS certificate, or a string, in which case it must be a path to a CA bundle to use. Defaults to True. When set to False, requests will accept any TLS certificate presented by the server, and will ignore hostname mismatches and/or expired certificates, which will make your application vulnerable to man-in-the-middle (MitM) attacks. Setting verify to False may be useful during local development or testing.
cert – (optional) if String, path to ssl client cert file (.pem). If Tuple, (‘cert’, ‘key’) pair.

Return type:

requests.Response