DocumentsApi

The DocumentsApi allows you to insert document files (PDF, docx, text files,…) inside an IL2 chain. To get an instance of the JsonApi, you can use the following example:

from pyil2 import IL2Client

client = IL2Client(
    host='https://il2.node:32032/',
    cert_filepath='rest.api.pfx',
    cert_password='Str0ngPassword'
)
api = client.api('documents')

The DocumentsApi is based on transactions to upload the files. This way, it is possible to upload multiple files to a single record. In summary, the basic steps to upload document files are as follows:

  • Begin an upload transaction;

  • Upload file;

    • Repeat for multiple files;

  • Commit the upload transaction.

An example on how to upload document files to an IL2 chain:

from pyil2.models.documents import BeginDocumentTransactionModel

new_transaction = BeginDocumentTransactionModel(
    chain='UHtr...REDACTED...vXRY',
    comment='Additional comment to describe the files inside this record.',
    encryption='PBKDF2-SHA512-AES256-MID',
    password='1234567890123456'
)
transaction = api.begin_document_transaction(new_transaction)

transaction = api.upload_document(
    transaction_id=transaction.transaction_id,
    filename='file1.txt',
    content_type='text/plain',
    file_bytes=b'Example 1',
    comment='Uploading a file using raw bytes as payload.'
)

transaction = api.upload_document_file(
    transaction_id=transaction.transaction_id,
    filepath='/path/to/file2.txt',
    comment='Uploading a file passing the file path.'
)

locator = api.commit_document_transaction(transaction.transaction_id)

After commiting the upload transaction, you will receive a locator to access the files inside the record.

Note

The locator will be available only in the response to the transaction commit. It will not be possible to recover the locator afterward, store it in a safe location.

With the locator, it is possible to get the details of the files in the record, or download the files.

metadata = api.get_document_metadata(locator)

# Download a single file
# This method will return the path to the downloaded file
document_path = api.download_single_document_at(
    locator=locator,
    index=0,
    dst_path='/path/to/download/folder'
)

# Download all files as a zip file
# This method will return the path to the downloaded file
document_path = api.download_documents_as_zip(
    locator=locator,
    dst_path='/path/to/download/folder'
)

The list of methods in the DOcumentsApi are described as follows:

class pyil2.api.DocumentsApi(client: IL2Client)

Bases: BaseApi

API class for the Multi-Documents requests.

Parameters:

client (pyil2.IL2Client) – IL2Client to be used to send requests.

base_url

Base path of the requests.

Type:

str

begin_document_transaction(new_transaction: BeginDocumentTransactionModel) → DocumentTransactionModel | ErrorDetailsModel

Begin a document upload transaction.

The transaction will rollback on timeout or errors.

Parameters:

new_transaction (pyil2.models.documents.BeginDocumentTransactionModel) – Begin transaction details.

Returns:

Document upload transaction status.

Return type:

pyil2.models.documents.DocumentTransactionModel

commit_document_transaction(transaction_id: str) → str | ErrorDetailsModel

Commits a document upload transaction.

Parameters:

transaction_id (str) – Document upload transaction ID.

Returns:

Document locator.

Return type:

str

property documents_configuration: DocumentUploadConfigurationModel | ErrorDetailsModel

Documents upload configuration.

Type:

pyil2.models.documents.DocumentUploadConfigurationModel

download_documents_as_zip(locator: str, dst_path: str = './', omit_from_parent: bool = False, omit_to_children: bool = False) → str | ErrorDetailsModel

Download documents in a compressed file to a folder (default: current folder).

Parameters:

  • locator (str) – A Documents Storage Locator.

  • dst_path (str) – Download the file to this folder.

  • omit_from_parent (bool) – If True, does not include the .from-parent control file in the zip.

  • omit_to_children (bool) – If True, does not include the .to-children control file in the zip.

Returns:

Downloaded file full path.

Return type:

str

download_documents_as_zip_as_response(locator: str, omit_from_parent: bool = False, omit_to_children: bool = False) → Response | ErrorDetailsModel

Get the request response to download documents in a compressed file.

Note: For advance use only.

Parameters:

  • locator (str) – A Documents Storage Locator.

  • omit_from_parent (bool) – If True, does not include the .from-parent control file in the zip.

  • omit_to_children (bool) – If True, does not include the .to-children control file in the zip.

Returns:

Request response.

Return type:

requests.Response

download_single_document_at(locator: str, index: int, dst_path: str = './') → str | ErrorDetailsModel

Download a single document by position from the set of documents to a folder (default: current folder).

Parameters:

  • locator (str) – A Documents Storage Locator.

  • index (int) – Index of the file.

  • dst_path (str) – Download the file to this folder.

Returns:

Downloaded file full path.

Return type:

str

download_single_document_at_as_response(locator: str, index: int) → Response | ErrorDetailsModel

Get the request response to download a single document by position from the set of documents.

Note: For advance use only.

Parameters:

  • locator (str) – A Documents Storage Locator.

  • index (int) – Index of the file.

Returns:

Request response.

Return type:

requests.Response

get_document_metadata(locator: str) → DocumentMetadataModel | ErrorDetailsModel

Get the documents metadata by the locator.

Parameters:

locator (str) – Document locator.

Returns:

Documents metadata.

Return type:

pyil2.models.documents.DocumentMetadataModel

get_document_transaction_status(transaction_id: str) → DocumentTransactionModel | ErrorDetailsModel

Get a document upload transaction status.

Parameters:

transaction_id (str) – Document upload transaction ID.

Returns:

Document upload transaction status.

Return type:

pyil2.models.documents.DocumentTransactionModel

upload_document(transaction_id: str, filename: str, content_type: str, file_bytes: bytes, comment: str = None, relative_path: str = '/') → DocumentTransactionModel | ErrorDetailsModel

Add a file to a document upload transaction using bytes.

Parameters:

  • transaction_id (str) – Document upload transaction ID.

  • filename (str) – File name.

  • content_type (str) – File mime-type

  • file_bytes (bytes) – File bytes.

  • comment (str) – Additional comment.

  • relative_path (str) – Relative path of the file inside the record.

Returns:

Document upload transaction status.

Return type:

pyil2.models.documents.DocumentTransactionModel

upload_document_file(transaction_id: str, filepath: str, comment: str = None, relative_path: str = '/', filename: str = None, content_type: str = None) → DocumentTransactionModel | ErrorDetailsModel

Add a file to a document upload transaction using file path. This method will try to get the filename and the MIME-type from the filepath. If needed, you can force the filename and/or the content-type.

Parameters:

  • transaction_id (str) – Document upload transaction ID.

  • filepath (str) – File path.

  • comment (str) – Additional comment.

  • relative_path (str) – Relative path of the file inside the record.

  • filename (str) – File name. If None, it will try to use the filename in the filepath.

  • content_type (str) – File mime-type. If None, it will try to guess the mime-type based on the file extension.

Returns:

Document upload transaction status.

Return type:

pyil2.models.documents.DocumentTransactionModel