Package: impira
Impira Python SDK and CLIImpira enables you to get everything you need from your PDFs, scanned documents, images, and more — with the help of machine learning. This API allows you to access Impira programatically through Python and the command line.NOTE: This SDK is currently under active development and is likely to break backwards compatibility between point releases. We will update this disclaimer when this changes.Full documentationBelow is an abbreviated set of documentation to help you get started. You can visit the full documentation by visiting theImpira SDK docs.RequirementsThis SDK is tested with Python 3.7.4+ on Mac OS X and Linux systems. We have users using Windows as well; however, this scenario is not tested automatically. Please reach out if you run into any issues on Windows or another platform.InstallationYou can install the Impira Python SDK, CLI, and its dependencies directly through pip:$pipinstall'impira[cli]'To installjustthe SDK and its dependencies use:$pipinstallimpiraDevelopment modeIf you would like to install the SDK and CLI to develop locally, you can run the following:$gitclonegit@github.com:impira/impira-python.git
$cdimpira-python
$makedevelopThis will create a virtualenv locally and install the library to it in a manner that automatically updates as you change the source code.CLI overviewSeeCLI Commandsin the docs.SDK overviewThe Impira Python SDK includes utilities to upload and label files, insert and update data, and query data. The core abstraction is theImpiraobject which represents an authenticated connection to your organization. The SDK makes heavy use of thepydanticlibrary to automatically build up and validate function arugments.AuthenticatingTo connect to an org, you simply instantiate theImpiraobject with your organization's name and API token. You can find your organization's name in the URL you visit to access Impira. For example, when you login, if the URL ishttps://app.impira.com/o/acme-corp-1a23/collections, then your organization's name isacme-corp-1a23. For instructions on obtaining an API token, please visit theImpira docs. For security reasons, we highly recommend storing both the organization name and API key in configuration or environment variables, not directly in the code itself. For the purpose of these examples, we will use the environment variablesIMPIRA_ORG_NAMEandIMPIRA_API_KEY.fromimpiraimportImpiraimportosimpira_api=Impira(os.environ["IMPIRA_ORG_NAME"],os.environ["IMPIRA_API_KEY"])When you instantiate the Impira API, it will automatically issue apingrequest to validate your credentials and raise anInvalidRequestexception if it fails. You can disable this behavior by passingping=Falseto the constructor.Referencing a collectionMany function calls in the API reference acollection_idparameter. This id can be found by navigating to a collection in the application, and copying the identifier afterfc. For example, for a collection at a URL likehttps://app.impira.com/o/acme-corp-1a23/fc/07b71143a26b7163, thecollection_idis07b71143a26b7163.UploadingTo upload one or more files, you must provide at a minimum a name and path (either local or a URL) for each file. The specification is defined in theFilePathtype. You can also optionally specify acollection_idorNoneto upload the file globally (to "All files").# Upload a file on your local machineuids=impira_api.upload_files(collection_id,[{"name":"foo.pdf","path":"/Users/me/Desktop/foo.pdf"}])# Upload multiple files by specifying their URLsuids=impira_api.upload_files(collection_id,[{"name":"foo.pdf","path":"http://website.com/foo.pdf"},{"name":"bar.pdf","path":"http://website.com/bar.pdf"},])Theuidsvariable is a list with auidfor each file. A file'suidis its unique identifier throughout the system. A file that belongs to more than one collection will have the sameuidin each. You can also optionally specify your ownuidwhile uploading a file. If two files have the sameuid, the system will automatically replace the former with the latter, effectively versioning the file. For more information on uploading files, visit theUpload API docs.Polling for resultsImpira's API is asynchronous, meaning that uploading files and retrieving predictions from them occur in two separate API requests. While there are manyadvanced ways to query for data using IQL, the SDK offers a simplepoll_for_results()method that allows you to wait for results to be available for your uploads. Using theuidsreturned fromupload_files()(as demonstrated above), you can simply run something likeforrowinimpira_api.poll_for_results(collection_id,uids):print(row)to retrieve each prediction. Note thatpoll_for_results()returns a generator, so you must iterate through its output to retrieve each result.Running IQL queriesYou can run arbitrary IQL queries through the API by simply invoking thequery()method. The response is exactly the same format asthe read APIand the SDK also supports poll mode (by passing themode="poll"argument). For example,response=impira_api.query("@`file_collections::%s`[uid] highest:Uploaded limit:10"%(collection_id))last_10_uids=[row["uid"]forrowinresponse["data"]]will retrieve theuidof each of the last 10 files uploaded to the collection. For more information on how to construct IQL queries, see theIQL docs.ExamplesThe examples directory contains end-to-end working examples for how to use the SDK.upload_files.pywalks through uploading a file, either locally or through a URL, and then waiting for its results.upload_and_split_files.pywalks through uploading a file, either locally or through a URL, remove all pages after page 5 and splitting the remaining pages, and then waiting for its results.download_all_collections_query.pycreates an IQL query that queries all data across all collectionsLicenseMIT License. Copyright 2021 Impira Inc.