Skip to content

Commit 2e74dbc

Browse files
hive-botclaude
andcommitted
feat: align the multilingual glossary functions with the other SDKs
Add update_multilingual_glossary() to rename a glossary and/or merge dictionaries in one request, and get_multilingual_glossary_dictionary_entries() returning the entries of one dictionary. Add extra_body_parameters to the create, update and replace functions, accept a MultilingualGlossaryInfo in get_multilingual_glossary(), and export the multilingual glossary types from the deepl package. Rename the arguments glossary_dicts, glossary_dict, csv_data and glossary_id to dictionaries, dictionary, csv and glossary; the old names keep working with a DeprecationWarning. get_multilingual_glossary_entries() is deprecated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 3b38a02 commit 2e74dbc

7 files changed

Lines changed: 826 additions & 223 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,30 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9999
`rephrase_text()`, and the `extra_body_parameters` option to
100100
`correct_text()`. `writing_style` and `tone` accept a `WritingStyle` or
101101
`WritingTone` member or a string.
102+
- Added `update_multilingual_glossary()` to the `DeepLClient` class to rename a
103+
multilingual glossary and/or merge dictionaries into it in one request,
104+
sending only the options that are set.
105+
- Added `get_multilingual_glossary_dictionary_entries()` to the `DeepLClient`
106+
class, returning the `MultilingualGlossaryDictionaryEntries` of one dictionary
107+
and raising `GlossaryNotFoundException` if the glossary has none for the
108+
language pair.
109+
- Added the `extra_body_parameters` option to `create_multilingual_glossary()`,
110+
`create_multilingual_glossary_from_csv()`,
111+
`update_multilingual_glossary_name()`,
112+
`update_multilingual_glossary_dictionary()`,
113+
`update_multilingual_glossary_dictionary_from_csv()`,
114+
`replace_multilingual_glossary_dictionary()` and
115+
`replace_multilingual_glossary_dictionary_from_csv()`.
116+
- `get_multilingual_glossary()` accepts a `MultilingualGlossaryInfo` object, as
117+
`glossary`, besides a glossary ID.
118+
- Added the argument names `dictionaries` (`create_multilingual_glossary()`),
119+
`dictionary` (`update_multilingual_glossary_dictionary()`,
120+
`replace_multilingual_glossary_dictionary()`), `csv` (the
121+
`*_multilingual_glossary*_from_csv()` functions) and `glossary`
122+
(`get_multilingual_glossary()`).
123+
- `MultilingualGlossaryInfo`, `MultilingualGlossaryDictionaryInfo` and
124+
`MultilingualGlossaryDictionaryEntries` are exported from the `deepl` package.
125+
- Added `MultilingualGlossaryDictionaryInfo.to_json()`.
102126

103127
### Changed
104128
- HTTP 404 responses raise `NotFoundException` instead of `DeepLException`
@@ -165,6 +189,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
165189
- The `style` keyword of `rephrase_text()` is deprecated in favour of
166190
`writing_style` and emits a `DeprecationWarning`. It keeps working; if both
167191
are given, `writing_style` is used.
192+
- `get_multilingual_glossary_entries()` is deprecated, use
193+
`get_multilingual_glossary_dictionary_entries()`.
194+
- The argument names `glossary_dicts`, `glossary_dict`, `csv_data` and
195+
`glossary_id` of the multilingual glossary functions are deprecated, use
196+
`dictionaries`, `dictionary`, `csv` and `glossary`.
168197

169198
### Fixed
170199
- HTTP 401 responses now raise `AuthorizationException`, like 403. Before they

‎README.md‎

