libtlp module
The transLectures-UPV Platform (TLP) Python2 Library
Software Requirements:
This module mainly implements the TLPSpeechClient, TLPTextClient and TLPWebClient classes that provides several
methods to interact with the /speech, /text and /web APIs of the transLectures-UPV Platform.
Below are shown some examples on interacting with the /speech
API. Using this library to query /text and /web API interfaces is pretty similar.
First, we have to import the libtlp library and create a
TLPSpeechClient class instance, using the appropriate argument values. E.g.:
#!python
>>> import libtlp
>>> tlp = libtlp.TLPSpeechClient("http://ttp.mllp.upv.es/api/v3", "http://ttp.mllp.upv.es/player", "tluser", "akjsfd982323098qwjs209823id09321io3290d")
To get the list of subtitle languages available for a particular Media ID:
#!python
>>> tlp.api_langs("media-id-1")
>>> print tlp.get_printable_response_data()
To download a subtitles file, for instance, English subtitles in SRT format:
#!python
>>> tlp.api_get("media-id-1", "en", form="srt")
>>> tlp.save_response_data("/path/to/my/media_subs.en.srt")
To Generate and upload a Media Package File to the TLP Server is also quite straightforward:
#!python
>>> # Initialise Manifest, define "New Media" Operation and Media ID:
>>> tlp.manifest_init("media-id-2")
>>> # Add media language and title:
>>> tlp.manifest_set_metadata(language="en", title="Testing libtlp")
>>> # Add main media file:
>>> tlp.manifest_set_main_media_file("/path/to/my/media_file.mp4")
>>> # Enable Ingest Service's Test Mode, since we are doing a test:
>>> tlp.manifest_set_options(test_mode=True)
>>> # Generate Media Package File and upload it via the /ingest/new interface:
>>> tlp.api_ingest_new()
>>> # Why to print the response? I just want the upload ID!
>>> upload_id = tlp.ret_data['id']
To track the progress of our first upload:
#!python
>>> tlp.api_status(upload_id)
>>> print tlp.get_printable_response_data()
Anyway, you can build the most complex Media Package in the world, but only if you want!
#!python
>>> tlp.manifest_init("media-id-3")
>>> tlp.manifest_set_metadata(language="en", title="Really testing libtlp")
>>> tlp.manifest_set_main_media_file("/path/to/my/media_file.mp4")
>>> # Add info about media speaker:
>>> tlp.manifest_add_speaker("speaker-id_1", "John Snow", email="jsnow21@got.com")
>>> # Add a related text file to improve the media transcription
>>> tlp.manifest_add_attachment("/path/to/my/doc_file.pdf", libtlp.TLPClient.FTYPE_CODE_DOCUMENT)
>>> # Request Spanish subtitles (English are generated by default):
>>> tlp.manifest_add_subtitles_request("es")
>>> # Request also a text-to-speech synthesized Spanish audiotrack:
>>> tlp.manifest_add_audiotrack_request("es")
>>> # etc, etc, etc.
>>> # BUT FINALLY...
>>> tlp.api_ingest_new()
>>> # Mere curiosity... print me the generated Manifest JSON object!
>>> print tlp.get_printable_manifest()
For further information you might check the full documentation of the transLectures-UPV Platform.
# -*- coding: utf-8 -*-
# Copyright 2015, 2016 transLectures-UPV Team
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
"""
## The *transLectures-UPV Platform* (TLP) Python2 Library
Software Requirements:
* [python-requests](http://docs.python-requests.org)
This module mainly implements the `libtlp.TLPSpeechClient`, `libtlp.TLPTextClient` and `libtlp.TLPWebClient` classes that provides several
methods to interact with the `/speech`, `/text` and `/web` APIs of the *transLectures-UPV Platform*.
Below are shown some examples on interacting with the `/speech`
API. Using this library to query `/text` and `/web` API interfaces is pretty similar.
First, we have to import the `libtlp` library and create a
`libtlp.TLPSpeechClient` class instance, using the appropriate argument values. E.g.:
#!python
>>> import libtlp
>>> tlp = libtlp.TLPSpeechClient("http://ttp.mllp.upv.es/api/v3", "http://ttp.mllp.upv.es/player", "tluser", "akjsfd982323098qwjs209823id09321io3290d")
To **get the list of subtitle languages available** for a particular Media ID:
#!python
>>> tlp.api_langs("media-id-1")
>>> print tlp.get_printable_response_data()
To **download a subtitles file**, for instance, English subtitles in SRT format:
#!python
>>> tlp.api_get("media-id-1", "en", form="srt")
>>> tlp.save_response_data("/path/to/my/media_subs.en.srt")
To **Generate and upload a Media Package File** to the TLP Server is also quite straightforward:
#!python
>>> # Initialise Manifest, define "New Media" Operation and Media ID:
>>> tlp.manifest_init("media-id-2")
>>> # Add media language and title:
>>> tlp.manifest_set_metadata(language="en", title="Testing libtlp")
>>> # Add main media file:
>>> tlp.manifest_set_main_media_file("/path/to/my/media_file.mp4")
>>> # Enable Ingest Service's Test Mode, since we are doing a test:
>>> tlp.manifest_set_options(test_mode=True)
>>> # Generate Media Package File and upload it via the /ingest/new interface:
>>> tlp.api_ingest_new()
>>> # Why to print the response? I just want the upload ID!
>>> upload_id = tlp.ret_data['id']
To **track the progress** of our first upload:
#!python
>>> tlp.api_status(upload_id)
>>> print tlp.get_printable_response_data()
Anyway, you can build the most **complex Media Package** in the world, but only if you want!
#!python
>>> tlp.manifest_init("media-id-3")
>>> tlp.manifest_set_metadata(language="en", title="Really testing libtlp")
>>> tlp.manifest_set_main_media_file("/path/to/my/media_file.mp4")
>>> # Add info about media speaker:
>>> tlp.manifest_add_speaker("speaker-id_1", "John Snow", email="jsnow21@got.com")
>>> # Add a related text file to improve the media transcription
>>> tlp.manifest_add_attachment("/path/to/my/doc_file.pdf", libtlp.TLPClient.FTYPE_CODE_DOCUMENT)
>>> # Request Spanish subtitles (English are generated by default):
>>> tlp.manifest_add_subtitles_request("es")
>>> # Request also a text-to-speech synthesized Spanish audiotrack:
>>> tlp.manifest_add_audiotrack_request("es")
>>> # etc, etc, etc.
>>> # BUT FINALLY...
>>> tlp.api_ingest_new()
>>> # Mere curiosity... print me the generated Manifest JSON object!
>>> print tlp.get_printable_manifest()
For **further information** you might check the [full documentation of the transLectures-UPV Platform](https://ttp.mllp.upv.es/doc).
"""
import cStringIO
from datetime import datetime, timedelta
import hashlib
import json
import base64
import os.path
import tempfile
import zipfile
import shutil
import urllib2
import requests
class TLPClient():
"""
TLPClient class.
"""
TLP_VERSION = "3.X"
API_SPEECH = "speech"
API_TEXT = "text"
API_WEB = "web"
def __init__(self, api_base_url, editor_base_url, api_user, api_secret_key, api_type):
"""
Creates a TLPClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._last_api_call = None
self._tmp_dir = None
self._session = None
self._response = None
self._http_auth_enabled = False
self._http_user = None
self._http_pass = None
self._api_base_url = api_base_url
self._api_type = api_type
self._editor_base_url = editor_base_url
self._api_user = api_user
self._api_secret_key = api_secret_key
self.use_get_method = False
"""Use HTTP GET Method instead of POST."""
self.use_data_parameter = True
"""Use a single "data" parameter on HTTP GET calls instead multiple GET parameters."""
self.parameters = None
"""Dictionary with API query parameters."""
self.ret_data = None
"""Data returned by the last performed API call. If the response was a JSON object, *ret_data* becomes a a parsed JSON object (dictionary or list, depending on the JSON)."""
self.ret_content_type = None
"""Mime-type of the data returned by the last performed API call."""
self.debug = False
"""Enable/Disable generation of debug information."""
self.debug_info = None
"""Debug information of the last performed API call / Generation of Player URL."""
def _reset_http_session(self):
"""Resets requests.Session class instance."""
self._session = requests.Session()
if self._http_auth_enabled:
self._session.auth = (self._http_user, self._http_pass)
def _reset(self):
"""Reset all class methods to perform a new API call."""
self._reset_http_session()
self._response = None
self.parameters = {}
self.parameters["client"] = "libtlp-%s" % (self.TLP_VERSION)
self.ret_data = None
self.ret_content_type = None
self.debug_info = None
def _set_auth_parameters_secret_key(self):
"""Set API authentication parameters using the secret key."""
self.parameters['user'] = self._api_user
self.parameters['auth_token'] = self._api_secret_key
def _set_auth_parameters_request_key_api(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for an API call."""
self.parameters['user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['auth_token'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def _set_auth_parameters_request_key_editor(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for generating am Editor URL."""
self.parameters['api_user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['request_key'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def _gen_expire_parameter(self, lifetime):
"""Returns a valid value of the "expire" API authentication parameter."""
return int((datetime.utcnow() + timedelta(minutes=lifetime) - datetime(1970,01,01)).total_seconds())
def _generate_debug_info_api(self, url):
""" Generates debug information about the last API call."""
o = cStringIO.StringIO()
o.write("\n")
o.write("- Input data (JSON-formatted):\n")
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
o.write("\n")
if self.use_get_method:
if self.use_data_parameter:
o.write("- URL (using GET request with a single 'data' base64-encoded JSON parameter):\n")
o.write("%s?data=%s\n" % (url, base64.b64encode(json.dumps(self.parameters, encoding="UTF-8"))))
o.write("\n")
else:
o.write("- URL (using GET request with multiple parameters):\n")
params = "&".join([ "%s=%s"%(k, str(self.parameters[k])) for k in self.parameters ])
o.write("%s?%s\n" % (url, params))
o.write("\n")
else:
o.write("- URL + POST data:\n")
o.write("%s\n" % url)
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
if self._last_api_call == "ingest":
if self.manifest != None:
o.write("\n- Manifest.JSON file:\n")
o.write("%s\n" % self.get_printable_manifest())
o.write("\n")
if self._tmp_dir != None:
o.write("- Temp dir: %s\n" % self._tmp_dir)
o.write("\n- TLP Server response:\n")
self.debug_info = o.getvalue()
def _generate_debug_info_editor(self):
""" Generates debug information about the last generated Player URL."""
o = cStringIO.StringIO()
o.write("\n")
o.write("- Input data (JSON-formatted):\n")
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
o.write("\n")
o.write("- Input data (Base 64):\n")
o.write("%s\n" % base64.b64encode(json.dumps(self.parameters, encoding="UTF-8")))
o.write("\n")
self.debug_info = o.getvalue()
def _parse_response(self):
if self._response.status_code == 200:
self.ret_content_type = self._response.headers['content-type']
if self.ret_content_type.find("application/json") >= 0:
self.ret_data = json.loads(self._response.content)
else:
self.ret_data = self._response.content
elif self._response.status_code == 400:
raise APIBadRequest(self._response.content)
elif self._response.status_code == 401:
raise APIUnauthorized(self._response.content)
elif self._response.status_code == 419:
raise APIAuthenticationTimeout(self._response.content)
elif self._response.status_code == 500:
raise APIInternalServerError(self._response.content)
def _call(self, interface):
""" Call to the specified interface with the parameters determined by the "parameters" class attribute."""
url = "%s/%s/%s" % (self._api_base_url, self._api_type, interface)
if self.use_get_method:
if self.use_data_parameter:
data = base64.b64encode(json.dumps(self.parameters, encoding="UTF-8"))
par = {'data':data}
else:
par = self.parameters
self._response = self._session.get(url=url,params=par, verify=False)
else:
self._response = self._session.post(url=url,data=json.dumps(self.parameters, encoding="UTF-8"), headers={'Content-Type':'application/json'}, verify=False)
self._parse_response()
self._last_api_call = interface
if self.debug: self._generate_debug_info_api(url)
def _call_ingest(self, interface, pkg=None):
""" Call the specified interface using with the parameters determined by the "parameters" class attribute."""
url = "%s/%s/%s" % (self._api_base_url, self._api_type, interface)
self.parameters['manifest'] = self.manifest
if pkg != None:
files = {'json':('data.json', json.dumps(self.parameters, encoding="UTF-8"), 'application/json')}
files['pkg'] = ('mp.zip', open(pkg, 'rb'), 'application/zip')
self._response = self._session.post(url=url,files=files, verify=False)
else:
self._response = self._session.post(url=url,data=json.dumps(self.parameters, encoding="UTF-8"), headers={'Content-Type':'application/json'}, verify=False)
self._parse_response()
self._last_api_call = interface
if self.debug:
self._generate_debug_info_api(url)
else:
if self._tmp_dir != None:
shutil.rmtree(self._tmp_dir)
def _is_url(self, url):
try:
myurl = urllib2.urlopen(url).geturl()
except:
return False
return True
def _get_file_format(self, fp):
return os.path.splitext(fp)[1][1:]
def _get_file_name(self, fp):
return os.path.basename(fp)
def _md5sum(self, fp):
md5 = hashlib.md5()
with open(fp, 'rb') as f:
for chunk in iter(lambda: f.read(128 * md5.block_size), b''):
md5.update(chunk)
return md5.hexdigest()
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
> *Get a list of all available Speech Recognition, Machine
> Translation, and Text-To-Speech Systems that can be applied to
> transcribe, translate, and synthesize a media file.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
class TLPStandardClient(TLPClient):
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type):
"""
Creates a `TLPStandardClient` class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._api_mod_session_id = None
"""Tells wether the /ingest API call requires to upload a media package"""
self._manifest_files = None
self.requires_package = False
self.manifest = None
"""Manifest JSON object."""
TLPClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type)
def create_media_package(self, dest=None):
"""Creates a Media Package File from the `libtlp.TLPStandardClient.manifest` JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a
temporal directory, unless you specify the destination file path with the
optional parameter **_dest_**.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self._tmp_dir = tempfile.mkdtemp()
if dest == None:
dest = "%s/mpf.zip" % self._tmp_dir
zf = zipfile.ZipFile(dest, mode='w', allowZip64=True)
for f in self._manifest_files:
zf.write(f[0], arcname=f[1])
zf.close()
return dest
def api_ingest_new(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/new interface:
> *Upload media (audio/video) files and many other attachments and
> metadata to the TLP Server for automatic multilingual subtitling
> and speech synthesization.*
If **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/new', mp_fp)
self._last_api_call = "ingest"
def api_ingest_update(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/update interface:
> *Upload media (audio/video) files and many other attachments and
> metadata to the TLP Server for automatic multilingual subtitling
> and speech synthesization.*
If **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/update', mp_fp)
self._last_api_call = "ingest"
def api_ingest_delete(self, oid, mode=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/delete interface:
> *Delete a media object in the TLP Server.*
**_oid_** must be a media ID.
Optionally, **_mode__** provides the deletion mode.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if mode != None:
if mode not in ['hard', 'soft']:
raise TLPException("Delete mode must be 'hard' or 'soft'")
self.parameters['mode'] = mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/delete')
def api_ingest_cancel(self, oid, debug_mode=False, su=None):
""" Performs an API call to the /ingest/cancel interface:
> * Cancel upload operation. *
**_oid_** must be an upload ID.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/cancel')
self._last_api_call = "ingest"
def api_uploadslist(self, object_id=None, su=None):
""" Performs an API call to the /uploadslist interface:
> *Get a list of all user's uploads.*
If the optional **_object_id_** argument is given, then the Web
Service will return a list of uploads involving the provided object ID (could
be an Upload ID or a Media ID).
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if object_id != None: self.parameters['object_id'] = object_id
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("uploadslist")
def api_status(self, oid, su=None):
""" Performs an API call to the /status interface:
> *Check the current status of a specific upload ID.*
**_oid_** is an upload ID, returned by the /ingest interface.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("status")
def api_list(self, su=None):
""" Performs an API call to the /list interface:
> *Get a list of all existing audios and videos in the TLP Database.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("list")
def api_langs(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /langs interface:
> *Get a list of all subtitle and audiotrack languages available for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("langs")
def api_metadata(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /metadata interface:
> *Get metadata and media file locations for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("metadata")
def api_start_session(self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /start_session interface:
> *Starts an edition session to send and commit modifications of a subtitles file.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("start_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = self.ret_data['session_id']
def api_session_status(self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /session_status interface:
> *Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.*
By default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to check session status (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['alive'] = int(alive)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("session_status")
def api_end_session(self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /end_session interface:
> *Ends an existing edition session.*
By default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_force_** option should set to *True* to force the end of a session when
the given **_author_id_** or API user are not the same that started the given
**_session_id**.
The **_regenerate_** option tells to the TLP Server if subtitles and/or synthesized audiotracks will be
regenerated after ending the session. By default it is set to *True*.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['force'] = int(force)
self.parameters['regenerate'] = int(regenerate)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("end_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = None
def api_lock(self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /lock interface:
> *Allow/disallow regular users to send subtitles modifications for an specific Media ID.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(lock, bool)):
raise TLPException("lock must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['lock'] = int(lock)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("lock")
def api_edit_history(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /edit_history interface:
> *Returns a list of all edit sessions carried out over an specific Media ID.*
The **_oid_** parameter is the Media ID. Optionally, a media hash
value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("edit_history")
def api_mark_revised(self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /mark_revised interface:
> *Mark/unmark an edition session as revised.*
**_session_id_** is the Session ID to mark/unmark as revised,
the **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(unmark, bool)):
raise TLPException("unmark must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['unmark'] = int(unmark)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mark_revised")
def api_accept(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /accept interface:
> *Accept modifications of one or more pending edit sessions without having to revise them.*
The **_ids_** parameter must be a list Session IDs whose edits are
meant to be accepted by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("accept")
def api_reject(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /reject interface:
> *Reject modifications of one or more pending edit sessions without having to revise them.*
The **_ids_** parameter must be a list Session IDs whose edits are
meant to be rejected by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("reject")
def api_revisions(self, su=None):
""" Performs an API call to the /revisions interface:
> *Returns a list of all edit sessions for all API user's media files that are pending to be revised.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("revisions")
class TLPSpeechClient(TLPStandardClient):
FTYPE_CODE_MEDIA = 0
"""Main Media file type code"""
FTYPE_CODE_SLIDES = 1
"""Slides file type code code"""
FTYPE_CODE_DOCUMENT = 2
"""Related Text Document file type code"""
FTYPE_CODE_THUMBNAIL = 3
"""Media thumbnail file type code"""
FTYPE_CODE_SUBS = 4
"""Subtitles file type code"""
FTYPE_CODE_AUDIOTRACK = 5
"""Audiotrack file type code"""
FTYPE_CODE_WAVEFORM = 6
"""Waveform file type code"""
FTYPE_CODE_NONTIMED_TRANSCRIPT = 7
"""Non-timed transcript file type code"""
SUBS_SELDATA_ALL = 0
"""Subtitle contents to be returned: Return both former and current contents (only for DFXP format). """
SUBS_SELDATA_FORMER = 1
"""Subtitle contents to be returned: Return former contents (automatic transcription or translation). """
SUBS_SELDATA_CURRENT = 2
"""Subtitle contents to be returned: Return current contents (current status of supervision of the subtitles). """
SUBS_SEGFILT_EMTPY = -1
"""Segment text filtering policy: Empty all segments (removes text from all segments). """
SUBS_SEGFILT_DISABLE = 0
"""Segment text filtering policy: Filtering disabled. """
SUBS_SEGFILT_ENABLE = 1
"""Segment text filtering policy: Filters out special annotations. """
DEL_MODE_SOFT = 'soft'
"""Soft delete mode for the /ingest/delete interface"""
DEL_MODE_HARD = 'hard'
"""Hard delete mode for the /ingest/delete interface"""
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key):
"""
Creates a TLPSpeechClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_player_base_url_**: Base URL to the transLectures-UPV Platform's Player.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, TLPClient.API_SPEECH)
def manifest_init(self, external_id):
"""Initalize the `libtlp.TLPSpeechClient.manifest` JSON object.
**_external_id_** must be a Media ID or an existing upload ID.
**Note:** This method should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['metadata'] = {}
self.manifest['metadata']['external_id'] = external_id
def manifest_set_metadata(self, language=None, title=None, topic=None, keywords=None, date=None):
"""Set metadata in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the Media language code in ISO 639-1 format (e.g.
"en", "es"), **_title_** is the title of the media, **_topic_** is the topic of
the media, **_keywords_** are the media keywords, and **_date_** is the
publication date of the media.
All arguments are optional, but **_language_** and **_title_**
arguments are mandatory for "New" operations.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if language != None:
self.manifest['metadata']['language'] = language
if title != None:
self.manifest['metadata']['title'] = title
if topic != None:
self.manifest['metadata']['topic'] = topic
if keywords != None:
self.manifest['metadata']['keywords'] = keywords
if date != None:
self.manifest['metadata']['date'] = date
def manifest_add_speaker(self, speaker_id, speaker_name, email=None, gender=None):
"""Add a speaker in the metadata section of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_speaker_id_** is the speaker ID of the media file, **_speaker_name_** is
the full name of the speaker, **_email_** is the e-mail of the speaker, and
**_gender_** is the gender of the speaker (*M* for Male or *F* for Female).
**_email_** and **_gender_** are optional.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
spk = {}
spk['speaker_id'] = speaker_id
spk['speaker_name'] = speaker_name
if gender != None: spk['speaker_gender'] = gender
if email != None: spk['speaker_email'] = email
try:
self.manifest['metadata']['speakers'].append(spk)
except:
self.manifest['metadata']['speakers'] = [spk]
def manifest_set_main_media_file(self, uri, slides=False):
"""Set main media file in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** can be a media file path o a media URL.
If the **_slides_** flat is set to true, video is treated also as a
slides file to improve the transcription quality.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['media'] = {}
if self._is_url(uri):
self.manifest['media']['url'] = uri
else:
self.manifest['media']['fileformat'] = self._get_file_format(uri)
self.manifest['media']['md5'] = self._md5sum(uri)
self.manifest['media']['filename'] = "%s.%s" % (self.manifest['media']['md5'], self.manifest['media']['fileformat'])
#self.manifest['media']['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, self.manifest['media']['filename']))
self.requires_package = True
self.manifest['media']['slides'] = slides
def manifest_add_attachment(self, uri, file_type_code, language=None, human=None):
"""Add attachment file to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** is the attachment file path, and **_file_type_code_** must be one of
the following values: `libtlp.TLPSpeechClient.FTYPE_CODE_MEDIA`,
`libtlp.TLPSpeechClient.FTYPE_CODE_SLIDES`, `libtlp.TLPSpeechClient.FTYPE_CODE_DOCUMENT`,
`libtlp.TLPSpeechClient.FTYPE_CODE_THUMBNAIL`, `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`,
`libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`,
`libtlp.TLPSpeechClient.FTYPE_CODE_WAVEFORM`, `libtlp.TLPSpeechClient.FTYPE_CODE_NONTIMED_TRANSCRIPT`.
In case **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`
or **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`, **_language_** and **_human_**
arguments are mandatory. The first one is the requested subtitles language
code in ISO 639-1 format (e.g. "en", "es"), while **_human_** is a boolean
variable indicationg whether the provided subtitles or audiotrack have been
produced by a human, or have been generated automatically by a computer.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
at = {}
at['fileformat'] = self._get_file_format(uri)
at['md5'] = self._md5sum(uri)
#at['filename'] = self._get_file_name(uri)
at['filename'] = "%s.%s" % (at['md5'], at['fileformat'])
at['type_code'] = file_type_code
if language != None: at['language'] = language
if human != None: at['human'] = human
try:
self.manifest['attachments'].append(at)
except:
self.manifest['attachments'] = [at]
self._manifest_files.append((uri, at['filename']))
self.requires_package = True
def manifest_add_subtitles_request(self, language, system_id=None, lm_adapt=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, **_lm_adapt_** is a boolean variable to enable or disable the
Language Model Adaptation technique, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
if lm_adapt != None: d['lma'] = lm_adapt
self.manifest['requested_langs'][language]['sub'] = d
def manifest_add_audiotrack_request(self, language, system_id=None):
"""Request audiotrack language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested audiotrack language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language]['tts'] = d
def manifest_set_options(self, generate=True, regenerate=None, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
transcriptions, translations and/or synthesized audiotracks. Must be a list of
keywords. Allowed Keywords are: *tx* (request regeneration of the media
transcription), *tl* (request regeneration of media translations), *tts*
(request regeneration of synthesized audiotracks). Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised subtitles.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty subtitles file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def manifest_add_callback_function(self, url, params=None):
"""Add a HTTP REST callback function into the `libtlp.TLPSpeechClient.manifest` JSON object, to
receive notifications about relevant upload status updates
**_url_** is the URL of a HTTP POST function that will receive notifications.
**_params_** is an optional dictionary that provides predefined parameter names and values that
will be added to the POST call (typically, authentication parameters). E.g. params={"auth_token":"deQkw3"}.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['callback'] = {}
self.manifest['callback']["url"] = url
if params != None:
if not(isinstance(params, dict)):
raise TLPException("'params' parameter should be a python dictionary.")
self.manifest['callback']['params'] = params
def api_get(self, oid, lang, form=None, seldata=None, segfilt=None, session_id=None, pending_revs=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
The **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible formats are: *dfxp* (default), *srt*, *ttml*, *vtt*, *text*, *json*, *ibmjson*, *stl*, *docx*.
**_seldata_** and **_segfilt_** are also optional parameters
corresponding to the *sel_data_policy* and *seg_filt_policy* API call
parameters.
On the one hand, **_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPSpeechClient.SUBS_SELDATA_ALL`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_FORMER`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_CURRENT`*.
On the other hand, **_segfilt_** specifies the segment text filtering
policy. Possible values are: *`libtlp.TLPSpeechClient.SUBS_SEGFILT_EMTPY`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_DISABLE`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_ENABLE`*.
If **_session_id_** is provided, will return the result of
applying to the original subtitle file all confirmed subtitle modifications upon
the given session ID.
If **_pending_revs_** is provided, will return the current subtitle file applying those revisions
that are still pending to be reviewed. Must be a boolean.
For further details of both API call parameters please check the full TLP API documentation.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
Dformats = { 'dfxp':0, 'ttml':1, 'srt':2, 'vtt':3, 'text':4, 'json':5, 'ibmjson':6, 'stl':7, 'docx':8 }
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None: self.parameters['format'] = Dformats[form]
if seldata != None: self.parameters['sel_data_policy'] = seldata
if segfilt != None: self.parameters['seg_filt_policy'] = segfilt
if session_id != None: self.parameters['session_id'] = session_id
if pending_revs != None:
if pending_revs:
self.parameters['pending_revs'] = 1
else:
self.parameters['pending_revs'] = 0
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_getmod(self, oid, session_id, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /getmod interface:
> *Get subtitle modifications in JSON format of a given media and session ID.*
The **_oid_** parameter is the Media ID, and **_session_id_** is the session ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("getmod")
def api_audiotrack(self, oid, lang, aid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /audiotrack interface:
> *Download an audiotrack file for a given media ID and language.*
The **_oid_** parameter is the Media ID, **_lang_** is the
language code (ISO 639-1) of the requested audiotrack language, and
**_aid_** is the audiotrack ID (retrieved from the /metadata interface).
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
self.parameters['aid'] = aid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("audiotrack")
def api_mod(self, oid, lang, author_id, author_conf, txt_array, del_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
By default, the session ID will be the one returned after calling the
`libtlp.TLPSpeechClient.start_session` interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "b":, "e":, "t":}
**sI** is the segment ID, **b** is the segment start time, **e** is the segment end time, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
**_del_array_** is a list containing the segment IDs (int values) to delete. It must be an empty list if no segments are being deleted.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[], 'del':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if del_array != None: self.parameters['mods'][lang]['del'] = del_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def api_active_sessions(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /speech/active_sessions interface:
> *Returns a list of active edit sessions involving a given media ID..*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("active_sessions")
def generate_player_url(self, oid, author_id, author_conf, session_id=None, req_key_lifetime=1440, language=None, author_name=None, start=None, options=None):
""" Returns a valid TLP Player URL.
**_oid_** is the Media ID, **_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
It is possible to open the TLP player in read-only (RO) mode: just
set **_author_id_** parameter to `None`.
Optionally, a **_language_** ISO-639-1 code can be provided to make
the Player load directly the specified subtitles language (if not provided, the
Player will load the source language transcriptions). Also, you can set the
media start time in seconds with the **_start_** parameter.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
You can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
**_options_** is an optional dict with valid Player options, to be
passed as `params` via GET. E.g. `{"mode":"transcriptor",
"autosave":5}`.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if language != None: self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
if options != None:
if not(isinstance(options, dict)):
raise TLPException("options parameter must be a python dict.")
params_parameter = base64.b64encode(json.dumps(options, encoding='UTF-8'))
url = "%s¶ms=%s" % (url, params_parameter)
if start != None:
url += "&t=%d" % int(start)
return url
class TLPTextClient(TLPStandardClient):
TRANS_FORMAT_ORIGINAL = 0
"""Translation file in original format"""
TRANS_FORMAT_HTML = 1
"""Translation file in internal HTML format"""
TRANS_FORMAT_DTLX = 2
"""Translation file in internal DTLX format"""
TRANS_FORMAT_TEXT = 3
"""Translation file in text format"""
TRANS_SELDATA_ALL = 0
"""Translation contents to be returned: Return both former and current contents (only for DTLX format). """
TRANS_SELDATA_FORMER = 1
"""Translation contents to be returned: Return former contents (automatic translation). """
TRANS_SELDATA_CURRENT = 2
"""Translation contents to be returned: Return current contents (current status of supervision of the translation). """
DEL_MODE_SOFT = 'soft'
"""Soft delete mode for the /ingest/delete interface"""
DEL_MODE_HARD = 'hard'
"""Hard delete mode for the /ingest/delete interface"""
def __init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPTextClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_translation_editor_base_url_**: Base URL to the transLectures-UPV Platform's Translation Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key, TLPClient.API_TEXT)
def _set_auth_parameters_request_key_translation_editor(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for generating a Player URL."""
self.parameters['api_user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['request_key'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def manifest_init(self, language):
"""Initalize the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the documents' language code in ISO 639-1 format (e.g.
"en", "es").
**Note:** This method should be executed before calling the `libtlp.TLPTextClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['documents'] = []
self.manifest['language'] = language
def manifest_add_document(self, external_id, uri=None, title=None, fileformat=None):
"""Set main media file in the `libtlp.TLPTextClient.manifest` JSON object.
**_external_id_** must be a Document ID.
**_uri_** can be a media file path o a media URL.
**_title_** is the title of the media.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
doc = {}
doc['external_id'] = external_id
if title != None:
doc['title'] = title
if uri != None:
if self._is_url(uri):
doc['url'] = uri
else:
if fileformat != None:
doc['fileformat'] = fileformat
else:
doc['fileformat'] = self._get_file_format(uri)
doc['md5'] = self._md5sum(uri)
doc['filename'] = "%s.%s" % (doc['md5'], doc['fileformat'])
#doc['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, doc['filename']))
self.requires_package = True
self.manifest['documents'].append(doc)
def manifest_add_translation_request(self, language, system_id=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language] = d
def manifest_set_options(self, generate=True, regenerate=False, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPTextClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
translations. Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised translations.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty translation file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def api_get(self, oid, lang, form=None, seldata=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
The **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible values are: *`libtlp.TLPTextClient.TRANS_FORMAT_ORIGINAL`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_HTML`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_DTLX`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_TXT`*.
**_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPTextClient.TRANS_SELDATA_ALL`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_FORMER`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_CURRENT`*.
A **_session_id_** argument can be provided in order to apply subtitle modifications made under the given edit session ID to the subtitles file.
For further details of both API call parameters please check the full TLP API documentation.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None:
if form not in (self.TRANS_FORMAT_ORIGINAL, self.TRANS_FORMAT_HTML, self.TRANS_FORMAT_DTLX, self.TRANS_FORMAT_TEXT):
raise TLPException("Unallowed document format.")
self.parameters['format'] = form
if seldata != None: self.parameters['sel_data_policy'] = seldata
if session_id != None: self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_mod(self, oid, lang, author_id, author_conf, txt_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
By default, the session ID will be the one returned after calling the
`libtlp.TLPTextClient.start_session` interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "t":}
**sI** is the segment ID, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def generate_translation_editor_url(self, oid, language, author_id, author_conf, session_id=None, req_key_lifetime=1440, author_name=None):
""" Returns a valid TLP Translation Editor URL.
**_oid_** is the Document ID, **_language_** is the ISO-639-1 code of the translation language to edit,
**_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
Finally, you can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
class TLPWebClient(TLPClient):
def __init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPWebClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPClient.__init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key, TLPClient.API_WEB)
def api_manage_list(self, su=None):
""" Performs an API call to the /web/manage/list interface:
> *Get list of websites.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/list")
def api_manage_add(self, name, language, url_pattern, requested_langs, su=None):
""" Performs an API call to the /web/manage/add interface:
> *Adds a new web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['name'] = name
self.parameters['language'] = language
self.parameters['url_pattern'] = url_pattern
self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/add")
def api_manage_edit(self, key, enabled=None, url_pattern=None, requested_langs=None, su=None):
""" Performs an API call to the /web/manage/edit interface:
> *Edits and existing web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if enabled != None: self.parameters['enabled'] = enabled
if url_pattern != None: self.parameters['url_pattern'] = url_pattern
if requested_langs != None: self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/edit")
def api_manage_delete(self, key, purge=None, su=None):
""" Performs an API call to the /web/manage/delete interface:
> *Deletes an existing web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if purge != None: self.parameters['purge'] = purge
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/delete")
def api_editor_langs(self, key, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/langs interface:
> *Returns a list of translation languages available for a specific website.*
**_key_** must be the Website Key.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/langs")
def api_editor_get(self, key, language, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/get interface:
> *Returns all existing source texts or translations of a specific website.*
**_key_** must be the Website Key, and **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es").
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/get")
def api_editor_mod(self, key, language, texts, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/mod interface:
> *Updates text translations of a specific website and language.*
**_key_** must be the Website Key, **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es"), and **_texts_** a dictionary of text hashes and text contents (i.e. '{"af129cd836a":"My updated text"}').
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
self.parameters['text'] = texts
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/mod")
def generate_web_translation_editor_url(self, web_key, language, req_key_lifetime=1440):
""" Returns a valid TLP Translation Editor URL.
**_web_key_** is the Website Key, and **_language_** is the ISO-639-1 code of the translation language to edit.
You can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = web_key
self.parameters['lang'] = language
self._set_auth_parameters_request_key_editor(req_key_lifetime, web_key)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
class TLPException(Exception):
"""Generic TLP Exception"""
def __init__(self, msg):
self.msg = msg
def __str__(self):
return self.msg
class APIBadRequest(TLPException):
"""Exception that is raised when the TLP Web Service returns a "400 Bad Request" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "400 Bad Request" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
class APIUnauthorized(TLPException):
"""Exception that is raised when the TLP Web Service returns a "401 Unauthorized" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "401 Unautorized" HTTP error code (please check your API credentials)'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
class APIAuthenticationTimeout(TLPException):
"""Exception that is raised when the TLP Web Service returns a "419 Authentication Timeout" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "419 Authentication Timeout" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
class APIInternalServerError(TLPException):
"""Exception that is raised when the TLP Web Service returns a "500 Internal Server Error" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "500 Internal Server Error" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
Classes
class APIAuthenticationTimeout
Exception that is raised when the TLP Web Service returns a "419 Authentication Timeout" HTTP error code.
class APIAuthenticationTimeout(TLPException):
"""Exception that is raised when the TLP Web Service returns a "419 Authentication Timeout" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "419 Authentication Timeout" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
Ancestors (in MRO)
- APIAuthenticationTimeout
- TLPException
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object
Class variables
Instance variables
Methods
class APIBadRequest
Exception that is raised when the TLP Web Service returns a "400 Bad Request" HTTP error code.
class APIBadRequest(TLPException):
"""Exception that is raised when the TLP Web Service returns a "400 Bad Request" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "400 Bad Request" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
Ancestors (in MRO)
- APIBadRequest
- TLPException
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object
Class variables
Instance variables
Methods
class APIInternalServerError
Exception that is raised when the TLP Web Service returns a "500 Internal Server Error" HTTP error code.
class APIInternalServerError(TLPException):
"""Exception that is raised when the TLP Web Service returns a "500 Internal Server Error" HTTP error code."""
def __str__(self):
string = 'TLP Web Service retuned a "500 Internal Server Error" HTTP error code'
if self.msg.strip() != "":
string = '%s: \n\n%s\n' % (string, self.msg)
else:
string = '%s.' % string
return string
Ancestors (in MRO)
- APIInternalServerError
- TLPException
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object
Class variables
Instance variables
Methods
Exception that is raised when the TLP Web Service returns a "401 Unauthorized" HTTP error code.
Ancestors (in MRO)
- APIUnauthorized
- TLPException
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object
Class variables
Inheritance:
TLPException.args
Inheritance:
TLPException.message
Instance variables
Inheritance:
TLPException.msg
Methods
class TLPClient
TLPClient class.
class TLPClient():
"""
TLPClient class.
"""
TLP_VERSION = "3.X"
API_SPEECH = "speech"
API_TEXT = "text"
API_WEB = "web"
def __init__(self, api_base_url, editor_base_url, api_user, api_secret_key, api_type):
"""
Creates a TLPClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._last_api_call = None
self._tmp_dir = None
self._session = None
self._response = None
self._http_auth_enabled = False
self._http_user = None
self._http_pass = None
self._api_base_url = api_base_url
self._api_type = api_type
self._editor_base_url = editor_base_url
self._api_user = api_user
self._api_secret_key = api_secret_key
self.use_get_method = False
"""Use HTTP GET Method instead of POST."""
self.use_data_parameter = True
"""Use a single "data" parameter on HTTP GET calls instead multiple GET parameters."""
self.parameters = None
"""Dictionary with API query parameters."""
self.ret_data = None
"""Data returned by the last performed API call. If the response was a JSON object, *ret_data* becomes a a parsed JSON object (dictionary or list, depending on the JSON)."""
self.ret_content_type = None
"""Mime-type of the data returned by the last performed API call."""
self.debug = False
"""Enable/Disable generation of debug information."""
self.debug_info = None
"""Debug information of the last performed API call / Generation of Player URL."""
def _reset_http_session(self):
"""Resets requests.Session class instance."""
self._session = requests.Session()
if self._http_auth_enabled:
self._session.auth = (self._http_user, self._http_pass)
def _reset(self):
"""Reset all class methods to perform a new API call."""
self._reset_http_session()
self._response = None
self.parameters = {}
self.parameters["client"] = "libtlp-%s" % (self.TLP_VERSION)
self.ret_data = None
self.ret_content_type = None
self.debug_info = None
def _set_auth_parameters_secret_key(self):
"""Set API authentication parameters using the secret key."""
self.parameters['user'] = self._api_user
self.parameters['auth_token'] = self._api_secret_key
def _set_auth_parameters_request_key_api(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for an API call."""
self.parameters['user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['auth_token'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def _set_auth_parameters_request_key_editor(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for generating am Editor URL."""
self.parameters['api_user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['request_key'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def _gen_expire_parameter(self, lifetime):
"""Returns a valid value of the "expire" API authentication parameter."""
return int((datetime.utcnow() + timedelta(minutes=lifetime) - datetime(1970,01,01)).total_seconds())
def _generate_debug_info_api(self, url):
""" Generates debug information about the last API call."""
o = cStringIO.StringIO()
o.write("\n")
o.write("- Input data (JSON-formatted):\n")
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
o.write("\n")
if self.use_get_method:
if self.use_data_parameter:
o.write("- URL (using GET request with a single 'data' base64-encoded JSON parameter):\n")
o.write("%s?data=%s\n" % (url, base64.b64encode(json.dumps(self.parameters, encoding="UTF-8"))))
o.write("\n")
else:
o.write("- URL (using GET request with multiple parameters):\n")
params = "&".join([ "%s=%s"%(k, str(self.parameters[k])) for k in self.parameters ])
o.write("%s?%s\n" % (url, params))
o.write("\n")
else:
o.write("- URL + POST data:\n")
o.write("%s\n" % url)
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
if self._last_api_call == "ingest":
if self.manifest != None:
o.write("\n- Manifest.JSON file:\n")
o.write("%s\n" % self.get_printable_manifest())
o.write("\n")
if self._tmp_dir != None:
o.write("- Temp dir: %s\n" % self._tmp_dir)
o.write("\n- TLP Server response:\n")
self.debug_info = o.getvalue()
def _generate_debug_info_editor(self):
""" Generates debug information about the last generated Player URL."""
o = cStringIO.StringIO()
o.write("\n")
o.write("- Input data (JSON-formatted):\n")
o.write("%s\n" % json.dumps(self.parameters, encoding="UTF-8", indent=4))
o.write("\n")
o.write("- Input data (Base 64):\n")
o.write("%s\n" % base64.b64encode(json.dumps(self.parameters, encoding="UTF-8")))
o.write("\n")
self.debug_info = o.getvalue()
def _parse_response(self):
if self._response.status_code == 200:
self.ret_content_type = self._response.headers['content-type']
if self.ret_content_type.find("application/json") >= 0:
self.ret_data = json.loads(self._response.content)
else:
self.ret_data = self._response.content
elif self._response.status_code == 400:
raise APIBadRequest(self._response.content)
elif self._response.status_code == 401:
raise APIUnauthorized(self._response.content)
elif self._response.status_code == 419:
raise APIAuthenticationTimeout(self._response.content)
elif self._response.status_code == 500:
raise APIInternalServerError(self._response.content)
def _call(self, interface):
""" Call to the specified interface with the parameters determined by the "parameters" class attribute."""
url = "%s/%s/%s" % (self._api_base_url, self._api_type, interface)
if self.use_get_method:
if self.use_data_parameter:
data = base64.b64encode(json.dumps(self.parameters, encoding="UTF-8"))
par = {'data':data}
else:
par = self.parameters
self._response = self._session.get(url=url,params=par, verify=False)
else:
self._response = self._session.post(url=url,data=json.dumps(self.parameters, encoding="UTF-8"), headers={'Content-Type':'application/json'}, verify=False)
self._parse_response()
self._last_api_call = interface
if self.debug: self._generate_debug_info_api(url)
def _call_ingest(self, interface, pkg=None):
""" Call the specified interface using with the parameters determined by the "parameters" class attribute."""
url = "%s/%s/%s" % (self._api_base_url, self._api_type, interface)
self.parameters['manifest'] = self.manifest
if pkg != None:
files = {'json':('data.json', json.dumps(self.parameters, encoding="UTF-8"), 'application/json')}
files['pkg'] = ('mp.zip', open(pkg, 'rb'), 'application/zip')
self._response = self._session.post(url=url,files=files, verify=False)
else:
self._response = self._session.post(url=url,data=json.dumps(self.parameters, encoding="UTF-8"), headers={'Content-Type':'application/json'}, verify=False)
self._parse_response()
self._last_api_call = interface
if self.debug:
self._generate_debug_info_api(url)
else:
if self._tmp_dir != None:
shutil.rmtree(self._tmp_dir)
def _is_url(self, url):
try:
myurl = urllib2.urlopen(url).geturl()
except:
return False
return True
def _get_file_format(self, fp):
return os.path.splitext(fp)[1][1:]
def _get_file_name(self, fp):
return os.path.basename(fp)
def _md5sum(self, fp):
md5 = hashlib.md5()
with open(fp, 'rb') as f:
for chunk in iter(lambda: f.read(128 * md5.block_size), b''):
md5.update(chunk)
return md5.hexdigest()
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
> *Get a list of all available Speech Recognition, Machine
> Translation, and Text-To-Speech Systems that can be applied to
> transcribe, translate, and synthesize a media file.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
Ancestors (in MRO)
Class variables
var API_SPEECH
var API_TEXT
var API_WEB
var TLP_VERSION
Instance variables
var debug
Enable/Disable generation of debug information.
var debug_info
Debug information of the last performed API call / Generation of Player URL.
var parameters
Dictionary with API query parameters.
var ret_content_type
Mime-type of the data returned by the last performed API call.
var ret_data
Data returned by the last performed API call. If the response was a JSON object, ret_data becomes a a parsed JSON object (dictionary or list, depending on the JSON).
var use_data_parameter
Use a single "data" parameter on HTTP GET calls instead multiple GET parameters.
var use_get_method
Use HTTP GET Method instead of POST.
Methods
def __init__(
self, api_base_url, editor_base_url, api_user, api_secret_key, api_type)
Creates a TLPClient class instance. Parameters:
- api_base_url: Base URL to the transLectures-UPV Platform's Web Service.
- editor_base_url: Base URL to the transLectures-UPV Platform's Editor.
- api_user: API username / TLP username.
- api_secret_key: API Secret Key.
- api_type: API type, must be
API_SPEECH,API_TEXTorAPI_WEB.
def __init__(self, api_base_url, editor_base_url, api_user, api_secret_key, api_type):
"""
Creates a TLPClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._last_api_call = None
self._tmp_dir = None
self._session = None
self._response = None
self._http_auth_enabled = False
self._http_user = None
self._http_pass = None
self._api_base_url = api_base_url
self._api_type = api_type
self._editor_base_url = editor_base_url
self._api_user = api_user
self._api_secret_key = api_secret_key
self.use_get_method = False
"""Use HTTP GET Method instead of POST."""
self.use_data_parameter = True
"""Use a single "data" parameter on HTTP GET calls instead multiple GET parameters."""
self.parameters = None
"""Dictionary with API query parameters."""
self.ret_data = None
"""Data returned by the last performed API call. If the response was a JSON object, *ret_data* becomes a a parsed JSON object (dictionary or list, depending on the JSON)."""
self.ret_content_type = None
"""Mime-type of the data returned by the last performed API call."""
self.debug = False
"""Enable/Disable generation of debug information."""
self.debug_info = None
"""Debug information of the last performed API call / Generation of Player URL."""
def api_systems(
self, su=None)
Performs an API call to the /systems interface:
Get a list of all available Speech Recognition, Machine Translation, and Text-To-Speech Systems that can be applied to transcribe, translate, and synthesize a media file.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
*Get a list of all available Speech Recognition, Machine
Translation, and Text-To-Speech Systems that can be applied to
transcribe, translate, and synthesize a media file.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
def disable_http_auth(
self)
Disable HTTP Authentication for all API calls
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def enable_http_auth(
self, http_user, http_pass)
Use HTTP Authentication for all API calls.
http_user is the HTTP Authentication username, while http_pass is the corresponding user password.
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def gen_request_key(
self, oid, expire, author=None, author_conf=None)
Returns a valid request key to be used as an API authentication token.
oid is the object ID that will be queried (id API call parameter), and expire is the UNIX timestamp of the expiration time of the key. With these two parameters is generated the basic request key.
If author (author_id API parameter) is supplied, then the full request key is generated using this parameter plus author_conf (author_conf API parameter).
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def get_printable_manifest(
self)
Returns a printable, user friendly version of the manifest JSON object (stored in the libtlp.TLPClient.manifest class member).
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def get_printable_response_data(
self)
Returns a printable, user friendly version of the response data from the
last API call (stored in the ret_data class member).
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def save_response_data(
self, dest)
Saves the response data from the last API call (stored in the ret_data
class member) into the destination dest file.
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
class TLPException
Generic TLP Exception
class TLPException(Exception):
"""Generic TLP Exception"""
def __init__(self, msg):
self.msg = msg
def __str__(self):
return self.msg
Ancestors (in MRO)
- TLPException
- exceptions.Exception
- exceptions.BaseException
- __builtin__.object
Class variables
var args
var message
Instance variables
var msg
Methods
def __init__(
self, msg)
def __init__(self, msg):
self.msg = msg
class TLPSpeechClient
class TLPSpeechClient(TLPStandardClient):
FTYPE_CODE_MEDIA = 0
"""Main Media file type code"""
FTYPE_CODE_SLIDES = 1
"""Slides file type code code"""
FTYPE_CODE_DOCUMENT = 2
"""Related Text Document file type code"""
FTYPE_CODE_THUMBNAIL = 3
"""Media thumbnail file type code"""
FTYPE_CODE_SUBS = 4
"""Subtitles file type code"""
FTYPE_CODE_AUDIOTRACK = 5
"""Audiotrack file type code"""
FTYPE_CODE_WAVEFORM = 6
"""Waveform file type code"""
FTYPE_CODE_NONTIMED_TRANSCRIPT = 7
"""Non-timed transcript file type code"""
SUBS_SELDATA_ALL = 0
"""Subtitle contents to be returned: Return both former and current contents (only for DFXP format). """
SUBS_SELDATA_FORMER = 1
"""Subtitle contents to be returned: Return former contents (automatic transcription or translation). """
SUBS_SELDATA_CURRENT = 2
"""Subtitle contents to be returned: Return current contents (current status of supervision of the subtitles). """
SUBS_SEGFILT_EMTPY = -1
"""Segment text filtering policy: Empty all segments (removes text from all segments). """
SUBS_SEGFILT_DISABLE = 0
"""Segment text filtering policy: Filtering disabled. """
SUBS_SEGFILT_ENABLE = 1
"""Segment text filtering policy: Filters out special annotations. """
DEL_MODE_SOFT = 'soft'
"""Soft delete mode for the /ingest/delete interface"""
DEL_MODE_HARD = 'hard'
"""Hard delete mode for the /ingest/delete interface"""
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key):
"""
Creates a TLPSpeechClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_player_base_url_**: Base URL to the transLectures-UPV Platform's Player.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, TLPClient.API_SPEECH)
def manifest_init(self, external_id):
"""Initalize the `libtlp.TLPSpeechClient.manifest` JSON object.
**_external_id_** must be a Media ID or an existing upload ID.
**Note:** This method should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['metadata'] = {}
self.manifest['metadata']['external_id'] = external_id
def manifest_set_metadata(self, language=None, title=None, topic=None, keywords=None, date=None):
"""Set metadata in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the Media language code in ISO 639-1 format (e.g.
"en", "es"), **_title_** is the title of the media, **_topic_** is the topic of
the media, **_keywords_** are the media keywords, and **_date_** is the
publication date of the media.
All arguments are optional, but **_language_** and **_title_**
arguments are mandatory for "New" operations.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if language != None:
self.manifest['metadata']['language'] = language
if title != None:
self.manifest['metadata']['title'] = title
if topic != None:
self.manifest['metadata']['topic'] = topic
if keywords != None:
self.manifest['metadata']['keywords'] = keywords
if date != None:
self.manifest['metadata']['date'] = date
def manifest_add_speaker(self, speaker_id, speaker_name, email=None, gender=None):
"""Add a speaker in the metadata section of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_speaker_id_** is the speaker ID of the media file, **_speaker_name_** is
the full name of the speaker, **_email_** is the e-mail of the speaker, and
**_gender_** is the gender of the speaker (*M* for Male or *F* for Female).
**_email_** and **_gender_** are optional.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
spk = {}
spk['speaker_id'] = speaker_id
spk['speaker_name'] = speaker_name
if gender != None: spk['speaker_gender'] = gender
if email != None: spk['speaker_email'] = email
try:
self.manifest['metadata']['speakers'].append(spk)
except:
self.manifest['metadata']['speakers'] = [spk]
def manifest_set_main_media_file(self, uri, slides=False):
"""Set main media file in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** can be a media file path o a media URL.
If the **_slides_** flat is set to true, video is treated also as a
slides file to improve the transcription quality.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['media'] = {}
if self._is_url(uri):
self.manifest['media']['url'] = uri
else:
self.manifest['media']['fileformat'] = self._get_file_format(uri)
self.manifest['media']['md5'] = self._md5sum(uri)
self.manifest['media']['filename'] = "%s.%s" % (self.manifest['media']['md5'], self.manifest['media']['fileformat'])
#self.manifest['media']['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, self.manifest['media']['filename']))
self.requires_package = True
self.manifest['media']['slides'] = slides
def manifest_add_attachment(self, uri, file_type_code, language=None, human=None):
"""Add attachment file to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** is the attachment file path, and **_file_type_code_** must be one of
the following values: `libtlp.TLPSpeechClient.FTYPE_CODE_MEDIA`,
`libtlp.TLPSpeechClient.FTYPE_CODE_SLIDES`, `libtlp.TLPSpeechClient.FTYPE_CODE_DOCUMENT`,
`libtlp.TLPSpeechClient.FTYPE_CODE_THUMBNAIL`, `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`,
`libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`,
`libtlp.TLPSpeechClient.FTYPE_CODE_WAVEFORM`, `libtlp.TLPSpeechClient.FTYPE_CODE_NONTIMED_TRANSCRIPT`.
In case **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`
or **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`, **_language_** and **_human_**
arguments are mandatory. The first one is the requested subtitles language
code in ISO 639-1 format (e.g. "en", "es"), while **_human_** is a boolean
variable indicationg whether the provided subtitles or audiotrack have been
produced by a human, or have been generated automatically by a computer.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
at = {}
at['fileformat'] = self._get_file_format(uri)
at['md5'] = self._md5sum(uri)
#at['filename'] = self._get_file_name(uri)
at['filename'] = "%s.%s" % (at['md5'], at['fileformat'])
at['type_code'] = file_type_code
if language != None: at['language'] = language
if human != None: at['human'] = human
try:
self.manifest['attachments'].append(at)
except:
self.manifest['attachments'] = [at]
self._manifest_files.append((uri, at['filename']))
self.requires_package = True
def manifest_add_subtitles_request(self, language, system_id=None, lm_adapt=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, **_lm_adapt_** is a boolean variable to enable or disable the
Language Model Adaptation technique, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
if lm_adapt != None: d['lma'] = lm_adapt
self.manifest['requested_langs'][language]['sub'] = d
def manifest_add_audiotrack_request(self, language, system_id=None):
"""Request audiotrack language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested audiotrack language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language]['tts'] = d
def manifest_set_options(self, generate=True, regenerate=None, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
transcriptions, translations and/or synthesized audiotracks. Must be a list of
keywords. Allowed Keywords are: *tx* (request regeneration of the media
transcription), *tl* (request regeneration of media translations), *tts*
(request regeneration of synthesized audiotracks). Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised subtitles.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty subtitles file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def manifest_add_callback_function(self, url, params=None):
"""Add a HTTP REST callback function into the `libtlp.TLPSpeechClient.manifest` JSON object, to
receive notifications about relevant upload status updates
**_url_** is the URL of a HTTP POST function that will receive notifications.
**_params_** is an optional dictionary that provides predefined parameter names and values that
will be added to the POST call (typically, authentication parameters). E.g. params={"auth_token":"deQkw3"}.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['callback'] = {}
self.manifest['callback']["url"] = url
if params != None:
if not(isinstance(params, dict)):
raise TLPException("'params' parameter should be a python dictionary.")
self.manifest['callback']['params'] = params
def api_get(self, oid, lang, form=None, seldata=None, segfilt=None, session_id=None, pending_revs=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
The **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible formats are: *dfxp* (default), *srt*, *ttml*, *vtt*, *text*, *json*, *ibmjson*, *stl*, *docx*.
**_seldata_** and **_segfilt_** are also optional parameters
corresponding to the *sel_data_policy* and *seg_filt_policy* API call
parameters.
On the one hand, **_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPSpeechClient.SUBS_SELDATA_ALL`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_FORMER`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_CURRENT`*.
On the other hand, **_segfilt_** specifies the segment text filtering
policy. Possible values are: *`libtlp.TLPSpeechClient.SUBS_SEGFILT_EMTPY`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_DISABLE`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_ENABLE`*.
If **_session_id_** is provided, will return the result of
applying to the original subtitle file all confirmed subtitle modifications upon
the given session ID.
If **_pending_revs_** is provided, will return the current subtitle file applying those revisions
that are still pending to be reviewed. Must be a boolean.
For further details of both API call parameters please check the full TLP API documentation.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
Dformats = { 'dfxp':0, 'ttml':1, 'srt':2, 'vtt':3, 'text':4, 'json':5, 'ibmjson':6, 'stl':7, 'docx':8 }
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None: self.parameters['format'] = Dformats[form]
if seldata != None: self.parameters['sel_data_policy'] = seldata
if segfilt != None: self.parameters['seg_filt_policy'] = segfilt
if session_id != None: self.parameters['session_id'] = session_id
if pending_revs != None:
if pending_revs:
self.parameters['pending_revs'] = 1
else:
self.parameters['pending_revs'] = 0
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_getmod(self, oid, session_id, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /getmod interface:
> *Get subtitle modifications in JSON format of a given media and session ID.*
The **_oid_** parameter is the Media ID, and **_session_id_** is the session ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("getmod")
def api_audiotrack(self, oid, lang, aid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /audiotrack interface:
> *Download an audiotrack file for a given media ID and language.*
The **_oid_** parameter is the Media ID, **_lang_** is the
language code (ISO 639-1) of the requested audiotrack language, and
**_aid_** is the audiotrack ID (retrieved from the /metadata interface).
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
self.parameters['aid'] = aid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("audiotrack")
def api_mod(self, oid, lang, author_id, author_conf, txt_array, del_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
By default, the session ID will be the one returned after calling the
`libtlp.TLPSpeechClient.start_session` interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "b":, "e":, "t":}
**sI** is the segment ID, **b** is the segment start time, **e** is the segment end time, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
**_del_array_** is a list containing the segment IDs (int values) to delete. It must be an empty list if no segments are being deleted.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[], 'del':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if del_array != None: self.parameters['mods'][lang]['del'] = del_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def api_active_sessions(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /speech/active_sessions interface:
> *Returns a list of active edit sessions involving a given media ID..*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("active_sessions")
def generate_player_url(self, oid, author_id, author_conf, session_id=None, req_key_lifetime=1440, language=None, author_name=None, start=None, options=None):
""" Returns a valid TLP Player URL.
**_oid_** is the Media ID, **_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
It is possible to open the TLP player in read-only (RO) mode: just
set **_author_id_** parameter to `None`.
Optionally, a **_language_** ISO-639-1 code can be provided to make
the Player load directly the specified subtitles language (if not provided, the
Player will load the source language transcriptions). Also, you can set the
media start time in seconds with the **_start_** parameter.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
You can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
**_options_** is an optional dict with valid Player options, to be
passed as `params` via GET. E.g. `{"mode":"transcriptor",
"autosave":5}`.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if language != None: self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
if options != None:
if not(isinstance(options, dict)):
raise TLPException("options parameter must be a python dict.")
params_parameter = base64.b64encode(json.dumps(options, encoding='UTF-8'))
url = "%s¶ms=%s" % (url, params_parameter)
if start != None:
url += "&t=%d" % int(start)
return url
Ancestors (in MRO)
Class variables
var DEL_MODE_HARD
Hard delete mode for the /ingest/delete interface
var DEL_MODE_SOFT
Soft delete mode for the /ingest/delete interface
var FTYPE_CODE_AUDIOTRACK
Audiotrack file type code
var FTYPE_CODE_DOCUMENT
Related Text Document file type code
var FTYPE_CODE_MEDIA
Main Media file type code
var FTYPE_CODE_NONTIMED_TRANSCRIPT
Non-timed transcript file type code
var FTYPE_CODE_SLIDES
Slides file type code code
var FTYPE_CODE_SUBS
Subtitles file type code
var FTYPE_CODE_THUMBNAIL
Media thumbnail file type code
var FTYPE_CODE_WAVEFORM
Waveform file type code
var SUBS_SEGFILT_DISABLE
Segment text filtering policy: Filtering disabled.
var SUBS_SEGFILT_EMTPY
Segment text filtering policy: Empty all segments (removes text from all segments).
var SUBS_SEGFILT_ENABLE
Segment text filtering policy: Filters out special annotations.
var SUBS_SELDATA_ALL
Subtitle contents to be returned: Return both former and current contents (only for DFXP format).
var SUBS_SELDATA_CURRENT
Subtitle contents to be returned: Return current contents (current status of supervision of the subtitles).
var SUBS_SELDATA_FORMER
Subtitle contents to be returned: Return former contents (automatic transcription or translation).
Instance variables
Methods
def __init__(
self, api_base_url, player_base_url, api_user, api_secret_key)
Inheritance:
TLPStandardClient.__init__
Creates a TLPSpeechClient class instance. Parameters:
- api_base_url: Base URL to the transLectures-UPV Platform's Web Service.
- player_base_url: Base URL to the transLectures-UPV Platform's Player.
- api_user: API username / TLP username.
- api_secret_key: API Secret Key.
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key):
"""
Creates a TLPSpeechClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_player_base_url_**: Base URL to the transLectures-UPV Platform's Player.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, TLPClient.API_SPEECH)
def api_accept(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_accept
Performs an API call to the /accept interface:
Accept modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be accepted by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_accept(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /accept interface:
> *Accept modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be accepted by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("accept")
def api_active_sessions(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /speech/active_sessions interface:
Returns a list of active edit sessions involving a given media ID..
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_active_sessions(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /speech/active_sessions interface:
> *Returns a list of active edit sessions involving a given media ID..*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("active_sessions")
def api_audiotrack(
self, oid, lang, aid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /audiotrack interface:
Download an audiotrack file for a given media ID and language.
The oid parameter is the Media ID, lang is the language code (ISO 639-1) of the requested audiotrack language, and aid is the audiotrack ID (retrieved from the /metadata interface).
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_audiotrack(self, oid, lang, aid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /audiotrack interface:
> *Download an audiotrack file for a given media ID and language.*
The **_oid_** parameter is the Media ID, **_lang_** is the
language code (ISO 639-1) of the requested audiotrack language, and
**_aid_** is the audiotrack ID (retrieved from the /metadata interface).
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
self.parameters['aid'] = aid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("audiotrack")
def api_edit_history(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_edit_history
Performs an API call to the /edit_history interface:
Returns a list of all edit sessions carried out over an specific Media ID.
The oid parameter is the Media ID. Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_edit_history(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /edit_history interface:
> *Returns a list of all edit sessions carried out over an specific Media ID.*
he **_oid_** parameter is the Media ID. Optionally, a media hash
value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("edit_history")
def api_end_session(
self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_end_session
Performs an API call to the /end_session interface:
Ends an existing edition session.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
force option should set to True to force the end of a session when the given author_id or API user are not the same that started the given _session_id.
The regenerate option tells to the TLP Server if subtitles and/or synthesized audiotracks will be regenerated after ending the session. By default it is set to True.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_end_session(self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /end_session interface:
> *Ends an existing edition session.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
*_force_** option should set to *True* to force the end of a session when
the given **_author_id_** or API user are not the same that started the given
**_session_id**.
The **_regenerate_** option tells to the TLP Server if subtitles and/or synthesized audiotracks will be
regenerated after ending the session. By default it is set to *True*.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['force'] = int(force)
self.parameters['regenerate'] = int(regenerate)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("end_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = None
def api_get(
self, oid, lang, form=None, seldata=None, segfilt=None, session_id=None, pending_revs=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /get interface:
Download current subtitles file for a given media ID and language.
The oid parameter is the Media ID, and lang is the language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional vhash parameter.
The format optional parameter sets the downloaded subtitles format. Possible formats are: dfxp (default), srt, ttml, vtt, text, json, ibmjson, stl, docx.
seldata and segfilt are also optional parameters corresponding to the sel_data_policy and seg_filt_policy API call parameters.
On the one hand, seldata defines which subtitle contents are returned. Possible
values are: SUBS_SELDATA_ALL,
SUBS_SELDATA_FORMER,
SUBS_SELDATA_CURRENT.
On the other hand, segfilt specifies the segment text filtering
policy. Possible values are: SUBS_SEGFILT_EMTPY,
SUBS_SEGFILT_DISABLE,
SUBS_SEGFILT_ENABLE.
If session_id is provided, will return the result of applying to the original subtitle file all confirmed subtitle modifications upon the given session ID.
If pending_revs is provided, will return the current subtitle file applying those revisions that are still pending to be reviewed. Must be a boolean.
For further details of both API call parameters please check the full TLP API documentation.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_get(self, oid, lang, form=None, seldata=None, segfilt=None, session_id=None, pending_revs=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
he **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible formats are: *dfxp* (default), *srt*, *ttml*, *vtt*, *text*, *json*, *ibmjson*, *stl*, *docx*.
*_seldata_** and **_segfilt_** are also optional parameters
corresponding to the *sel_data_policy* and *seg_filt_policy* API call
parameters.
n the one hand, **_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPSpeechClient.SUBS_SELDATA_ALL`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_FORMER`*,
*`libtlp.TLPSpeechClient.SUBS_SELDATA_CURRENT`*.
n the other hand, **_segfilt_** specifies the segment text filtering
policy. Possible values are: *`libtlp.TLPSpeechClient.SUBS_SEGFILT_EMTPY`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_DISABLE`*,
*`libtlp.TLPSpeechClient.SUBS_SEGFILT_ENABLE`*.
f **_session_id_** is provided, will return the result of
applying to the original subtitle file all confirmed subtitle modifications upon
the given session ID.
If **_pending_revs_** is provided, will return the current subtitle file applying those revisions
that are still pending to be reviewed. Must be a boolean.
For further details of both API call parameters please check the full TLP API documentation.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
Dformats = { 'dfxp':0, 'ttml':1, 'srt':2, 'vtt':3, 'text':4, 'json':5, 'ibmjson':6, 'stl':7, 'docx':8 }
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None: self.parameters['format'] = Dformats[form]
if seldata != None: self.parameters['sel_data_policy'] = seldata
if segfilt != None: self.parameters['seg_filt_policy'] = segfilt
if session_id != None: self.parameters['session_id'] = session_id
if pending_revs != None:
if pending_revs:
self.parameters['pending_revs'] = 1
else:
self.parameters['pending_revs'] = 0
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_getmod(
self, oid, session_id, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /getmod interface:
Get subtitle modifications in JSON format of a given media and session ID.
The oid parameter is the Media ID, and session_id is the session ID. Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_getmod(self, oid, session_id, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /getmod interface:
> *Get subtitle modifications in JSON format of a given media and session ID.*
he **_oid_** parameter is the Media ID, and **_session_id_** is the session ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("getmod")
def api_ingest_cancel(
self, oid, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_cancel
Performs an API call to the /ingest/cancel interface:
- Cancel upload operation. *
oid must be an upload ID.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_cancel(self, oid, debug_mode=False, su=None):
""" Performs an API call to the /ingest/cancel interface:
* Cancel upload operation. *
**_oid_** must be an upload ID.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/cancel')
self._last_api_call = "ingest"
def api_ingest_delete(
self, oid, mode=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_delete
Performs an API call to the /ingest/delete interface:
Delete a media object in the TLP Server.
oid must be a media ID.
Optionally, _mode__ provides the deletion mode.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_delete(self, oid, mode=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/delete interface:
*Delete a media object in the TLP Server.*
**_oid_** must be a media ID.
Optionally, **_mode__** provides the deletion mode.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if mode != None:
if mode not in ['hard', 'soft']:
raise TLPException("Delete mode must be 'hard' or 'soft'")
self.parameters['mode'] = mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/delete')
def api_ingest_new(
self, media_package_file=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_new
Performs an API call to the /ingest/new interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_new(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/new interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/new', mp_fp)
self._last_api_call = "ingest"
def api_ingest_update(
self, media_package_file=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_update
Performs an API call to the /ingest/update interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_update(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/update interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/update', mp_fp)
self._last_api_call = "ingest"
def api_langs(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_langs
Performs an API call to the /langs interface:
Get a list of all subtitle and audiotrack languages available for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_langs(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /langs interface:
> *Get a list of all subtitle and audiotrack languages available for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("langs")
def api_list(
self, su=None)
Inheritance:
TLPStandardClient.api_list
Performs an API call to the /list interface:
Get a list of all existing audios and videos in the TLP Database.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_list(self, su=None):
""" Performs an API call to the /list interface:
*Get a list of all existing audios and videos in the TLP Database.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("list")
def api_lock(
self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_lock
Performs an API call to the /lock interface:
Allow/disallow regular users to send subtitles modifications for an specific Media ID.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_lock(self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /lock interface:
> *Allow/disallow regular users to send subtitles modifications for an specific Media ID.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(lock, bool)):
raise TLPException("lock must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['lock'] = int(lock)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("lock")
def api_mark_revised(
self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_mark_revised
Performs an API call to the /mark_revised interface:
Mark/unmark an edition session as revised.
session_id is the Session ID to mark/unmark as revised, the oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_mark_revised(self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /mark_revised interface:
> *Mark/unmark an edition session as revised.*
*_session_id_** is the Session ID to mark/unmark as revised,
the **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(unmark, bool)):
raise TLPException("unmark must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['unmark'] = int(unmark)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mark_revised")
def api_metadata(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_metadata
Performs an API call to the /metadata interface:
Get metadata and media file locations for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_metadata(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /metadata interface:
> *Get metadata and media file locations for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("metadata")
def api_mod(
self, oid, lang, author_id, author_conf, txt_array, del_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None)
Performs an API call to the /mod interface:
Send and commit subtitle corrections made by a user under an edit session ID.
By default, the session ID will be the one returned after calling the
libtlp.TLPSpeechClient.start_session interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, lang is the language code (ISO 639-1) of the edited subtitles language, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
txt_array is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":<int>, "b":<float>, "e":<float>, "t":<str>}
sI is the segment ID, b is the segment start time, e is the segment end time, and t is the updated segment text. txt_array must be an empty list if no segments where modified.
del_array is a list containing the segment IDs (int values) to delete. It must be an empty list if no segments are being deleted.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter value with all required /mod parameters. In this case, all mandatory arguments can be set to None, because they are ignored.
def api_mod(self, oid, lang, author_id, author_conf, txt_array, del_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
y default, the session ID will be the one returned after calling the
`libtlp.TLPSpeechClient.start_session` interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
he **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "b":, "e":, "t":}
**sI** is the segment ID, **b** is the segment start time, **e** is the segment end time, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
**_del_array_** is a list containing the segment IDs (int values) to delete. It must be an empty list if no segments are being deleted.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
lternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[], 'del':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if del_array != None: self.parameters['mods'][lang]['del'] = del_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def api_reject(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_reject
Performs an API call to the /reject interface:
Reject modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be rejected by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_reject(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /reject interface:
> *Reject modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be rejected by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("reject")
def api_revisions(
self, su=None)
Inheritance:
TLPStandardClient.api_revisions
Performs an API call to the /revisions interface:
Returns a list of all edit sessions for all API user's media files that are pending to be revised.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_revisions(self, su=None):
""" Performs an API call to the /revisions interface:
> *Returns a list of all edit sessions for all API user's media files that are pending to be revised.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("revisions")
def api_session_status(
self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_session_status
Performs an API call to the /session_status interface:
Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_session_status(self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /session_status interface:
> *Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to check session status (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['alive'] = int(alive)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("session_status")
def api_start_session(
self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_start_session
Performs an API call to the /start_session interface:
Starts an edition session to send and commit modifications of a subtitles file.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_start_session(self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /start_session interface:
> *Starts an edition session to send and commit modifications of a subtitles file.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("start_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = self.ret_data['session_id']
def api_status(
self, oid, su=None)
Inheritance:
TLPStandardClient.api_status
Performs an API call to the /status interface:
Check the current status of a specific upload ID.
oid is an upload ID, returned by the /ingest interface.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_status(self, oid, su=None):
""" Performs an API call to the /status interface:
> *Check the current status of a specific upload ID.*
**_oid_** is an upload ID, returned by the /ingest interface.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("status")
def api_systems(
self, su=None)
Inheritance:
TLPStandardClient.api_systems
Performs an API call to the /systems interface:
Get a list of all available Speech Recognition, Machine Translation, and Text-To-Speech Systems that can be applied to transcribe, translate, and synthesize a media file.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
*Get a list of all available Speech Recognition, Machine
Translation, and Text-To-Speech Systems that can be applied to
transcribe, translate, and synthesize a media file.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
def api_uploadslist(
self, object_id=None, su=None)
Inheritance:
TLPStandardClient.api_uploadslist
Performs an API call to the /uploadslist interface:
Get a list of all user's uploads.
If the optional object_id argument is given, then the Web Service will return a list of uploads involving the provided object ID (could be an Upload ID or a Media ID).
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_uploadslist(self, object_id=None, su=None):
""" Performs an API call to the /uploadslist interface:
> *Get a list of all user's uploads.*
f the optional **_object_id_** argument is given, then the Web
Service will return a list of uploads involving the provided object ID (could
be an Upload ID or a Media ID).
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if object_id != None: self.parameters['object_id'] = object_id
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("uploadslist")
def create_media_package(
self, dest=None)
Inheritance:
TLPStandardClient.create_media_package
Creates a Media Package File from the manifest JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a temporal directory, unless you specify the destination file path with the optional parameter dest.
def create_media_package(self, dest=None):
"""Creates a Media Package File from the `libtlp.TLPStandardClient.manifest` JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a
temporal directory, unless you specify the destination file path with the
optional parameter **_dest_**.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self._tmp_dir = tempfile.mkdtemp()
if dest == None:
dest = "%s/mpf.zip" % self._tmp_dir
zf = zipfile.ZipFile(dest, mode='w', allowZip64=True)
for f in self._manifest_files:
zf.write(f[0], arcname=f[1])
zf.close()
return dest
def disable_http_auth(
self)
Inheritance:
TLPStandardClient.disable_http_auth
Disable HTTP Authentication for all API calls
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def enable_http_auth(
self, http_user, http_pass)
Inheritance:
TLPStandardClient.enable_http_auth
Use HTTP Authentication for all API calls.
http_user is the HTTP Authentication username, while http_pass is the corresponding user password.
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def gen_request_key(
self, oid, expire, author=None, author_conf=None)
Inheritance:
TLPStandardClient.gen_request_key
Returns a valid request key to be used as an API authentication token.
oid is the object ID that will be queried (id API call parameter), and expire is the UNIX timestamp of the expiration time of the key. With these two parameters is generated the basic request key.
If author (author_id API parameter) is supplied, then the full request key is generated using this parameter plus author_conf (author_conf API parameter).
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def generate_player_url(
self, oid, author_id, author_conf, session_id=None, req_key_lifetime=1440, language=None, author_name=None, start=None, options=None)
Returns a valid TLP Player URL.
oid is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
It is possible to open the TLP player in read-only (RO) mode: just
set author_id parameter to None.
Optionally, a language ISO-639-1 code can be provided to make the Player load directly the specified subtitles language (if not provided, the Player will load the source language transcriptions). Also, you can set the media start time in seconds with the start parameter.
The full name of the user that will edit the subtitles can be provided with the parameter _author_name.
A session_id argument can be provided in order review subtitle modifications made under the provided edit session ID.
You can adjust de lifetime duration in minutes of the generated URL using the option req_key_lifetime. By default is set to 24 hours (1440 minutes).
options is an optional dict with valid Player options, to be
passed as params via GET. E.g. {"mode":"transcriptor",
"autosave":5}.
def generate_player_url(self, oid, author_id, author_conf, session_id=None, req_key_lifetime=1440, language=None, author_name=None, start=None, options=None):
""" Returns a valid TLP Player URL.
*_oid_** is the Media ID, **_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
It is possible to open the TLP player in read-only (RO) mode: just
set **_author_id_** parameter to `None`.
ptionally, a **_language_** ISO-639-1 code can be provided to make
the Player load directly the specified subtitles language (if not provided, the
Player will load the source language transcriptions). Also, you can set the
media start time in seconds with the **_start_** parameter.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
ou can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
**_options_** is an optional dict with valid Player options, to be
passed as `params` via GET. E.g. `{"mode":"transcriptor",
"autosave":5}`.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if language != None: self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
if options != None:
if not(isinstance(options, dict)):
raise TLPException("options parameter must be a python dict.")
params_parameter = base64.b64encode(json.dumps(options, encoding='UTF-8'))
url = "%s¶ms=%s" % (url, params_parameter)
if start != None:
url += "&t=%d" % int(start)
return url
def get_printable_manifest(
self)
Inheritance:
TLPStandardClient.get_printable_manifest
Returns a printable, user friendly version of the manifest JSON object (stored in the libtlp.TLPClient.manifest class member).
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def get_printable_response_data(
self)
Inheritance:
TLPStandardClient.get_printable_response_data
Returns a printable, user friendly version of the response data from the
last API call (stored in the ret_data class member).
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def manifest_add_attachment(
self, uri, file_type_code, language=None, human=None)
Add attachment file to the manifest JSON object.
uri is the attachment file path, and file_type_code must be one of
the following values: FTYPE_CODE_MEDIA,
FTYPE_CODE_SLIDES, FTYPE_CODE_DOCUMENT,
FTYPE_CODE_THUMBNAIL, FTYPE_CODE_SUBS,
FTYPE_CODE_AUDIOTRACK,
FTYPE_CODE_WAVEFORM, FTYPE_CODE_NONTIMED_TRANSCRIPT.
In case file_type_code = FTYPE_CODE_SUBS
or file_type_code = FTYPE_CODE_AUDIOTRACK, language and human
arguments are mandatory. The first one is the requested subtitles language
code in ISO 639-1 format (e.g. "en", "es"), while human is a boolean
variable indicationg whether the provided subtitles or audiotrack have been
produced by a human, or have been generated automatically by a computer.
Note: The manifest object should have been
initialised before with a libtlp.TLPClient.manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_add_attachment(self, uri, file_type_code, language=None, human=None):
"""Add attachment file to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** is the attachment file path, and **_file_type_code_** must be one of
the following values: `libtlp.TLPSpeechClient.FTYPE_CODE_MEDIA`,
`libtlp.TLPSpeechClient.FTYPE_CODE_SLIDES`, `libtlp.TLPSpeechClient.FTYPE_CODE_DOCUMENT`,
`libtlp.TLPSpeechClient.FTYPE_CODE_THUMBNAIL`, `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`,
`libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`,
`libtlp.TLPSpeechClient.FTYPE_CODE_WAVEFORM`, `libtlp.TLPSpeechClient.FTYPE_CODE_NONTIMED_TRANSCRIPT`.
In case **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_SUBS`
or **_file_type_code_** = `libtlp.TLPSpeechClient.FTYPE_CODE_AUDIOTRACK`, **_language_** and **_human_**
arguments are mandatory. The first one is the requested subtitles language
code in ISO 639-1 format (e.g. "en", "es"), while **_human_** is a boolean
variable indicationg whether the provided subtitles or audiotrack have been
produced by a human, or have been generated automatically by a computer.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
at = {}
at['fileformat'] = self._get_file_format(uri)
at['md5'] = self._md5sum(uri)
#at['filename'] = self._get_file_name(uri)
at['filename'] = "%s.%s" % (at['md5'], at['fileformat'])
at['type_code'] = file_type_code
if language != None: at['language'] = language
if human != None: at['human'] = human
try:
self.manifest['attachments'].append(at)
except:
self.manifest['attachments'] = [at]
self._manifest_files.append((uri, at['filename']))
self.requires_package = True
def manifest_add_audiotrack_request(
self, language, system_id=None)
Request audiotrack language in the "requested_langs" option of the manifest JSON object.
language is the requested audiotrack language code in ISO 639-1 format (e.g. "en", "es").
Some advanced options can be provided to the Ingest Service for subtitles generation. system_id must be an integer value indicating the System ID to use.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_add_audiotrack_request(self, language, system_id=None):
"""Request audiotrack language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested audiotrack language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language]['tts'] = d
def manifest_add_callback_function(
self, url, params=None)
Add a HTTP REST callback function into the manifest JSON object, to
receive notifications about relevant upload status updates
url is the URL of a HTTP POST function that will receive notifications.
params is an optional dictionary that provides predefined parameter names and values that will be added to the POST call (typically, authentication parameters). E.g. params={"auth_token":"deQkw3"}.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_add_callback_function(self, url, params=None):
"""Add a HTTP REST callback function into the `libtlp.TLPSpeechClient.manifest` JSON object, to
receive notifications about relevant upload status updates
**_url_** is the URL of a HTTP POST function that will receive notifications.
**_params_** is an optional dictionary that provides predefined parameter names and values that
will be added to the POST call (typically, authentication parameters). E.g. params={"auth_token":"deQkw3"}.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['callback'] = {}
self.manifest['callback']["url"] = url
if params != None:
if not(isinstance(params, dict)):
raise TLPException("'params' parameter should be a python dictionary.")
self.manifest['callback']['params'] = params
def manifest_add_speaker(
self, speaker_id, speaker_name, email=None, gender=None)
Add a speaker in the metadata section of the manifest JSON object.
speaker_id is the speaker ID of the media file, speaker_name is the full name of the speaker, email is the e-mail of the speaker, and gender is the gender of the speaker (M for Male or F for Female). email and gender are optional.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_add_speaker(self, speaker_id, speaker_name, email=None, gender=None):
"""Add a speaker in the metadata section of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_speaker_id_** is the speaker ID of the media file, **_speaker_name_** is
the full name of the speaker, **_email_** is the e-mail of the speaker, and
**_gender_** is the gender of the speaker (*M* for Male or *F* for Female).
**_email_** and **_gender_** are optional.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
spk = {}
spk['speaker_id'] = speaker_id
spk['speaker_name'] = speaker_name
if gender != None: spk['speaker_gender'] = gender
if email != None: spk['speaker_email'] = email
try:
self.manifest['metadata']['speakers'].append(spk)
except:
self.manifest['metadata']['speakers'] = [spk]
def manifest_add_subtitles_request(
self, language, system_id=None, lm_adapt=None, tl_path=None)
Request subtitles language in the "requested_langs" option of the manifest JSON object.
language is the requested subtitles language code in ISO 639-1 format (e.g. "en", "es").
Some advanced options can be provided to the Ingest Service for subtitles generation. system_id must be an integer value indicating the System ID to use, lm_adapt is a boolean variable to enable or disable the Language Model Adaptation technique, and tl_path must be a list of tuples (language, system_id) describing an alternative translation path. In this latter case, system_id is optional and must be set to None if is not provided.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_add_subtitles_request(self, language, system_id=None, lm_adapt=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, **_lm_adapt_** is a boolean variable to enable or disable the
Language Model Adaptation technique, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
if lm_adapt != None: d['lma'] = lm_adapt
self.manifest['requested_langs'][language]['sub'] = d
def manifest_init(
self, external_id)
Initalize the manifest JSON object.
external_id must be a Media ID or an existing upload ID.
Note: This method should be executed before calling the libtlp.TLPSpeechClient.api_ingest method and any manifest_* class methods.
def manifest_init(self, external_id):
"""Initalize the `libtlp.TLPSpeechClient.manifest` JSON object.
**_external_id_** must be a Media ID or an existing upload ID.
**Note:** This method should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['metadata'] = {}
self.manifest['metadata']['external_id'] = external_id
def manifest_set_main_media_file(
self, uri, slides=False)
Set main media file in the manifest JSON object.
uri can be a media file path o a media URL.
If the slides flat is set to true, video is treated also as a slides file to improve the transcription quality.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_set_main_media_file(self, uri, slides=False):
"""Set main media file in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_uri_** can be a media file path o a media URL.
If the **_slides_** flat is set to true, video is treated also as a
slides file to improve the transcription quality.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['media'] = {}
if self._is_url(uri):
self.manifest['media']['url'] = uri
else:
self.manifest['media']['fileformat'] = self._get_file_format(uri)
self.manifest['media']['md5'] = self._md5sum(uri)
self.manifest['media']['filename'] = "%s.%s" % (self.manifest['media']['md5'], self.manifest['media']['fileformat'])
#self.manifest['media']['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, self.manifest['media']['filename']))
self.requires_package = True
self.manifest['media']['slides'] = slides
def manifest_set_metadata(
self, language=None, title=None, topic=None, keywords=None, date=None)
Set metadata in the manifest JSON object.
language is the Media language code in ISO 639-1 format (e.g. "en", "es"), title is the title of the media, topic is the topic of the media, keywords are the media keywords, and date is the publication date of the media.
All arguments are optional, but language and title arguments are mandatory for "New" operations.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_set_metadata(self, language=None, title=None, topic=None, keywords=None, date=None):
"""Set metadata in the `libtlp.TLPSpeechClient.manifest` JSON object.
**_language_** is the Media language code in ISO 639-1 format (e.g.
"en", "es"), **_title_** is the title of the media, **_topic_** is the topic of
the media, **_keywords_** are the media keywords, and **_date_** is the
publication date of the media.
All arguments are optional, but **_language_** and **_title_**
arguments are mandatory for "New" operations.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if language != None:
self.manifest['metadata']['language'] = language
if title != None:
self.manifest['metadata']['title'] = title
if topic != None:
self.manifest['metadata']['topic'] = topic
if keywords != None:
self.manifest['metadata']['keywords'] = keywords
if date != None:
self.manifest['metadata']['date'] = date
def manifest_set_options(
self, generate=True, regenerate=None, force=False, test_mode=False, email=None)
Set Ingest Service options to the manifest JSON object.
generate is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, regenerate option can be used to request a regeneration of transcriptions, translations and/or synthesized audiotracks. Must be a list of keywords. Allowed Keywords are: tx (request regeneration of the media transcription), tl (request regeneration of media translations), tts (request regeneration of synthesized audiotracks). Also, if force = True, regeneration of automatic subtitles is forced even if there exist human-supervised subtitles.
Finally, the test_mode argument is a boolean variable to enable/disable the Test Mode of the Ingest Service. When enabled, the uploaded media will be available inmediately with an empty subtitles file. This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPSpeechClient.api_ingest method.
def manifest_set_options(self, generate=True, regenerate=None, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPSpeechClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
transcriptions, translations and/or synthesized audiotracks. Must be a list of
keywords. Allowed Keywords are: *tx* (request regeneration of the media
transcription), *tl* (request regeneration of media translations), *tts*
(request regeneration of synthesized audiotracks). Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised subtitles.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty subtitles file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPSpeechClient.manifest` object should have been
initialised before with a `libtlp.TLPSpeechClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPSpeechClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def save_response_data(
self, dest)
Inheritance:
TLPStandardClient.save_response_data
Saves the response data from the last API call (stored in the ret_data
class member) into the destination dest file.
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
class TLPStandardClient
class TLPStandardClient(TLPClient):
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type):
"""
Creates a `TLPStandardClient` class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._api_mod_session_id = None
"""Tells wether the /ingest API call requires to upload a media package"""
self._manifest_files = None
self.requires_package = False
self.manifest = None
"""Manifest JSON object."""
TLPClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type)
def create_media_package(self, dest=None):
"""Creates a Media Package File from the `libtlp.TLPStandardClient.manifest` JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a
temporal directory, unless you specify the destination file path with the
optional parameter **_dest_**.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self._tmp_dir = tempfile.mkdtemp()
if dest == None:
dest = "%s/mpf.zip" % self._tmp_dir
zf = zipfile.ZipFile(dest, mode='w', allowZip64=True)
for f in self._manifest_files:
zf.write(f[0], arcname=f[1])
zf.close()
return dest
def api_ingest_new(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/new interface:
> *Upload media (audio/video) files and many other attachments and
> metadata to the TLP Server for automatic multilingual subtitling
> and speech synthesization.*
If **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/new', mp_fp)
self._last_api_call = "ingest"
def api_ingest_update(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/update interface:
> *Upload media (audio/video) files and many other attachments and
> metadata to the TLP Server for automatic multilingual subtitling
> and speech synthesization.*
If **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/update', mp_fp)
self._last_api_call = "ingest"
def api_ingest_delete(self, oid, mode=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/delete interface:
> *Delete a media object in the TLP Server.*
**_oid_** must be a media ID.
Optionally, **_mode__** provides the deletion mode.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if mode != None:
if mode not in ['hard', 'soft']:
raise TLPException("Delete mode must be 'hard' or 'soft'")
self.parameters['mode'] = mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/delete')
def api_ingest_cancel(self, oid, debug_mode=False, su=None):
""" Performs an API call to the /ingest/cancel interface:
> * Cancel upload operation. *
**_oid_** must be an upload ID.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/cancel')
self._last_api_call = "ingest"
def api_uploadslist(self, object_id=None, su=None):
""" Performs an API call to the /uploadslist interface:
> *Get a list of all user's uploads.*
If the optional **_object_id_** argument is given, then the Web
Service will return a list of uploads involving the provided object ID (could
be an Upload ID or a Media ID).
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if object_id != None: self.parameters['object_id'] = object_id
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("uploadslist")
def api_status(self, oid, su=None):
""" Performs an API call to the /status interface:
> *Check the current status of a specific upload ID.*
**_oid_** is an upload ID, returned by the /ingest interface.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("status")
def api_list(self, su=None):
""" Performs an API call to the /list interface:
> *Get a list of all existing audios and videos in the TLP Database.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("list")
def api_langs(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /langs interface:
> *Get a list of all subtitle and audiotrack languages available for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("langs")
def api_metadata(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /metadata interface:
> *Get metadata and media file locations for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("metadata")
def api_start_session(self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /start_session interface:
> *Starts an edition session to send and commit modifications of a subtitles file.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("start_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = self.ret_data['session_id']
def api_session_status(self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /session_status interface:
> *Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.*
By default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to check session status (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['alive'] = int(alive)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("session_status")
def api_end_session(self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /end_session interface:
> *Ends an existing edition session.*
By default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_force_** option should set to *True* to force the end of a session when
the given **_author_id_** or API user are not the same that started the given
**_session_id**.
The **_regenerate_** option tells to the TLP Server if subtitles and/or synthesized audiotracks will be
regenerated after ending the session. By default it is set to *True*.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['force'] = int(force)
self.parameters['regenerate'] = int(regenerate)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("end_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = None
def api_lock(self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /lock interface:
> *Allow/disallow regular users to send subtitles modifications for an specific Media ID.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(lock, bool)):
raise TLPException("lock must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['lock'] = int(lock)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("lock")
def api_edit_history(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /edit_history interface:
> *Returns a list of all edit sessions carried out over an specific Media ID.*
The **_oid_** parameter is the Media ID. Optionally, a media hash
value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("edit_history")
def api_mark_revised(self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /mark_revised interface:
> *Mark/unmark an edition session as revised.*
**_session_id_** is the Session ID to mark/unmark as revised,
the **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(unmark, bool)):
raise TLPException("unmark must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['unmark'] = int(unmark)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mark_revised")
def api_accept(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /accept interface:
> *Accept modifications of one or more pending edit sessions without having to revise them.*
The **_ids_** parameter must be a list Session IDs whose edits are
meant to be accepted by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("accept")
def api_reject(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /reject interface:
> *Reject modifications of one or more pending edit sessions without having to revise them.*
The **_ids_** parameter must be a list Session IDs whose edits are
meant to be rejected by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("reject")
def api_revisions(self, su=None):
""" Performs an API call to the /revisions interface:
> *Returns a list of all edit sessions for all API user's media files that are pending to be revised.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("revisions")
Ancestors (in MRO)
Class variables
Instance variables
var debug_info
Inheritance:
TLPClient.debug_info
Debug information of the last performed API call / Generation of Player URL.
var manifest
Manifest JSON object.
var requires_package
var ret_content_type
Inheritance:
TLPClient.ret_content_type
Mime-type of the data returned by the last performed API call.
var ret_data
Inheritance:
TLPClient.ret_data
Data returned by the last performed API call. If the response was a JSON object, ret_data becomes a a parsed JSON object (dictionary or list, depending on the JSON).
var use_data_parameter
Inheritance:
TLPClient.use_data_parameter
Use a single "data" parameter on HTTP GET calls instead multiple GET parameters.
Methods
def __init__(
self, api_base_url, player_base_url, api_user, api_secret_key, api_type)
Inheritance:
TLPClient.__init__
Creates a TLPStandardClient class instance. Parameters:
- api_base_url: Base URL to the transLectures-UPV Platform's Web Service.
- editor_base_url: Base URL to the transLectures-UPV Platform's Editor.
- api_user: API username / TLP username.
- api_secret_key: API Secret Key.
- api_type: API type, must be
API_SPEECH,API_TEXTorAPI_WEB.
def __init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type):
"""
Creates a `TLPStandardClient` class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_editor_base_url_**: Base URL to the transLectures-UPV Platform's Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
- **_api_type_**: API type, must be `libtlp.TLPClient.API_SPEECH`, `libtlp.TLPClient.API_TEXT` or `libtlp.TLPClient.API_WEB`.
"""
self._api_mod_session_id = None
"""Tells wether the /ingest API call requires to upload a media package"""
self._manifest_files = None
self.requires_package = False
self.manifest = None
"""Manifest JSON object."""
TLPClient.__init__(self, api_base_url, player_base_url, api_user, api_secret_key, api_type)
def api_accept(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /accept interface:
Accept modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be accepted by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_accept(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /accept interface:
> *Accept modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be accepted by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("accept")
def api_edit_history(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /edit_history interface:
Returns a list of all edit sessions carried out over an specific Media ID.
The oid parameter is the Media ID. Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_edit_history(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /edit_history interface:
> *Returns a list of all edit sessions carried out over an specific Media ID.*
he **_oid_** parameter is the Media ID. Optionally, a media hash
value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("edit_history")
def api_end_session(
self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /end_session interface:
Ends an existing edition session.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
force option should set to True to force the end of a session when the given author_id or API user are not the same that started the given _session_id.
The regenerate option tells to the TLP Server if subtitles and/or synthesized audiotracks will be regenerated after ending the session. By default it is set to True.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_end_session(self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /end_session interface:
> *Ends an existing edition session.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
*_force_** option should set to *True* to force the end of a session when
the given **_author_id_** or API user are not the same that started the given
**_session_id**.
The **_regenerate_** option tells to the TLP Server if subtitles and/or synthesized audiotracks will be
regenerated after ending the session. By default it is set to *True*.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['force'] = int(force)
self.parameters['regenerate'] = int(regenerate)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("end_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = None
def api_ingest_cancel(
self, oid, debug_mode=False, su=None)
Performs an API call to the /ingest/cancel interface:
- Cancel upload operation. *
oid must be an upload ID.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_cancel(self, oid, debug_mode=False, su=None):
""" Performs an API call to the /ingest/cancel interface:
* Cancel upload operation. *
**_oid_** must be an upload ID.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/cancel')
self._last_api_call = "ingest"
def api_ingest_delete(
self, oid, mode=None, debug_mode=False, su=None)
Performs an API call to the /ingest/delete interface:
Delete a media object in the TLP Server.
oid must be a media ID.
Optionally, _mode__ provides the deletion mode.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_delete(self, oid, mode=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/delete interface:
*Delete a media object in the TLP Server.*
**_oid_** must be a media ID.
Optionally, **_mode__** provides the deletion mode.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if mode != None:
if mode not in ['hard', 'soft']:
raise TLPException("Delete mode must be 'hard' or 'soft'")
self.parameters['mode'] = mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/delete')
def api_ingest_new(
self, media_package_file=None, debug_mode=False, su=None)
Performs an API call to the /ingest/new interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_new(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/new interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/new', mp_fp)
self._last_api_call = "ingest"
def api_ingest_update(
self, media_package_file=None, debug_mode=False, su=None)
Performs an API call to the /ingest/update interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_update(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/update interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/update', mp_fp)
self._last_api_call = "ingest"
def api_langs(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /langs interface:
Get a list of all subtitle and audiotrack languages available for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_langs(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /langs interface:
> *Get a list of all subtitle and audiotrack languages available for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("langs")
def api_list(
self, su=None)
Performs an API call to the /list interface:
Get a list of all existing audios and videos in the TLP Database.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_list(self, su=None):
""" Performs an API call to the /list interface:
*Get a list of all existing audios and videos in the TLP Database.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("list")
def api_lock(
self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /lock interface:
Allow/disallow regular users to send subtitles modifications for an specific Media ID.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_lock(self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /lock interface:
> *Allow/disallow regular users to send subtitles modifications for an specific Media ID.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(lock, bool)):
raise TLPException("lock must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['lock'] = int(lock)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("lock")
def api_mark_revised(
self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /mark_revised interface:
Mark/unmark an edition session as revised.
session_id is the Session ID to mark/unmark as revised, the oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_mark_revised(self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /mark_revised interface:
> *Mark/unmark an edition session as revised.*
*_session_id_** is the Session ID to mark/unmark as revised,
the **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(unmark, bool)):
raise TLPException("unmark must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['unmark'] = int(unmark)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mark_revised")
def api_metadata(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /metadata interface:
Get metadata and media file locations for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_metadata(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /metadata interface:
> *Get metadata and media file locations for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("metadata")
def api_reject(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /reject interface:
Reject modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be rejected by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_reject(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /reject interface:
> *Reject modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be rejected by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("reject")
def api_revisions(
self, su=None)
Performs an API call to the /revisions interface:
Returns a list of all edit sessions for all API user's media files that are pending to be revised.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_revisions(self, su=None):
""" Performs an API call to the /revisions interface:
> *Returns a list of all edit sessions for all API user's media files that are pending to be revised.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("revisions")
def api_session_status(
self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /session_status interface:
Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_session_status(self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /session_status interface:
> *Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to check session status (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['alive'] = int(alive)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("session_status")
def api_start_session(
self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /start_session interface:
Starts an edition session to send and commit modifications of a subtitles file.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_start_session(self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /start_session interface:
> *Starts an edition session to send and commit modifications of a subtitles file.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("start_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = self.ret_data['session_id']
def api_status(
self, oid, su=None)
Performs an API call to the /status interface:
Check the current status of a specific upload ID.
oid is an upload ID, returned by the /ingest interface.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_status(self, oid, su=None):
""" Performs an API call to the /status interface:
> *Check the current status of a specific upload ID.*
**_oid_** is an upload ID, returned by the /ingest interface.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("status")
def api_systems(
self, su=None)
Inheritance:
TLPClient.api_systems
Performs an API call to the /systems interface:
Get a list of all available Speech Recognition, Machine Translation, and Text-To-Speech Systems that can be applied to transcribe, translate, and synthesize a media file.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
*Get a list of all available Speech Recognition, Machine
Translation, and Text-To-Speech Systems that can be applied to
transcribe, translate, and synthesize a media file.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
def api_uploadslist(
self, object_id=None, su=None)
Performs an API call to the /uploadslist interface:
Get a list of all user's uploads.
If the optional object_id argument is given, then the Web Service will return a list of uploads involving the provided object ID (could be an Upload ID or a Media ID).
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_uploadslist(self, object_id=None, su=None):
""" Performs an API call to the /uploadslist interface:
> *Get a list of all user's uploads.*
f the optional **_object_id_** argument is given, then the Web
Service will return a list of uploads involving the provided object ID (could
be an Upload ID or a Media ID).
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if object_id != None: self.parameters['object_id'] = object_id
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("uploadslist")
def create_media_package(
self, dest=None)
Creates a Media Package File from the manifest JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a temporal directory, unless you specify the destination file path with the optional parameter dest.
def create_media_package(self, dest=None):
"""Creates a Media Package File from the `libtlp.TLPStandardClient.manifest` JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a
temporal directory, unless you specify the destination file path with the
optional parameter **_dest_**.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self._tmp_dir = tempfile.mkdtemp()
if dest == None:
dest = "%s/mpf.zip" % self._tmp_dir
zf = zipfile.ZipFile(dest, mode='w', allowZip64=True)
for f in self._manifest_files:
zf.write(f[0], arcname=f[1])
zf.close()
return dest
def disable_http_auth(
self)
Inheritance:
TLPClient.disable_http_auth
Disable HTTP Authentication for all API calls
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def enable_http_auth(
self, http_user, http_pass)
Inheritance:
TLPClient.enable_http_auth
Use HTTP Authentication for all API calls.
http_user is the HTTP Authentication username, while http_pass is the corresponding user password.
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def gen_request_key(
self, oid, expire, author=None, author_conf=None)
Inheritance:
TLPClient.gen_request_key
Returns a valid request key to be used as an API authentication token.
oid is the object ID that will be queried (id API call parameter), and expire is the UNIX timestamp of the expiration time of the key. With these two parameters is generated the basic request key.
If author (author_id API parameter) is supplied, then the full request key is generated using this parameter plus author_conf (author_conf API parameter).
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def get_printable_manifest(
self)
Inheritance:
TLPClient.get_printable_manifest
Returns a printable, user friendly version of the manifest JSON object (stored in the libtlp.TLPClient.manifest class member).
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def get_printable_response_data(
self)
Inheritance:
TLPClient.get_printable_response_data
Returns a printable, user friendly version of the response data from the
last API call (stored in the ret_data class member).
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def save_response_data(
self, dest)
Inheritance:
TLPClient.save_response_data
Saves the response data from the last API call (stored in the ret_data
class member) into the destination dest file.
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
class TLPTextClient
class TLPTextClient(TLPStandardClient):
TRANS_FORMAT_ORIGINAL = 0
"""Translation file in original format"""
TRANS_FORMAT_HTML = 1
"""Translation file in internal HTML format"""
TRANS_FORMAT_DTLX = 2
"""Translation file in internal DTLX format"""
TRANS_FORMAT_TEXT = 3
"""Translation file in text format"""
TRANS_SELDATA_ALL = 0
"""Translation contents to be returned: Return both former and current contents (only for DTLX format). """
TRANS_SELDATA_FORMER = 1
"""Translation contents to be returned: Return former contents (automatic translation). """
TRANS_SELDATA_CURRENT = 2
"""Translation contents to be returned: Return current contents (current status of supervision of the translation). """
DEL_MODE_SOFT = 'soft'
"""Soft delete mode for the /ingest/delete interface"""
DEL_MODE_HARD = 'hard'
"""Hard delete mode for the /ingest/delete interface"""
def __init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPTextClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_translation_editor_base_url_**: Base URL to the transLectures-UPV Platform's Translation Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key, TLPClient.API_TEXT)
def _set_auth_parameters_request_key_translation_editor(self, req_key_lifetime, oid, author=None, author_conf=None):
"""Set API authentication parameters using a request key for generating a Player URL."""
self.parameters['api_user'] = self._api_user
expire = self._gen_expire_parameter(req_key_lifetime)
self.parameters['request_key'] = self.gen_request_key(oid, expire, author, author_conf)
self.parameters['expire'] = expire
def manifest_init(self, language):
"""Initalize the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the documents' language code in ISO 639-1 format (e.g.
"en", "es").
**Note:** This method should be executed before calling the `libtlp.TLPTextClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['documents'] = []
self.manifest['language'] = language
def manifest_add_document(self, external_id, uri=None, title=None, fileformat=None):
"""Set main media file in the `libtlp.TLPTextClient.manifest` JSON object.
**_external_id_** must be a Document ID.
**_uri_** can be a media file path o a media URL.
**_title_** is the title of the media.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
doc = {}
doc['external_id'] = external_id
if title != None:
doc['title'] = title
if uri != None:
if self._is_url(uri):
doc['url'] = uri
else:
if fileformat != None:
doc['fileformat'] = fileformat
else:
doc['fileformat'] = self._get_file_format(uri)
doc['md5'] = self._md5sum(uri)
doc['filename'] = "%s.%s" % (doc['md5'], doc['fileformat'])
#doc['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, doc['filename']))
self.requires_package = True
self.manifest['documents'].append(doc)
def manifest_add_translation_request(self, language, system_id=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language] = d
def manifest_set_options(self, generate=True, regenerate=False, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPTextClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
translations. Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised translations.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty translation file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def api_get(self, oid, lang, form=None, seldata=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
The **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible values are: *`libtlp.TLPTextClient.TRANS_FORMAT_ORIGINAL`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_HTML`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_DTLX`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_TXT`*.
**_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPTextClient.TRANS_SELDATA_ALL`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_FORMER`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_CURRENT`*.
A **_session_id_** argument can be provided in order to apply subtitle modifications made under the given edit session ID to the subtitles file.
For further details of both API call parameters please check the full TLP API documentation.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None:
if form not in (self.TRANS_FORMAT_ORIGINAL, self.TRANS_FORMAT_HTML, self.TRANS_FORMAT_DTLX, self.TRANS_FORMAT_TEXT):
raise TLPException("Unallowed document format.")
self.parameters['format'] = form
if seldata != None: self.parameters['sel_data_policy'] = seldata
if session_id != None: self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_mod(self, oid, lang, author_id, author_conf, txt_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
By default, the session ID will be the one returned after calling the
`libtlp.TLPTextClient.start_session` interface. However, an alternative session ID can be
provided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "t":}
**sI** is the segment ID, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def generate_translation_editor_url(self, oid, language, author_id, author_conf, session_id=None, req_key_lifetime=1440, author_name=None):
""" Returns a valid TLP Translation Editor URL.
**_oid_** is the Document ID, **_language_** is the ISO-639-1 code of the translation language to edit,
**_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
Finally, you can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
Ancestors (in MRO)
Class variables
var DEL_MODE_HARD
Hard delete mode for the /ingest/delete interface
var DEL_MODE_SOFT
Soft delete mode for the /ingest/delete interface
var TRANS_FORMAT_DTLX
Translation file in internal DTLX format
var TRANS_FORMAT_HTML
Translation file in internal HTML format
var TRANS_FORMAT_ORIGINAL
Translation file in original format
var TRANS_FORMAT_TEXT
Translation file in text format
var TRANS_SELDATA_ALL
Translation contents to be returned: Return both former and current contents (only for DTLX format).
var TRANS_SELDATA_CURRENT
Translation contents to be returned: Return current contents (current status of supervision of the translation).
var TRANS_SELDATA_FORMER
Translation contents to be returned: Return former contents (automatic translation).
Instance variables
Methods
def __init__(
self, api_base_url, translation_editor_base_url, api_user, api_secret_key)
Inheritance:
TLPStandardClient.__init__
Creates a TLPTextClient class instance. Parameters:
- api_base_url: Base URL to the transLectures-UPV Platform's Web Service.
- translation_editor_base_url: Base URL to the transLectures-UPV Platform's Translation Editor.
- api_user: API username / TLP username.
- api_secret_key: API Secret Key.
def __init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPTextClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_translation_editor_base_url_**: Base URL to the transLectures-UPV Platform's Translation Editor.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPStandardClient.__init__(self, api_base_url, translation_editor_base_url, api_user, api_secret_key, TLPClient.API_TEXT)
def api_accept(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_accept
Performs an API call to the /accept interface:
Accept modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be accepted by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_accept(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /accept interface:
> *Accept modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be accepted by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("accept")
def api_edit_history(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_edit_history
Performs an API call to the /edit_history interface:
Returns a list of all edit sessions carried out over an specific Media ID.
The oid parameter is the Media ID. Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_edit_history(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /edit_history interface:
> *Returns a list of all edit sessions carried out over an specific Media ID.*
he **_oid_** parameter is the Media ID. Optionally, a media hash
value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("edit_history")
def api_end_session(
self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_end_session
Performs an API call to the /end_session interface:
Ends an existing edition session.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
force option should set to True to force the end of a session when the given author_id or API user are not the same that started the given _session_id.
The regenerate option tells to the TLP Server if subtitles and/or synthesized audiotracks will be regenerated after ending the session. By default it is set to True.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_end_session(self, oid, author_id, author_conf, author_name=None, session_id=None, force=False, regenerate=True, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /end_session interface:
> *Ends an existing edition session.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
*_force_** option should set to *True* to force the end of a session when
the given **_author_id_** or API user are not the same that started the given
**_session_id**.
The **_regenerate_** option tells to the TLP Server if subtitles and/or synthesized audiotracks will be
regenerated after ending the session. By default it is set to *True*.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['force'] = int(force)
self.parameters['regenerate'] = int(regenerate)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("end_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = None
def api_get(
self, oid, lang, form=None, seldata=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /get interface:
Download current subtitles file for a given media ID and language.
The oid parameter is the Media ID, and lang is the language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional vhash parameter.
The format optional parameter sets the downloaded subtitles format.
Possible values are: TRANS_FORMAT_ORIGINAL,
TRANS_FORMAT_HTML,
TRANS_FORMAT_DTLX,
libtlp.TLPTextClient.TRANS_FORMAT_TXT.
seldata defines which subtitle contents are returned. Possible
values are: TRANS_SELDATA_ALL,
TRANS_SELDATA_FORMER,
TRANS_SELDATA_CURRENT.
A session_id argument can be provided in order to apply subtitle modifications made under the given edit session ID to the subtitles file.
For further details of both API call parameters please check the full TLP API documentation.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_get(self, oid, lang, form=None, seldata=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /get interface:
> *Download current subtitles file for a given media ID and language.*
he **_oid_** parameter is the Media ID, and **_lang_** is the
language code (ISO 639-1) of the requested subtitles language.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
The **_format_** optional parameter sets the downloaded subtitles format.
Possible values are: *`libtlp.TLPTextClient.TRANS_FORMAT_ORIGINAL`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_HTML`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_DTLX`*,
*`libtlp.TLPTextClient.TRANS_FORMAT_TXT`*.
*_seldata_** defines which subtitle contents are returned. Possible
values are: *`libtlp.TLPTextClient.TRANS_SELDATA_ALL`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_FORMER`*,
*`libtlp.TLPTextClient.TRANS_SELDATA_CURRENT`*.
A **_session_id_** argument can be provided in order to apply subtitle modifications made under the given edit session ID to the subtitles file.
For further details of both API call parameters please check the full TLP API documentation.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['lang'] = lang
if form != None:
if form not in (self.TRANS_FORMAT_ORIGINAL, self.TRANS_FORMAT_HTML, self.TRANS_FORMAT_DTLX, self.TRANS_FORMAT_TEXT):
raise TLPException("Unallowed document format.")
self.parameters['format'] = form
if seldata != None: self.parameters['sel_data_policy'] = seldata
if session_id != None: self.parameters['session_id'] = session_id
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("get")
def api_ingest_cancel(
self, oid, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_cancel
Performs an API call to the /ingest/cancel interface:
- Cancel upload operation. *
oid must be an upload ID.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_cancel(self, oid, debug_mode=False, su=None):
""" Performs an API call to the /ingest/cancel interface:
* Cancel upload operation. *
**_oid_** must be an upload ID.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/cancel')
self._last_api_call = "ingest"
def api_ingest_delete(
self, oid, mode=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_delete
Performs an API call to the /ingest/delete interface:
Delete a media object in the TLP Server.
oid must be a media ID.
Optionally, _mode__ provides the deletion mode.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_delete(self, oid, mode=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/delete interface:
*Delete a media object in the TLP Server.*
**_oid_** must be a media ID.
Optionally, **_mode__** provides the deletion mode.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['debug'] = debug_mode
if mode != None:
if mode not in ['hard', 'soft']:
raise TLPException("Delete mode must be 'hard' or 'soft'")
self.parameters['mode'] = mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call('ingest/delete')
def api_ingest_new(
self, media_package_file=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_new
Performs an API call to the /ingest/new interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_new(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/new interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/new', mp_fp)
self._last_api_call = "ingest"
def api_ingest_update(
self, media_package_file=None, debug_mode=False, su=None)
Inheritance:
TLPStandardClient.api_ingest_update
Performs an API call to the /ingest/update interface:
Upload media (audio/video) files and many other attachments and metadata to the TLP Server for automatic multilingual subtitling and speech synthesization.
If media_package_file is not provided, then it is generated
automatically by calling the create_media_package method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the libtlp.TLPStandardClient.manifest_init method.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_ingest_update(self, media_package_file=None, debug_mode=False, su=None):
""" Performs an API call to the /ingest/update interface:
*Upload media (audio/video) files and many other attachments and
metadata to the TLP Server for automatic multilingual subtitling
and speech synthesization.*
f **_media_package_file_** is not provided, then it is generated
automatically by calling the `libtlp.TLPStandardClient.create_media_package` method. In
this latter case, it is assumed that at least a manifest file has been
initialised before with the `libtlp.TLPStandardClient.manifest_init` method.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if self.requires_package:
if media_package_file != None:
mp_fp = media_package_file
else:
mp_fp = self.create_media_package()
else:
mp_fp = None
self.parameters['debug'] = debug_mode
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call_ingest('ingest/update', mp_fp)
self._last_api_call = "ingest"
def api_langs(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_langs
Performs an API call to the /langs interface:
Get a list of all subtitle and audiotrack languages available for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_langs(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /langs interface:
> *Get a list of all subtitle and audiotrack languages available for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("langs")
def api_list(
self, su=None)
Inheritance:
TLPStandardClient.api_list
Performs an API call to the /list interface:
Get a list of all existing audios and videos in the TLP Database.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_list(self, su=None):
""" Performs an API call to the /list interface:
*Get a list of all existing audios and videos in the TLP Database.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("list")
def api_lock(
self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_lock
Performs an API call to the /lock interface:
Allow/disallow regular users to send subtitles modifications for an specific Media ID.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_lock(self, oid, lock, author_id, author_conf, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /lock interface:
> *Allow/disallow regular users to send subtitles modifications for an specific Media ID.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(lock, bool)):
raise TLPException("lock must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['lock'] = int(lock)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("lock")
def api_mark_revised(
self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_mark_revised
Performs an API call to the /mark_revised interface:
Mark/unmark an edition session as revised.
session_id is the Session ID to mark/unmark as revised, the oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_mark_revised(self, oid, session_id, author_id, author_conf, author_name=None, revision_session_id=None, unmark=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /mark_revised interface:
> *Mark/unmark an edition session as revised.*
*_session_id_** is the Session ID to mark/unmark as revised,
the **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(unmark, bool)):
raise TLPException("unmark must be a boolean.")
self._reset()
self.parameters['id'] = oid
self.parameters['session_id'] = session_id
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['unmark'] = int(unmark)
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mark_revised")
def api_metadata(
self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_metadata
Performs an API call to the /metadata interface:
Get metadata and media file locations for a given media ID.
The oid parameter is the Media ID.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_metadata(self, oid, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /metadata interface:
> *Get metadata and media file locations for a given media ID.*
The **_oid_** parameter is the Media ID.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid)
else:
self._set_auth_parameters_secret_key()
self._call("metadata")
def api_mod(
self, oid, lang, author_id, author_conf, txt_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None)
Performs an API call to the /mod interface:
Send and commit subtitle corrections made by a user under an edit session ID.
By default, the session ID will be the one returned after calling the
libtlp.TLPTextClient.start_session interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, lang is the language code (ISO 639-1) of the edited subtitles language, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
txt_array is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":<int>, "t":<str>}
sI is the segment ID, and t is the updated segment text. txt_array must be an empty list if no segments where modified.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
Alternatively, you can provide a base64-encoded JSON data parameter value with all required /mod parameters. In this case, all mandatory arguments can be set to None, because they are ignored.
def api_mod(self, oid, lang, author_id, author_conf, txt_array, author_name=None, session_id=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1, data=None):
""" Performs an API call to the /mod interface:
> *Send and commit subtitle corrections made by a user under an edit session ID.*
y default, the session ID will be the one returned after calling the
`libtlp.TLPTextClient.start_session` interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
he **_oid_** parameter is the Media ID, **_lang_** is the language
code (ISO 639-1) of the edited subtitles language, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
**_txt_array_** is a list of JSON dictionaries, where each dictionary contains the following segment edition information:
{"sI":, "t":}
**sI** is the segment ID, and **t** is the updated segment text.
**_txt_array_** must be an empty list if no segments where modified.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
lternatively, you can provide a base64-encoded JSON data parameter
value with all required /mod parameters. In this case, all mandatory arguments can be
set to *None*, because they are ignored.
"""
self._reset()
if data != None:
self.parameters = json.loads(base64.b64decode(data), encoding='utf-8')
else:
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to send subtitle modifications (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['mods'] = { lang: { 'txt':[] } }
if author_name != None: self.parameters['author_name'] = author_name
if txt_array != None: self.parameters['mods'][lang]['txt'] = txt_array
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if self.use_get_method and not(self.use_data_parameter): self.parameters['mods'] = base64.b64encode(json.dumps(self.parameters['mods'], encoding='utf-8'))
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("mod")
def api_reject(
self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_reject
Performs an API call to the /reject interface:
Reject modifications of one or more pending edit sessions without having to revise them.
The ids parameter must be a list Session IDs whose edits are meant to be rejected by the given Author ID. author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_reject(self, ids, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /reject interface:
> *Reject modifications of one or more pending edit sessions without having to revise them.*
he **_ids_** parameter must be a list Session IDs whose edits are
meant to be rejected by the given Author ID. **_author_id_** is the ID of the
user that will edit the subtitles (typically the internal user ID that the API
client's organisation assigns to the user), and **_author_conf_** is an integer
value (range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
if not(isinstance(ids, list)):
raise TLPException("ids must be a list.")
self._reset()
self.parameters['id'] = ",".join([ str(x) for x in ids ])
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("reject")
def api_revisions(
self, su=None)
Inheritance:
TLPStandardClient.api_revisions
Performs an API call to the /revisions interface:
Returns a list of all edit sessions for all API user's media files that are pending to be revised.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_revisions(self, su=None):
""" Performs an API call to the /revisions interface:
> *Returns a list of all edit sessions for all API user's media files that are pending to be revised.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("revisions")
def api_session_status(
self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_session_status
Performs an API call to the /session_status interface:
Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.
By default, the session ID will be the one returned after calling the
/start_session (libtlp.TLPStandardClient.start_session) interface. However, an alternative session ID can be
provided via the optional session_id argument.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_session_status(self, oid, author_id, author_conf, session_id=None, alive=False, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /session_status interface:
> *Returns the current status of the given session ID. If it is alive, it updates the last alive timestamp. This interface is commonly used to avoid the automatic end of session due to user inactivity.*
y default, the session ID will be the one returned after calling the
*/start_session* (`libtlp.TLPStandardClient.start_session`) interface. However, an alternative session ID can be
rovided via the optional **_session_id_** argument.
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if session_id != None:
self.parameters['session_id'] = session_id
elif self._api_mod_session_id != None:
self.parameters['session_id'] = self._api_mod_session_id
else:
raise TLPException("You must start an edit session to check session status (see api_start_session()), or to manually provide a session ID (session_id optional argument).")
self.parameters['alive'] = int(alive)
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("session_status")
def api_start_session(
self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1)
Inheritance:
TLPStandardClient.api_start_session
Performs an API call to the /start_session interface:
Starts an edition session to send and commit modifications of a subtitles file.
The oid parameter is the Media ID, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional vhash parameter.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_start_session(self, oid, author_id, author_conf, author_name=None, vhash=None, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /start_session interface:
> *Starts an edition session to send and commit modifications of a subtitles file.*
The **_oid_** parameter is the Media ID, **_author_id_** is the ID of
the user that will edit the subtitles (typically the internal user ID that the
API client's organisation assigns to the user), and **_author_conf_** is an
integer value (range 0-100) that indicates the confidence level that the API
client's organisation provide to the user.
Optionally, a media hash value can be provided using the optional **_vhash_** parameter.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
if author_name != None: self.parameters['author_name'] = author_name
if vhash != None: self.parameters['hash'] = vhash
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
else:
self._set_auth_parameters_secret_key()
self._call("start_session")
if self.ret_data['rcode'] == 0:
self._api_mod_session_id = self.ret_data['session_id']
def api_status(
self, oid, su=None)
Inheritance:
TLPStandardClient.api_status
Performs an API call to the /status interface:
Check the current status of a specific upload ID.
oid is an upload ID, returned by the /ingest interface.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_status(self, oid, su=None):
""" Performs an API call to the /status interface:
> *Check the current status of a specific upload ID.*
**_oid_** is an upload ID, returned by the /ingest interface.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = oid
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("status")
def api_systems(
self, su=None)
Inheritance:
TLPStandardClient.api_systems
Performs an API call to the /systems interface:
Get a list of all available Speech Recognition, Machine Translation, and Text-To-Speech Systems that can be applied to transcribe, translate, and synthesize a media file.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
*Get a list of all available Speech Recognition, Machine
Translation, and Text-To-Speech Systems that can be applied to
transcribe, translate, and synthesize a media file.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
def api_uploadslist(
self, object_id=None, su=None)
Inheritance:
TLPStandardClient.api_uploadslist
Performs an API call to the /uploadslist interface:
Get a list of all user's uploads.
If the optional object_id argument is given, then the Web Service will return a list of uploads involving the provided object ID (could be an Upload ID or a Media ID).
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_uploadslist(self, object_id=None, su=None):
""" Performs an API call to the /uploadslist interface:
> *Get a list of all user's uploads.*
f the optional **_object_id_** argument is given, then the Web
Service will return a list of uploads involving the provided object ID (could
be an Upload ID or a Media ID).
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if object_id != None: self.parameters['object_id'] = object_id
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("uploadslist")
def create_media_package(
self, dest=None)
Inheritance:
TLPStandardClient.create_media_package
Creates a Media Package File from the manifest JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a temporal directory, unless you specify the destination file path with the optional parameter dest.
def create_media_package(self, dest=None):
"""Creates a Media Package File from the `libtlp.TLPStandardClient.manifest` JSON object information, returning the location of the zip package.
By default the media package file is created and stored in a
temporal directory, unless you specify the destination file path with the
optional parameter **_dest_**.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self._tmp_dir = tempfile.mkdtemp()
if dest == None:
dest = "%s/mpf.zip" % self._tmp_dir
zf = zipfile.ZipFile(dest, mode='w', allowZip64=True)
for f in self._manifest_files:
zf.write(f[0], arcname=f[1])
zf.close()
return dest
def disable_http_auth(
self)
Inheritance:
TLPStandardClient.disable_http_auth
Disable HTTP Authentication for all API calls
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def enable_http_auth(
self, http_user, http_pass)
Inheritance:
TLPStandardClient.enable_http_auth
Use HTTP Authentication for all API calls.
http_user is the HTTP Authentication username, while http_pass is the corresponding user password.
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def gen_request_key(
self, oid, expire, author=None, author_conf=None)
Inheritance:
TLPStandardClient.gen_request_key
Returns a valid request key to be used as an API authentication token.
oid is the object ID that will be queried (id API call parameter), and expire is the UNIX timestamp of the expiration time of the key. With these two parameters is generated the basic request key.
If author (author_id API parameter) is supplied, then the full request key is generated using this parameter plus author_conf (author_conf API parameter).
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def generate_translation_editor_url(
self, oid, language, author_id, author_conf, session_id=None, req_key_lifetime=1440, author_name=None)
Returns a valid TLP Translation Editor URL.
oid is the Document ID, language is the ISO-639-1 code of the translation language to edit, author_id is the ID of the user that will edit the subtitles (typically the internal user ID that the API client's organisation assigns to the user), and author_conf is an integer value (range 0-100) that indicates the confidence level that the API client's organisation provide to the user.
The full name of the user that will edit the subtitles can be provided with the parameter _author_name.
A session_id argument can be provided in order review subtitle modifications made under the provided edit session ID.
Finally, you can adjust de lifetime duration in minutes of the generated URL using the option req_key_lifetime. By default is set to 24 hours (1440 minutes).
def generate_translation_editor_url(self, oid, language, author_id, author_conf, session_id=None, req_key_lifetime=1440, author_name=None):
""" Returns a valid TLP Translation Editor URL.
*_oid_** is the Document ID, **_language_** is the ISO-639-1 code of the translation language to edit,
**_author_id_** is the ID of the user that
will edit the subtitles (typically the internal user ID that the API client's
organisation assigns to the user), and **_author_conf_** is an integer value
(range 0-100) that indicates the confidence level that the API client's
organisation provide to the user.
The full name of the user that will edit the subtitles can be provided with the parameter **_author_name**.
A **_session_id_** argument can be provided in order review subtitle modifications made under the provided edit session ID.
inally, you can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = oid
self.parameters['author_id'] = author_id
self.parameters['author_conf'] = author_conf
self.parameters['lang'] = language
if author_name != None: self.parameters['author_name'] = author_name
if session_id != None: self.parameters['session_id'] = session_id
self._set_auth_parameters_request_key_editor(req_key_lifetime, oid, author=author_id, author_conf=author_conf)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
def get_printable_manifest(
self)
Inheritance:
TLPStandardClient.get_printable_manifest
Returns a printable, user friendly version of the manifest JSON object (stored in the libtlp.TLPClient.manifest class member).
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def get_printable_response_data(
self)
Inheritance:
TLPStandardClient.get_printable_response_data
Returns a printable, user friendly version of the response data from the
last API call (stored in the ret_data class member).
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def manifest_add_document(
self, external_id, uri=None, title=None, fileformat=None)
Set main media file in the manifest JSON object.
external_id must be a Document ID.
uri can be a media file path o a media URL.
title is the title of the media.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPTextClient.api_ingest method.
def manifest_add_document(self, external_id, uri=None, title=None, fileformat=None):
"""Set main media file in the `libtlp.TLPTextClient.manifest` JSON object.
**_external_id_** must be a Document ID.
**_uri_** can be a media file path o a media URL.
**_title_** is the title of the media.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
doc = {}
doc['external_id'] = external_id
if title != None:
doc['title'] = title
if uri != None:
if self._is_url(uri):
doc['url'] = uri
else:
if fileformat != None:
doc['fileformat'] = fileformat
else:
doc['fileformat'] = self._get_file_format(uri)
doc['md5'] = self._md5sum(uri)
doc['filename'] = "%s.%s" % (doc['md5'], doc['fileformat'])
#doc['filename'] = self._get_file_name(uri)
self._manifest_files.append((uri, doc['filename']))
self.requires_package = True
self.manifest['documents'].append(doc)
def manifest_add_translation_request(
self, language, system_id=None, tl_path=None)
Request subtitles language in the "requested_langs" option of the manifest JSON object.
language is the requested subtitles language code in ISO 639-1 format (e.g. "en", "es").
Some advanced options can be provided to the Ingest Service for subtitles generation. system_id must be an integer value indicating the System ID to use, and tl_path must be a list of tuples (language, system_id) describing an alternative translation path. In this latter case, system_id is optional and must be set to None if is not provided.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPTextClient.api_ingest method.
def manifest_add_translation_request(self, language, system_id=None, tl_path=None):
"""Request subtitles language in the "requested_langs" option of the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the requested subtitles language code in ISO 639-1 format (e.g.
"en", "es").
Some advanced options can be provided to the Ingest Service for
subtitles generation. **_system_id_** must be an integer value indicating the
System ID to use, and **_tl_path_** must be a list of tuples
(language, system_id) describing an alternative translation path. In this
latter case, system_id is optional and must be set to None if is not provided.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
if 'requested_langs' not in self.manifest:
self.manifest['requested_langs'] = {}
if language not in self.manifest['requested_langs']:
self.manifest['requested_langs'][language] = {}
d = {}
if tl_path != None:
p = []
for s in tl_path: # is a tuple (langcode, systemId=None)
ds = {}
ds['l'] = s[0]
if s[1] != None: ds['sid'] = s[1]
p.append(ds)
d['tlpath'] = p
else:
if system_id != None: d['sid'] = system_id
self.manifest['requested_langs'][language] = d
def manifest_init(
self, language)
Initalize the manifest JSON object.
language is the documents' language code in ISO 639-1 format (e.g. "en", "es").
Note: This method should be executed before calling the libtlp.TLPTextClient.api_ingest method and any manifest_* class methods.
def manifest_init(self, language):
"""Initalize the `libtlp.TLPTextClient.manifest` JSON object.
**_language_** is the documents' language code in ISO 639-1 format (e.g.
"en", "es").
**Note:** This method should be executed before calling the `libtlp.TLPTextClient.api_ingest` method and any *manifest_\** class methods.
"""
self._tmp_dir = None
self._manifest_files = []
self.requires_package = False
self.manifest = {}
self.manifest['documents'] = []
self.manifest['language'] = language
def manifest_set_options(
self, generate=True, regenerate=False, force=False, test_mode=False, email=None)
Set Ingest Service options to the manifest JSON object.
generate is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, regenerate option can be used to request a regeneration of translations. Also, if force = True, regeneration of automatic subtitles is forced even if there exist human-supervised translations.
Finally, the test_mode argument is a boolean variable to enable/disable the Test Mode of the Ingest Service. When enabled, the uploaded media will be available inmediately with an empty translation file. This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
Note: The manifest object should have been
initialised before with a manifest_init call. This method
should be executed before calling the libtlp.TLPTextClient.api_ingest method.
def manifest_set_options(self, generate=True, regenerate=False, force=False, test_mode=False, email=None):
"""Set Ingest Service options to the `libtlp.TLPTextClient.manifest` JSON object.
**_generate_** is a boolean variable to enable/disable transcription and translation technologies.
On Update operations, **_regenerate_** option can be used to request a regeneration of
translations. Also, if **_force_** = *True*,
regeneration of automatic subtitles is forced even if there exist human-supervised translations.
Finally, the **_test_mode_** argument is a boolean variable to enable/disable the Test Mode of the Ingest Service.
When enabled, the uploaded media will be available inmediately with an empty translation file.
This feature is very useful when executing integration tests with the /ingest interface. By default it is disabled.
**Note:** The `libtlp.TLPTextClient.manifest` object should have been
initialised before with a `libtlp.TLPTextClient.manifest_init` call. This method
should be executed before calling the `libtlp.TLPTextClient.api_ingest` method.
"""
if self.manifest == None:
raise TLPException("Manifest file was not initialized.")
self.manifest['generate'] = generate
self.manifest['force'] = force
self.manifest['test_mode'] = test_mode
if regenerate != None: self.manifest['re-generate'] = regenerate
if email != None: self.manifest['email'] = email.split(",")
def save_response_data(
self, dest)
Inheritance:
TLPStandardClient.save_response_data
Saves the response data from the last API call (stored in the ret_data
class member) into the destination dest file.
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())
class TLPWebClient
class TLPWebClient(TLPClient):
def __init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPWebClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPClient.__init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key, TLPClient.API_WEB)
def api_manage_list(self, su=None):
""" Performs an API call to the /web/manage/list interface:
> *Get list of websites.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/list")
def api_manage_add(self, name, language, url_pattern, requested_langs, su=None):
""" Performs an API call to the /web/manage/add interface:
> *Adds a new web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['name'] = name
self.parameters['language'] = language
self.parameters['url_pattern'] = url_pattern
self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/add")
def api_manage_edit(self, key, enabled=None, url_pattern=None, requested_langs=None, su=None):
""" Performs an API call to the /web/manage/edit interface:
> *Edits and existing web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if enabled != None: self.parameters['enabled'] = enabled
if url_pattern != None: self.parameters['url_pattern'] = url_pattern
if requested_langs != None: self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/edit")
def api_manage_delete(self, key, purge=None, su=None):
""" Performs an API call to the /web/manage/delete interface:
> *Deletes an existing web site.*
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if purge != None: self.parameters['purge'] = purge
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/delete")
def api_editor_langs(self, key, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/langs interface:
> *Returns a list of translation languages available for a specific website.*
**_key_** must be the Website Key.
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/langs")
def api_editor_get(self, key, language, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/get interface:
> *Returns all existing source texts or translations of a specific website.*
**_key_** must be the Website Key, and **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es").
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/get")
def api_editor_mod(self, key, language, texts, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/mod interface:
> *Updates text translations of a specific website and language.*
**_key_** must be the Website Key, **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es"), and **_texts_** a dictionary of text hashes and text contents (i.e. '{"af129cd836a":"My updated text"}').
If **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
The **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
self.parameters['text'] = texts
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/mod")
def generate_web_translation_editor_url(self, web_key, language, req_key_lifetime=1440):
""" Returns a valid TLP Translation Editor URL.
**_web_key_** is the Website Key, and **_language_** is the ISO-639-1 code of the translation language to edit.
You can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = web_key
self.parameters['lang'] = language
self._set_auth_parameters_request_key_editor(req_key_lifetime, web_key)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
Ancestors (in MRO)
Class variables
Instance variables
var debug_info
Inheritance:
TLPClient.debug_info
Debug information of the last performed API call / Generation of Player URL.
var ret_content_type
Inheritance:
TLPClient.ret_content_type
Mime-type of the data returned by the last performed API call.
var ret_data
Inheritance:
TLPClient.ret_data
Data returned by the last performed API call. If the response was a JSON object, ret_data becomes a a parsed JSON object (dictionary or list, depending on the JSON).
var use_data_parameter
Inheritance:
TLPClient.use_data_parameter
Use a single "data" parameter on HTTP GET calls instead multiple GET parameters.
Methods
def __init__(
self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key)
Inheritance:
TLPClient.__init__
Creates a TLPWebClient class instance. Parameters:
- api_base_url: Base URL to the transLectures-UPV Platform's Web Service.
- api_user: API username / TLP username.
- api_secret_key: API Secret Key.
def __init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key):
"""
Creates a TLPWebClient class instance. Parameters:
- **_api_base_url_**: Base URL to the transLectures-UPV Platform's Web Service.
- **_api_user_**: API username / TLP username.
- **_api_secret_key_**: API Secret Key.
"""
TLPClient.__init__(self, api_base_url, web_translation_editor_base_url, api_user, api_secret_key, TLPClient.API_WEB)
def api_editor_get(
self, key, language, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /web/editor/get interface:
Returns all existing source texts or translations of a specific website.
key must be the Website Key, and language the requested language code in ISO 639-1 format (e.g. "en", "es").
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_editor_get(self, key, language, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/get interface:
> *Returns all existing source texts or translations of a specific website.*
**_key_** must be the Website Key, and **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es").
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/get")
def api_editor_langs(
self, key, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /web/editor/langs interface:
Returns a list of translation languages available for a specific website.
key must be the Website Key.
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_editor_langs(self, key, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/langs interface:
> *Returns a list of translation languages available for a specific website.*
**_key_** must be the Website Key.
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/langs")
def api_editor_mod(
self, key, language, texts, su=None, use_req_key=False, req_key_lifetime=1)
Performs an API call to the /web/editor/mod interface:
Updates text translations of a specific website and language.
key must be the Website Key, language the requested language code in ISO 639-1 format (e.g. "en", "es"), and texts a dictionary of text hashes and text contents (i.e. '{"af129cd836a":"My updated text"}').
If use_req_key = True, the API call will be performed using a valid Request Key as authentication token instead of the Secret Key. req_key_lifetime defines the Request Key lifetime in minutes, by default is 1 minute.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_editor_mod(self, key, language, texts, su=None, use_req_key=False, req_key_lifetime=1):
""" Performs an API call to the /web/editor/mod interface:
> *Updates text translations of a specific website and language.*
**_key_** must be the Website Key, **_language_** the requested language code in ISO 639-1 format (e.g.
"en", "es"), and **_texts_** a dictionary of text hashes and text contents (i.e. '{"af129cd836a":"My updated text"}').
f **_use_req_key_** *= True*, the API call will be performed using a
valid *Request Key* as authentication token instead of the *Secret Key*. **_req_key_lifetime_**
defines the *Request Key* lifetime in minutes, by default is 1 minute.
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
self.parameters['language'] = language
self.parameters['text'] = texts
if su != None: self.parameters['su'] = su
if use_req_key:
self._set_auth_parameters_request_key_api(req_key_lifetime, key)
else:
self._set_auth_parameters_secret_key()
self._call("editor/mod")
def api_manage_add(
self, name, language, url_pattern, requested_langs, su=None)
Performs an API call to the /web/manage/add interface:
Adds a new web site.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_manage_add(self, name, language, url_pattern, requested_langs, su=None):
""" Performs an API call to the /web/manage/add interface:
> *Adds a new web site.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['name'] = name
self.parameters['language'] = language
self.parameters['url_pattern'] = url_pattern
self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/add")
def api_manage_delete(
self, key, purge=None, su=None)
Performs an API call to the /web/manage/delete interface:
Deletes an existing web site.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_manage_delete(self, key, purge=None, su=None):
""" Performs an API call to the /web/manage/delete interface:
> *Deletes an existing web site.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if purge != None: self.parameters['purge'] = purge
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/delete")
def api_manage_edit(
self, key, enabled=None, url_pattern=None, requested_langs=None, su=None)
Performs an API call to the /web/manage/edit interface:
Edits and existing web site.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_manage_edit(self, key, enabled=None, url_pattern=None, requested_langs=None, su=None):
""" Performs an API call to the /web/manage/edit interface:
> *Edits and existing web site.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
self.parameters['id'] = key
if enabled != None: self.parameters['enabled'] = enabled
if url_pattern != None: self.parameters['url_pattern'] = url_pattern
if requested_langs != None: self.parameters['requested_langs'] = requested_langs
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/edit")
def api_manage_list(
self, su=None)
Performs an API call to the /web/manage/list interface:
Get list of websites.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_manage_list(self, su=None):
""" Performs an API call to the /web/manage/list interface:
> *Get list of websites.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("manage/list")
def api_systems(
self, su=None)
Inheritance:
TLPClient.api_systems
Performs an API call to the /systems interface:
Get a list of all available Speech Recognition, Machine Translation, and Text-To-Speech Systems that can be applied to transcribe, translate, and synthesize a media file.
The su (substitute user) option can be used by Admin users to be identified as another existing API user at the TLP Web Service.
def api_systems(self, su=None):
""" Performs an API call to the /systems interface:
*Get a list of all available Speech Recognition, Machine
Translation, and Text-To-Speech Systems that can be applied to
transcribe, translate, and synthesize a media file.*
he **_su_** (*substitute user*) option can be used by Admin users
to be identified as another existing API user at the TLP Web Service.
"""
self._reset()
if su != None: self.parameters['su'] = su
self._set_auth_parameters_secret_key()
self._call("systems")
def disable_http_auth(
self)
Inheritance:
TLPClient.disable_http_auth
Disable HTTP Authentication for all API calls
def disable_http_auth(self):
"""Disable HTTP Authentication for all API calls"""
self._http_user = None
self._http_pass = None
self._http_auth_enabled = False
def enable_http_auth(
self, http_user, http_pass)
Inheritance:
TLPClient.enable_http_auth
Use HTTP Authentication for all API calls.
http_user is the HTTP Authentication username, while http_pass is the corresponding user password.
def enable_http_auth(self, http_user, http_pass):
"""Use HTTP Authentication for all API calls.
**_http_user_** is the HTTP Authentication username, while **_http_pass_** is the corresponding user password.
"""
self._http_user = http_user
self._http_pass = http_pass
self._http_auth_enabled = True
def gen_request_key(
self, oid, expire, author=None, author_conf=None)
Inheritance:
TLPClient.gen_request_key
Returns a valid request key to be used as an API authentication token.
oid is the object ID that will be queried (id API call parameter), and expire is the UNIX timestamp of the expiration time of the key. With these two parameters is generated the basic request key.
If author (author_id API parameter) is supplied, then the full request key is generated using this parameter plus author_conf (author_conf API parameter).
def gen_request_key(self, oid, expire, author=None, author_conf=None):
"""Returns a valid request key to be used as an API authentication token.
**_oid_** is the object ID that will be queried (*id* API call
parameter), and **_expire_** is the UNIX timestamp of the expiration time of
the key. With these two parameters is generated the *basic request key*.
If **_author_** (*author_id* API parameter) is supplied, then the *full request key* is generated
using this parameter plus **_author_conf_** (*author_conf* API parameter).
"""
s1 = hashlib.sha1()
s1.update(oid + str(expire) + self._api_user + self._api_secret_key)
rk = s1.hexdigest()
if author != None:
s2 = hashlib.sha1()
s2.update(author + str(author_conf) + str(expire) + self._api_user + self._api_secret_key)
rk += s2.hexdigest()
return rk
def generate_web_translation_editor_url(
self, web_key, language, req_key_lifetime=1440)
Returns a valid TLP Translation Editor URL.
web_key is the Website Key, and language is the ISO-639-1 code of the translation language to edit.
You can adjust de lifetime duration in minutes of the generated URL using the option req_key_lifetime. By default is set to 24 hours (1440 minutes).
def generate_web_translation_editor_url(self, web_key, language, req_key_lifetime=1440):
""" Returns a valid TLP Translation Editor URL.
*_web_key_** is the Website Key, and **_language_** is the ISO-639-1 code of the translation language to edit.
ou can adjust de lifetime duration in minutes of the
generated URL using the option **_req_key_lifetime_**. By default is set to 24
hours (1440 minutes).
"""
self._reset()
self.parameters['id'] = web_key
self.parameters['lang'] = language
self._set_auth_parameters_request_key_editor(req_key_lifetime, web_key)
if self.debug: self._generate_debug_info_editor()
request_parameter = base64.b64encode(json.dumps(self.parameters, encoding='UTF-8'))
url = "%s?request=%s" % (self._editor_base_url, request_parameter)
return url
def get_printable_manifest(
self)
Inheritance:
TLPClient.get_printable_manifest
Returns a printable, user friendly version of the manifest JSON object (stored in the libtlp.TLPClient.manifest class member).
def get_printable_manifest(self):
"""Returns a printable, user friendly version of the manifest JSON object (stored in the `libtlp.TLPClient.manifest` class member).
"""
if self.manifest != None:
return json.dumps(self.manifest, indent=4)
else:
raise TLPException("Manifest file was not initialized.")
def get_printable_response_data(
self)
Inheritance:
TLPClient.get_printable_response_data
Returns a printable, user friendly version of the response data from the
last API call (stored in the ret_data class member).
def get_printable_response_data(self):
"""Returns a printable, user friendly version of the response data from the
last API call (stored in the `libtlp.TLPClient.ret_data` class member).
"""
if self.ret_data == None:
raise TLPException("No response data available (have you called any API interface before?).")
if self.ret_content_type.find("application/json") >= 0:
return json.dumps(self.ret_data, indent=4)
else:
return self.ret_data
def save_response_data(
self, dest)
Inheritance:
TLPClient.save_response_data
Saves the response data from the last API call (stored in the ret_data
class member) into the destination dest file.
def save_response_data(self, dest):
"""Saves the response data from the last API call (stored in the `libtlp.TLPClient.ret_data`
class member) into the destination **_dest_** file.
"""
with open(dest,'wb') as fd:
fd.write(self.get_printable_response_data())