A HTTP Python client to use the Lleida.net API
Project description
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'john@doe.com' certificate.mail_from # u'info@evilcorp.com' 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: info@evilcorp.com
mail_to: the email address of the certificate’s destination. Example: john@doe.com
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.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for pylleida-0.2.6-py2.py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | e0310a41c7500ecf0a2a3add4ec804ecc038069eb38a7214bccc4583e915f7f3 |
|
MD5 | f2255c31f0d49918a0fa52af257cfb82 |
|
BLAKE2b-256 | 2c781375337091c33e34bbf90e97713ac534582f34fe25bf5d2fb4f1521681a5 |