pylleida 0.2.6

A HTTP Python client to use the Lleida.net API

pylleida

A HTTP Python client to use the Lleida.net API. This API consists of several modules, each one related to a different set of services. More information can be found at the official API listing website.

• Free software: MIT license

• Documentation: https://pylleida.readthedocs.io.

Disclosure

This Python library has been developed by the reclamador.es team without any previous collaboration agreement with Lleida.net. The code in this repository will be updated according to the updates on the Lleida.net APIs, initially based on the internal requirements of the reclamador.es team.

Features

• MailCert API: lets the client check the status of the PDF email certificate documents emitted by the Lleida.net MailCert service. Currently implemented methods:

  • get_default_settings: retrieves a list of the MailCert service’s configuration parameters associated to the account used by the PyLleida client.

  • list_pdf: fetches a listing of PDF documents (email certificates), indicating their metadat, status and other identification data.

  • download_pdf: fetches the binary data of a given PDF document (email certificate) if possible, otherwise returns an error response.

Usage

Start by importing the PyLleida client and creating a new instance with your Lleida.net credentials:

from pylleida import PyLleida

client = PyLleida('username', 'password')

In order to obtain a list of the email certificates that contain the word John Doe in their subject, do as follows:

# Request data
res = client.mail_cert.list_pdf(subjrw='John Doe')

# Access response contents
res.status  # u'100'
results = res.pdf_list  # ResponseItem object containing all results

results.rows_found  # u'1'
results.pdf_row  # List of ResponseItem objects, each containing data about an email certificate

certificate = results.pdf_row[0]
certificate.mail_id  # u'12345': the identifier of the email
certificate.file_status  # u'5': the status of the signature process associated to the document. u'5' indicates 'Finished PDF'.
certificate.mail_date  # u'20171108124802'
certificate.mail_to  # u'[e-mail]'
certificate.mail_from  # u'[e-mail]'
certificate.file_id  # u'98765': identifier of the PDF document associated to the email certificate object.
certificate.file_status_desc  # u'Finished pdf': verbose description of the file status.
certificate.mail_subj  # u'=?utf-8?Q?John=20aDoe?='
certificate.file_type  # u'S': this value indicates the file is of type 'Sent (certificate email, normal variant, sent as certificate email)

There exist more fields accesible on the certificate variable. For a more complete description on each field, refer to the official Lleida.net API documentation.

To download the PDF contents associated to an email certificate, first look up its file_id value, then do something like:

file_id = u'98765'
res = client.mail_cert.download_pdf(file_id)
if res.has_file:  # Use this flag to check whether the file was successfully downloaded
    cert_file = open('/path/to/cert/file', 'wb')
    cert_file.write(res.content)
    cert_file.flush()
    cert_file.close()
else:
    res_status = res.status  # Only available in case of error
    res_msg = res.msg  # Only available in case of error
    raise Exception("Requested file has no PDF contents yet: status %s, msg: %s" % (res_status, res_msg))

When requesting an email certificate by cc’ing Lleida.net in an email message, it can take some time for the Lleida.net servers to generate the PDF file of the email certificate. It is encouraged to perform the PDF document download at a later point in time.

MailCert API

• get_default_settings

Fetches the default settings associated to the username/password credentials supplied to the PyLleida constructor.

• list_pdf

Email certificates generated by Lleida.net can be searched for using this method. Several filtering parameters can be provided in order to narrow the search:

• mail_from: the email address of the certificate’s sender. Example: [e-mail]

• mail_to: the email address of the certificate’s destination. Example: [e-mail]

• date_min: list email certificates generated after this datetime. Example: 201711200800 (from 20th November 2017, 08:00)

• date_max: fetch email certificates generated before this datetime. Example: 201801011000 (up to 1st January 2018, 11:00)

• file_id_min: list email certificates whose file identifiers are greater than this value. Example: 123456

• file_id_max: list email certificates whose file identifiers are lower than this value. Example: 98765

• file_type: limit the search results to a certain kind of certificates. Valid values are: ``

• subjrw: limit the search results based on a substring that should appear on the subject of the generated email certificates. Example: Information for user john.doe.

• mail_message_id: get results belonging to a certain email certificate identifier. Example: ``

• only_last_file_id: returns a single email certificate, the latest generated one. Set to True if desired.

Note: Lleida.net does not paginate the search results. This means that you must narrow your search criteria as much as possible to avoid ending with humongous objects in memory. That is, if your search yields one million results, your code will have a variable with one million items, each referencing a result.

• download_pdf

Given an already generated email certificate file identifier, returns the binary contents of such file in PDF format.

Lleida.net does not return a normalized response for both success and failure. Due to this fact, the PyLleida client returns an object with a has_file boolean property, indicating whether the request returned the requested file contents or not. By looking at this variable you may know about the outcome of the request.

Credits

The reclamador team.

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

History

0.1.0 (2017-11-07)

• First release on PyPI.