Feature: incognito mode (#3)

* feature: add optional headers parameter to HTTP client methods

* feature: support incognito mode for text and document translation

Author: f4b1ux

src/lara_sdk/_client.py

@@ -75,67 +75,75 @@ def __init__(self, access_key_id: str, access_key_secret: str, server_url: str =
         self.sdk_name: str = 'lara-python'
         self.sdk_version: str = __import__('lara_sdk').__version__
 
-    def get(self, path: str, params: Dict = None) -> Optional[Union[Dict, List]]:
+    def get(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
         """
         Sends a GET request to the Lara API.
         :param path: The path to send the request to.
         :param params: The parameters to send with the request.
+        :param headers: Additional headers to include in the request.
         :return: The JSON response from the API.
         """
-        return self._request('GET', path, body=params)
+        return self._request('GET', path, body=params, headers=headers)
 
-    def delete(self, path: str, params: Dict = None) -> Optional[Union[Dict, List]]:
+    def delete(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
         """
         Sends a DELETE request to the Lara API.
         :param path: The path to send the request to.
         :param params: The parameters to send with the request.
+        :param headers: Additional headers to include in the request.
         :return: The JSON response from the API.
         """
-        return self._request('DELETE', path, body=params)
+        return self._request('DELETE', path, body=params, headers=headers)
 
-    def post(self, path: str, body: Dict = None, files: Dict = None) -> Optional[Union[Dict, List]]:
+    def post(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
         """
         Sends a POST request to the Lara API.
         :param path: The path to send the request to.
         :param body: The parameters to send with the request.
         :param files: The files to send with the request. If present, request will be sent as multipart/form-data.
+        :param headers: Additional headers to include in the request.
         :return: The JSON response from the API.
         """
-        return self._request('POST', path, body, files)
+        return self._request('POST', path, body, files, headers)
 
-    def put(self, path: str, body: Dict = None, files: Dict = None) -> Optional[Union[Dict, List]]:
+    def put(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
         """
         Sends a PUT request to the Lara API.
         :param path: The path to send the request to.
         :param body: The parameters to send with the request.
         :param files: The files to send with the request. If present, request will be sent as multipart/form-data.
+        :param headers: Additional headers to include in the request.
         :return: The JSON response from the API.
         """
-        return self._request('PUT', path, body, files)
+        return self._request('PUT', path, body, files, headers)
 
-    def _request(self, method: str, path: str, body: Dict = None, files: Dict = None) -> Optional[Union[Dict, List]]:
+    def _request(self, method: str, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
         if not path.startswith('/'):
             path = '/' + path
 
-        headers = {
+        _headers = {
             'X-HTTP-Method-Override': method,
             'Date': datetime.datetime.now(datetime.timezone.utc).strftime('%a, %d %b %Y %H:%M:%S +0000'),
             'X-Lara-SDK-Name': self.sdk_name,
             'X-Lara-SDK-Version': self.sdk_version
         }
 
+        # headers
+        if headers is not None:
+            _headers.update(headers)
+
         if body is not None:
             body = {k: v for k, v in body.items() if v is not None}
 
             if len(body) > 0:
                 encoded_body = json.dumps(body, ensure_ascii=False, separators=(',', ':')).encode('UTF-8')
-                headers['Content-MD5'] = hashlib.md5(encoded_body).hexdigest()
+                _headers['Content-MD5'] = hashlib.md5(encoded_body).hexdigest()
 
         if files is not None:
-            response = self.session.request('POST', f'{self.base_url}{path}', headers=headers, data=body, files=files)
+            response = self.session.request('POST', f'{self.base_url}{path}', headers=_headers, data=body, files=files)
         else:
-            response = self.session.request('POST', f'{self.base_url}{path}', headers=headers, json=body)
+            response = self.session.request('POST', f'{self.base_url}{path}', headers=_headers, json=body)
 
         if 200 <= response.status_code < 300:
             return response.json().get('content', None)
-        raise LaraApiError.from_response(response)
+        raise LaraApiError.from_response(response)

src/lara_sdk/_translator.py

@@ -39,6 +39,7 @@ def __init__(self, **kwargs):
 @dataclass
 class DocumentOptions:
     adapt_to: Optional[List[str]] = None
+    no_trace: Optional[bool] = None
 
 class Document(LaraObject):
 
@@ -184,7 +185,8 @@ def __init__(self, client: LaraClient):
         self._s3client = S3Client()
         self._polling_interval: int = 2
 
-    def upload(self, file_path: str, filename: str, target: str, source: Optional[str] = None, adapt_to: Optional[List[str]] = None) -> Document:
+    def upload(self, file_path: str, filename: str, target: str, source: Optional[str] = None,
+               adapt_to: Optional[List[str]] = None, no_trace: bool = False) -> Document:
         with open(file_path, 'rb') as file_payload:
             response_data = self._client.get('/documents/upload-url', {'filename': filename})
 
@@ -203,7 +205,11 @@ def upload(self, file_path: str, filename: str, target: str, source: Optional[st
         if adapt_to is not None:
             body['adapt_to'] = adapt_to
 
-        return Document(**self._client.post('/documents', body))
+        headers = None
+        if no_trace is True:
+            headers = {'X-No-Trace': 'true'}
+
+        return Document(**self._client.post('/documents', body, headers=headers))
 
     def status(self, id: str) -> Document:
         return Document(**self._client.get(f'/documents/{id}'))
@@ -216,9 +222,11 @@ def download(self, id: str, output_format: Optional[str] = None) -> bytes:
         return self._s3client.download(url=url)
 
     def translate(self, file_path: str, filename: str, target: str, source: Optional[str] = None, 
-                  adapt_to: Optional[List[str]] = None, output_format: Optional[str] = None) -> bytes:
+                  adapt_to: Optional[List[str]] = None, output_format: Optional[str] = None,
+                  no_trace: bool = False) -> bytes:
 
-        document = self.upload(file_path=file_path, filename=filename, target=target, source=source, adapt_to=adapt_to)
+        document = self.upload(file_path=file_path, filename=filename, target=target, source=source, adapt_to=adapt_to,
+                               no_trace=no_trace)
 
         max_wait_time = 60 * 15 # 15 minutes
         start = time.time()
@@ -265,7 +273,8 @@ def translate(self, text: Union[str, Iterable[str], Iterable[TextBlock]], *,
                   source: str = None, source_hint: str = None, target: str, adapt_to: List[str] = None,
                   instructions: List[str] = None, content_type: str = None,
                   multiline: bool = True, timeout_ms: int = None, priority: TranslatePriority = None,
-                  use_cache: Union[bool, UseCache] = None, cache_ttl_s: int = None) -> TextResult:
+                  use_cache: Union[bool, UseCache] = None, cache_ttl_s: int = None,
+                  no_trace: bool = False) -> TextResult:
         if isinstance(text, str):
             q = text
         elif hasattr(text, '__iter__'):
@@ -283,9 +292,15 @@ def translate(self, text: Union[str, Iterable[str], Iterable[TextBlock]], *,
         elif use_cache is False:
             use_cache = UseCache.NO
 
-        return TextResult(**self._client.post('/translate', {
+        body = {
             'source': source, 'target': target, 'source_hint': source_hint, 'content_type': content_type,
             'multiline': multiline, 'adapt_to': adapt_to, 'instructions': instructions, 'timeout': timeout_ms, 'q': q,
             'priority': priority.value if priority is not None else None,
             'use_cache': use_cache.value if use_cache is not None else None, 'cache_ttl': cache_ttl_s
-        }))
+        }
+
+        headers = None
+        if no_trace is True:
+            headers = {'X-No-Trace': 'true'}
+
+        return TextResult(**self._client.post('/translate', body, headers=headers))