Lines changed: 64 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -450,7 +450,10 @@ You can create a multi-lingual glossary with your desired terms and name using
450450
support multiple source-target language pairs. Note: Glossaries are only
451451
supported for some language pairs, see
452452
[Listing available glossary languages](#listing-available-glossary-languages)
453-
for more information. The entries should be specified as a dictionary.
453+
for more information. The entries should be specified as a dictionary, in
454+
`MultilingualGlossaryDictionaryEntries` objects passed as `dictionaries`.
455+
`MultilingualGlossaryDictionaryEntries`, `MultilingualGlossaryInfo` and
456+
`MultilingualGlossaryDictionaryInfo` can be imported from the `deepl` package.
454457

455458
If successful, the glossary is created and stored with your DeepL account, and
456459
a `MultilingualGlossaryInfo` object is returned including the ID, name, and glossary
@@ -459,6 +462,8 @@ dictionaries. The glossary dictionaries would be an array of
459462
entry count.
460463

461464
```python
465+
from deepl import MultilingualGlossaryDictionaryEntries
466+
462467
# Create a glossary with an English to German dictionary containing two terms:
463468
entries = {"artist": "Maler", "prize": "Gewinn"}
464469
dictionaries = [MultilingualGlossaryDictionaryEntries("EN", "DE", entries)]
@@ -481,8 +486,8 @@ print(
481486
You can also upload a glossary downloaded from the DeepL website using
482487
`create_multilingual_glossary_from_csv()`. Instead of supplying the entries as a
483488
dictionary within a MultilingualGlossaryDictionaryEntries object, you can specify
484-
the CSV data as `csv_data` either as a file-like object or string or bytes
485-
containing file content:
489+
the CSV data as `csv` either as a file-like object or string or bytes
490+
containing file content (`csv_data` is the deprecated name of this argument):
486491

487492
```python
488493
# Open the CSV file assuming UTF-8 encoding. If your file contains a BOM,
@@ -493,7 +498,7 @@ with open('/path/to/glossary_file.csv', 'r', encoding='utf-8') as csv_file:
493498
"CSV glossary",
494499
source_lang="EN",
495500
target_lang="DE",
496-
csv_data=csv_data,
501+
csv=csv_data,
497502
)
498503
```
499504

@@ -504,7 +509,8 @@ detail.
504509

505510
Functions to get, list, and delete stored glossaries are also provided:
506511

507-
- `get_multilingual_glossary()` takes a glossary ID and returns a
512+
- `get_multilingual_glossary()` takes a glossary ID or `MultilingualGlossaryInfo`
513+
object and returns a
508514
`MultilingualGlossaryInfo` object for a stored glossary, or raises an
509515
exception if no such glossary is found.
510516
- `list_multilingual_glossaries()` returns a list of `MultilingualGlossaryInfo` objects
@@ -537,32 +543,65 @@ for glossary in glossaries:
537543
The `MultilingualGlossaryInfo` object does not contain the glossary entries, but
538544
instead only the number of entries in the `entry_count` property.
539545

540-
To list the entries contained within a stored glossary, use
541-
`get_multilingual_glossary_entries()` providing either the `MultilingualGlossaryInfo` object or glossary
542-
ID and either a `MultilingualGlossaryDictionaryInfo` or source and target language pair:
546+
To list the entries of one dictionary within a stored glossary, use
547+
`get_multilingual_glossary_dictionary_entries()` providing either the
548+
`MultilingualGlossaryInfo` object or glossary ID, and the source and target
549+
language. It returns a `MultilingualGlossaryDictionaryEntries` object whose
550+
`entries` is a dictionary of source-target terms, and raises a
551+
`GlossaryNotFoundException` if the glossary has no dictionary for that language
552+
pair:
543553

544554
```python
545-
entries = deepl_client.get_multilingual_glossary_entries(my_glossary, "EN", "DE")
546-
print(entries.dictionaries[0]) # "{'artist': 'Maler', 'prize': 'Gewinn'}"
555+
dictionary = deepl_client.get_multilingual_glossary_dictionary_entries(
556+
my_glossary, "EN", "DE"
557+
)
558+
print(dictionary.entries) # "{'artist': 'Maler', 'prize': 'Gewinn'}"
547559
```
548560

561+
`get_multilingual_glossary_entries()` is deprecated: it returns a
562+
`MultilingualGlossaryDictionaryEntriesResponse` wrapping a list of
563+
dictionaries. Use `get_multilingual_glossary_dictionary_entries()` instead.
564+
549565
#### Editing a glossary
550566

551567
Functions to edit stored glossaries are also provided:
552568

569+
- `update_multilingual_glossary()` takes a glossary ID or `MultilingualGlossaryInfo`
570+
object, plus the optional keyword arguments `name` (the new name) and
571+
`dictionaries` (a list of `MultilingualGlossaryDictionaryEntries` to merge into
572+
the glossary, as `update_multilingual_glossary_dictionary()` does for one).
573+
Only the arguments that are set are sent.
553574
- `update_multilingual_glossary_dictionary()` takes a glossary ID or `MultilingualGlossaryInfo`
554-
object, plus a source language, target language, and a dictionary of entries.
575+
object, plus a `dictionary`: a `MultilingualGlossaryDictionaryEntries` with
576+
a source language, target language, and a dictionary of entries.
555577
It will then either update the list of entries for that dictionary (either
556578
inserting new entires or replacing the target phrase for any existing
557579
entries) or will insert a new glossary dictionary if that language pair is
558580
not currently in the stored glossary.
559581
- `replace_multilingual_glossary_dictionary()` takes a glossary ID or `MultilingualGlossaryInfo`
560-
object, plus a source language, target language, and a dictionary of entries.
582+
object, plus a `dictionary`: a `MultilingualGlossaryDictionaryEntries` with
583+
a source language, target language, and a dictionary of entries.
561584
It will then either set the entries to the parameter value, completely
562585
replacing any pre-existing entries for that language pair.
563586
- `update_multilingual_glossary_name()` takes a glossary ID or `MultilingualGlossaryInfo`
564587
object, plus the new name of the glossary.
565588

589+
The `*_from_csv()` variants take the entries as `csv` instead. The
590+
`glossary_dicts` (of `create_multilingual_glossary()`), `glossary_dict` and
591+
`csv_data` argument names are deprecated; use `dictionaries`, `dictionary` and
592+
`csv`. `get_multilingual_glossary()` likewise takes `glossary`; its
593+
`glossary_id` keyword is deprecated.
594+
595+
The functions that create, update or replace glossaries and dictionaries
596+
(`create_multilingual_glossary()`, `create_multilingual_glossary_from_csv()`,
597+
`update_multilingual_glossary()`, `update_multilingual_glossary_name()`,
598+
`update_multilingual_glossary_dictionary()`,
599+
`update_multilingual_glossary_dictionary_from_csv()`,
600+
`replace_multilingual_glossary_dictionary()` and
601+
`replace_multilingual_glossary_dictionary_from_csv()`) also accept
602+
`extra_body_parameters`: a dictionary of additional fields for the JSON request
603+
body. They are added last and replace fields with the same key.
604+
566605
```python
567606
# Update glossary dictionary
568607
entries = {"artist": "Maler", "hello": "guten tag"}
@@ -578,8 +617,8 @@ updated_glossary = deepl_client.update_multilingual_glossary_dictionary(
578617
glossary_dict
579618
)
580619

