Add Glossary support

- Introduced Glossary, GlossaryImport, and GlossaryCounts models, plus Glossaries service for CRUD, import/export, and counts
- Extended Documents, high-level client, and LaraClient to support glossaries parameter and binary CSV export
- Updated LaraClient._request and HTTP methods to return raw bytes for CSV/export endpoints

Author: f4b1ux

src/lara_sdk/_client.py

@@ -75,7 +75,7 @@ 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, headers: Dict = None) -> Optional[Union[Dict, List]]:
+    def get(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List, bytes]]:
         """
         Sends a GET request to the Lara API.
         :param path: The path to send the request to.
@@ -85,7 +85,7 @@ def get(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[
         """
         return self._request('GET', path, body=params, headers=headers)
 
-    def delete(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
+    def delete(self, path: str, params: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List, bytes]]:
         """
         Sends a DELETE request to the Lara API.
         :param path: The path to send the request to.
@@ -95,7 +95,7 @@ def delete(self, path: str, params: Dict = None, headers: Dict = None) -> Option
         """
         return self._request('DELETE', path, body=params, headers=headers)
 
-    def post(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
+    def post(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List, bytes]]:
         """
         Sends a POST request to the Lara API.
         :param path: The path to send the request to.
@@ -106,7 +106,7 @@ def post(self, path: str, body: Dict = None, files: Dict = None, headers: Dict =
         """
         return self._request('POST', path, body, files, headers)
 
-    def put(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List]]:
+    def put(self, path: str, body: Dict = None, files: Dict = None, headers: Dict = None) -> Optional[Union[Dict, List, bytes]]:
         """
         Sends a PUT request to the Lara API.
         :param path: The path to send the request to.
@@ -117,7 +117,7 @@ def put(self, path: str, body: Dict = None, files: Dict = None, headers: Dict =
         """
         return self._request('PUT', path, body, files, headers)
 
-    def _request(self, method: str, path: str, body: Dict = None, files: Dict = None, headers: 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, bytes]]:
         if not path.startswith('/'):
             path = '/' + path
 