581-
entries_response = deepl_client.get_multilingual_glossary_entries(my_glossary, "EN", "DE")
582-
print(entries_response.dictionaries[0]) # "{'artist': 'Maler', 'hello': 'hallo', 'prize': 'Gewinn'}"
620+
dictionary = deepl_client.get_multilingual_glossary_dictionary_entries(my_glossary, "EN", "DE")
621+
print(dictionary.entries) # "{'artist': 'Maler', 'hello': 'hallo', 'prize': 'Gewinn'}"
583622

584623
# Update a glossary dictionary from CSV
585624
# Open the CSV file assuming UTF-8 encoding. If your file contains a BOM,
@@ -590,7 +629,7 @@ with open('/path/to/glossary_file.csv', 'r', encoding='utf-8') as csv_file:
590629
glossary="4c81ffb4-2e...",
591630
source_lang="EN",
592631
target_lang="DE",
593-
csv_data=csv_data,
632+
csv=csv_data,
594633
)
595634

596635
# Replace glossary dictionary
@@ -599,8 +638,8 @@ glossary_dict = MultilingualGlossaryDictionaryEntries("EN", "DE", replacement_en
599638
updated_glossary = deepl_client.replace_multilingual_glossary_dictionary(
600639
my_glossary,
601640
glossary_dict)
602-
entries_response = deepl_client.get_multilingual_glossary_entries(my_glossary, "EN", "DE")
603-
print(entries_response.dictionaries[0]) # "{'goodbye': 'Auf Wiedersehen'}"
641+
dictionary = deepl_client.get_multilingual_glossary_dictionary_entries(my_glossary, "EN", "DE")
642+
print(dictionary.entries) # "{'goodbye': 'Auf Wiedersehen'}"
604643

605644
# Replace a glossary dictionary from CSV
606645
# Open the CSV file assuming UTF-8 encoding. If your file contains a BOM,
@@ -611,7 +650,7 @@ with open('/path/to/glossary_file.csv', 'r', encoding='utf-8') as csv_file:
611650
glossary="4c81ffb4-2e...",
612651
source_lang="EN",
613652
target_lang="DE",
614-
csv_data=csv_data,
653+
csv=csv_data,
615654
)
616655

617656
# Update the glossary name
@@ -620,6 +659,13 @@ updated_glossary = deepl_client.update_multilingual_glossary_name(
620659
"My new glossary name"
621660
)
622661
print(updated_glossary.name) # 'My new glossary name'
662+
663+
# Rename the glossary and merge entries in one request
664+
updated_glossary = deepl_client.update_multilingual_glossary(
665+
my_glossary,
666+
name="My renamed glossary",
667+
dictionaries=[MultilingualGlossaryDictionaryEntries("EN", "DE", {"cat": "Katze"})],
668+
)
623669
```
624670

625671
#### Using a stored glossary

‎deepl/__init__.py‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@
4040
from . import http_client # noqa
4141

4242
from .api_data import ( # noqa
43+
MultilingualGlossaryDictionaryEntries,
44+
MultilingualGlossaryDictionaryInfo,
45+
MultilingualGlossaryInfo,
4346
SpokenTerms,
4447
SpokenTermsEntries,
4548
SpokenTermsList,
@@ -91,6 +94,9 @@
9194
"Formality",
9295
"GlossaryInfo",
9396
"Language",
97+
"MultilingualGlossaryDictionaryEntries",
98+
"MultilingualGlossaryDictionaryInfo",
99+
"MultilingualGlossaryInfo",
94100
"SplitSentences",
95101
"SpokenTerms",
96102
"SpokenTermsEntries",

0 commit comments

Comments
 (0)