@@ -145,5 +145,7 @@ def _request(self, method: str, path: str, body: Dict = None, files: Dict = None
             response = self.session.request('POST', f'{self.base_url}{path}', headers=_headers, json=body)
 
         if 200 <= response.status_code < 300:
+            if "text/csv" in response.headers.get('Content-Type', ''):
+                return response.content
             return response.json().get('content', None)
         raise LaraApiError.from_response(response)

src/lara_sdk/_translator.py

@@ -1,7 +1,7 @@
 import time
 from datetime import datetime
 from enum import Enum
-from typing import Optional, Union, List, Iterable, Callable
+from typing import Optional, Union, List, Iterable, Callable, Literal
 from dataclasses import dataclass
 
 from gzip_stream import GZIPCompressedStream
@@ -36,9 +36,32 @@ def __init__(self, **kwargs):
         self.size: int = kwargs.get('size')
         self.progress: float = kwargs.get('progress')
 
+class Glossary(LaraObject):
+    def __init__(self, **kwargs):
+        self.id: str = kwargs.get('id')
+        self.name: str = kwargs.get('name')
+        self.owner_id: str = kwargs.get('owner_id')
+        self.created_at: datetime = self._parse_date(kwargs.get('created_at', None))
+        self.updated_at: datetime = self._parse_date(kwargs.get('updated_at', None))
+
+class GlossaryImport(LaraObject):
+    def __init__(self, **kwargs):
+        self.id: str = kwargs.get('id')
+        self.begin: int = kwargs.get('begin')
+        self.end: int = kwargs.get('end')
+        self.channel: int = kwargs.get('channel')
+        self.size: int = kwargs.get('size')
+        self.progress: float = kwargs.get('progress')
+
+class GlossaryCounts(LaraObject):
+    def __init__(self, **kwargs):
+        self.unidirectional: Optional[dict[str, int]] = kwargs.get('unidirectional')
+        self.multidirectional: Optional[int] = kwargs.get('multidirectional')
+
 @dataclass
 class DocumentOptions:
     adapt_to: Optional[List[str]] = None
+    glossaries: Optional[List[str]] = None
     no_trace: Optional[bool] = None
 
 class Document(LaraObject):
@@ -168,6 +191,75 @@ def wait_for_import(self, memory_import: MemoryImport, *,
 
         return memory_import
 
+class Glossaries:
+    def __init__(self, client: LaraClient):
+        self._client: LaraClient = client
+        self._polling_interval: int = 2
+
+    def list(self) -> List[Glossary]:
+        return [Glossary(**e) for e in self._client.get('/glossaries')]
+
+    def create(self, name: str) -> Glossary:
+        return Glossary(**self._client.post('/glossaries', {
+            'name': name
+        }))
+
+    def get(self, id_: str) -> Optional[Glossary]:
+        try:
+            return Glossary(**self._client.get(f'/glossaries/{id_}'))
+        except LaraApiError as e:
+            if e.status_code == 404:
+                return None
+            raise
+
+    def delete(self, id_: str) -> Glossary:
+        return Glossary(**self._client.delete(f'/glossaries/{id_}'))
+
+    def update(self, id_: str, name: str) -> Glossary:
+        return Glossary(**self._client.put(f'/glossaries/{id_}', {
+            'name': name
+        }))
+
+    def import_csv(self, id_: str, csv: str) -> GlossaryImport:
+        with open(csv, 'rb') as stream:
+            compressed_stream = GZIPCompressedStream(stream, compression_level=7)
+            return GlossaryImport(**self._client.post(f'/glossaries/{id_}/import',
+                                                    {'compression': 'gzip'}, {'csv': compressed_stream}))
+
+    def get_import_status(self, id_: str) -> GlossaryImport:
+        return GlossaryImport(**self._client.get(f'/glossaries/imports/{id_}'))
+
+    def wait_for_import(self, glossary_import: GlossaryImport, *,
+                        update_callback: Callable[[GlossaryImport], None] = None,
+                        max_wait_time: float = 0) -> GlossaryImport:
+        start = time.time()
+        while glossary_import.progress < 1.:
+            if 0 < max_wait_time < time.time() - start:
+                raise TimeoutError()
+
+            time.sleep(self._polling_interval)
+
+            glossary_import = self.get_import_status(glossary_import.id)
+            if update_callback is not None:
+                update_callback(glossary_import)
+
+        return glossary_import
+
+    def counts(self, id_: str) -> GlossaryCounts:
+        return GlossaryCounts(**self._client.get(f'/glossaries/{id_}/counts'))
+
+
+    def export(self, id_: str, content_type: Literal["csv/table-uni"], source: Optional[str]) -> bytes:
+        """
+        Exports a csv file with the glossary content. If the content_type is "csv/table-uni", the
+        file will contain a unidirectional glossary with only terms in the specified source language (required)
+        """
+        response = self._client.get(f'/glossaries/{id_}/export', {
+            'content_type': content_type,
+            'source': source
+        })
+        return response
+
 
 
 class DocumentStatus(Enum):
@@ -186,7 +278,7 @@ def __init__(self, client: LaraClient):
         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, no_trace: bool = False) -> Document:
+               adapt_to: Optional[List[str]] = None, glossaries: 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})
 
@@ -205,6 +297,9 @@ def upload(self, file_path: str, filename: str, target: str, source: Optional[st
         if adapt_to is not None:
             body['adapt_to'] = adapt_to
 
+        if glossaries is not None:
+            body['glossaries'] = glossaries
+
         headers = None
         if no_trace is True:
             headers = {'X-No-Trace': 'true'}
@@ -222,11 +317,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,
+                  adapt_to: Optional[List[str]] = None, glossaries: 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,
-                               no_trace=no_trace)
+                               glossaries=glossaries, no_trace=no_trace)
 
         max_wait_time = 60 * 15 # 15 minutes
         start = time.time()
@@ -265,13 +360,14 @@ def __init__(self, credentials: Credentials = None, *,
         self._client: LaraClient = LaraClient(credentials.access_key_id, credentials.access_key_secret, server_url)
         self.memories: Memories = Memories(self._client)
         self.documents: Documents = Documents(self._client)
+        self.glossaries: Glossaries = Glossaries(self._client)
 
     def languages(self) -> List[str]:
         return self._client.get('/languages')
 
     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,
+                  glossaries: 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,
                   no_trace: bool = False, verbose: bool = False) -> TextResult:
@@ -297,7 +393,7 @@ def translate(self, text: Union[str, Iterable[str], Iterable[TextBlock]], *,
             '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,
-            'verbose': verbose
+            'glossaries': glossaries, 'verbose': verbose
         }
 
         headers = None