From 11c62b090b96ce49bcf7e02f671ae30a7dd9391c Mon Sep 17 00:00:00 2001 From: Ad5001 Date: Fri, 3 Nov 2023 01:33:56 +0100 Subject: [PATCH] Updating documentation --- .gitignore | 1 + README.md | 26 ++++++++++ build-doc.sh | 6 +++ pybergamot/__init__.py | 5 ++ pybergamot/engine.py | 26 +++++++--- pybergamot/models.py | 41 ++++++++++++---- pybergamot/translator.py | 103 +++++++++++++++++++++++++-------------- 7 files changed, 155 insertions(+), 53 deletions(-) create mode 100755 build-doc.sh diff --git a/.gitignore b/.gitignore index 30b0ba0..dca6b08 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ */*.pyc */__pycache__ +html .idea .coverage .pytest_cache diff --git a/README.md b/README.md index 5208a80..f465da2 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,29 @@ # pybergamot (Somewhat) stable interface for the **Bergamot Translation Engine Python Bindings**. + +## Generate documentation + +Documentation for `pybergamot` can be generated using [pdoc](https://pdoc.dev). + +Use the script `build-doc.sh` to generate the documentation directly. + +## Legal + + pybergamot - (Somewhat) stable interface for the **Bergamot Translation Engine Python Bindings**. + Copyright (C) 2023 Ad5001 + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +This project is not affiliated to the Bergamot Project or Mozilla. \ No newline at end of file diff --git a/build-doc.sh b/build-doc.sh new file mode 100755 index 0000000..8ebf4ba --- /dev/null +++ b/build-doc.sh @@ -0,0 +1,6 @@ +#!/usr/bin/env bash +python3 -m pdoc --force --html pybergamot + +cd html/pybergamot || exit + +python3 -m http.server 8080 diff --git a/pybergamot/__init__.py b/pybergamot/__init__.py index 546c41b..70aa347 100644 --- a/pybergamot/__init__.py +++ b/pybergamot/__init__.py @@ -1 +1,6 @@ +""" +Welcome to pybergamot! + + +""" from .translator import Translator diff --git a/pybergamot/engine.py b/pybergamot/engine.py index dc38385..aa5af7c 100644 --- a/pybergamot/engine.py +++ b/pybergamot/engine.py @@ -46,18 +46,27 @@ class Engine(ABC): def translate(self, text: str, html: bool = False, alignment: bool = False, quality_scores: bool = False) -> str: """ Translates the text from the engine's source lang its target. - :param text: Text to translate. - :param html: Set to True if the text contains an HTML structure which needs to - be preserved while translated. - :param alignment: Toggle for alignment. - :param quality_scores: Toggle for whether to include the translation's quality scores - for each word in HTML format. - :return: The translated text. + + ## Parameters + --- + - **text**: Text to translate. + - **html**: Set to True if the text contains an HTML structure which needs to + be preserved while translated. + - **alignment**: Toggle for alignment. + - **quality_scores**: Toggle for whether to include the translation's quality scores + for each word in HTML format. + + ## Returns + --- + The translated text. """ pass class DirectBergamotModelEngine(Engine): + """ + Internal module. Engine using a single bergamot model to translate. + """ def __init__(self, source_lang: str, target_lang: str, model: TranslationModel, service: Service): self._source_lang = source_lang @@ -82,6 +91,9 @@ class DirectBergamotModelEngine(Engine): class ChainBergamotModelsEngine(Engine): + """ + Internal module. Engine chaining two bergamot model to translate. + """ def __init__(self, source_lang: str, target_lang: str, model1: TranslationModel, model2: TranslationModel, service: Service): self._source_lang = source_lang diff --git a/pybergamot/models.py b/pybergamot/models.py index 320d403..5d8ad36 100644 --- a/pybergamot/models.py +++ b/pybergamot/models.py @@ -64,10 +64,19 @@ class Models: def get_model_languages(model_name: str) -> tuple: """ Returns a tuple of two two-char ISO language name which the model translates from and to. - :param model_name: Name of the model - :raises: - ValueError: When the model_name doesn't exist. - :return: (from language, to language) + + ## Parameters + --- + - **model_name**: Name of the model + + ## Exceptions + --- + - `ValueError`: When the model_name doesn't exist. + + ## Returns + --- + (from language, to language) + """ if model_name not in Models.AVAILABLE: raise ValueError(f"Model {model_name} does not exist. Did you update the repository cache?") @@ -83,9 +92,16 @@ class Models: def get_model_name_for_languages(source_lang: str, target_lang: str) -> str | None: """ Finds a model which translates source_lang into target_lang. - :param source_lang: Language to translate from. - :param target_lang: Language to translate to. - :return: None if no model was found, name of the model otherwise. + + ## Parameters + --- + - **source_lang**: Language to translate from. + - **target_lang**: Language to translate to. + + ## Returns + --- + None if no model was found, name of the model otherwise. + """ lang_tuple = (source_lang, target_lang) names = list(filter(lambda name: lang_tuple == Models.get_model_languages(name), Models.AVAILABLE)) @@ -99,9 +115,14 @@ class Models: def download(model_name: str) -> None: """ Downloads or updates the given model. - :param model_name: Name of the model to download. - :raises: - ValueError: When the model_name doesn't exist. + + ## Parameters + --- + - **model_name**: Name of the model to download. + + ## Exceptions + --- + - `ValueError`: When the model_name doesn't exist. """ if model_name not in Models.AVAILABLE: raise ValueError(f"Model {model_name} does not exist. Did you update the repository cache?") diff --git a/pybergamot/translator.py b/pybergamot/translator.py index ad1a850..c4f490b 100644 --- a/pybergamot/translator.py +++ b/pybergamot/translator.py @@ -27,17 +27,21 @@ class Translator: """ Main exposed class to provide translation using Bergamot. Workflow goes as follows: + 1. Create instance 2. Load languages 3. Use translation between any of the loaded language. """ - def __init__(self, workers_count = 1, cache_size = 0, log_level = 'off'): + def __init__(self, workers_count=1, cache_size=0, log_level='off'): """ Creates a Translator instance. - :param workers_count: Number of workers which can be used at once. - :param cache_size: Size of the cache used in bergamot.. - :param log_level: Level of logs used in bergamot. + + ## Parameters + --- + - **workers_count**: Number of workers which can be used at once. + - **cache_size**: Size of the cache used in bergamot. + - **log_level**: Level of logs used in bergamot. """ self.loaded_languages = [] self._loaded_engines = {} @@ -47,13 +51,21 @@ class Translator: def _load_model(self, model_name: str, download: bool = True) -> TranslationModel: """ Loads a tiny model by its name, downloads it if it doesn't exist. - :param model_name: Name of the model to load. - :param download: If a model does not exist locally, if True, download it, - otherwise emit an error. - :raises: - ValueError: If the provided model does not exist. - EnvironmentError: When a model is unavailable and download has been set to false. - :return: Bergamot translation model instance. + + ## Parameters + --- + - **model_name**: Name of the model to load. + - **download**: If a model does not exist locally, if True, download it, + otherwise emit an error. + + ## Exceptions + --- + - `ValueError`: If the provided model does not exist. + - `EnvironmentError`: When a model is unavailable and download has been set to false. + + ## Returns + --- + Bergamot translation model instance. """ if model_name not in Models.AVAILABLE: raise ValueError(f"Model {model_name} not available.") @@ -71,14 +83,22 @@ class Translator: def _create_engine(self, source_lang: str, target_lang: str, download: bool = True) -> Engine: """ Creates an Engine to translate a source lang to a target lang. - :param source_lang: Language to translate from. - :param target_lang: Language to translate to. - :param download: If a model does not exist locally, if True, download it, - otherwise emit an error. - :raises: - ValueError: If a model from a lang to english does not exist. - EnvironmentError: When a model is unavailable and download has been set to false. - :return: Engine instance. + + ## Parameters + --- + - **source_lang**: Language to translate from. + - **target_lang**: Language to translate to. + - **download**: If a model does not exist locally, if True, download it, + otherwise emit an error. + + ## Exceptions + --- + - `ValueError`: If a model from a lang to english does not exist. + - `EnvironmentError`: When a model is unavailable and download has been set to false. + + ## Returns + --- + Engine instance. """ direct_model_name = Models.get_model_name_for_languages(source_lang, target_lang) if direct_model_name is not None and (download or direct_model_name in Models.INSTALLED): @@ -107,12 +127,16 @@ class Translator: Loads a language code and all the associated models (for already added languages) into the translator. - :param lang: Two-char ISO language name. - :param download: If a model does not exist locally, if True, download it, - otherwise emit an error. - :raises: - ValueError: If a model from a lang to english does not exist. - EnvironmentError: When a model is unavailable and download has been set to false. + ## Parameters + --- + - **lang**: Two-char ISO language name. + - **download**: If a model does not exist locally, if True, download it, + otherwise emit an error. + + ## Exceptions + --- + - `ValueError`: If a model from a lang to english does not exist. + - `EnvironmentError`: When a model is unavailable and download has been set to false. """ if lang not in Models.LANGS: raise ValueError(f"Language {lang} does not exist.") @@ -136,20 +160,27 @@ class Translator: """ Translates a text from a source lang to a target lang. - :param source_lang: Language to translate from. - :param target_lang: Language to translate to. - :param text: Text to translate. - :param html: Set to True if the text contains an HTML structure which needs to - be preserved while translated. - :param alignment: Toggle for alignment. - :param quality_scores: Toggle for whether to include the translation's quality scores + ## Parameters + --- + - **source_lang**: Language to translate from. + - **target_lang**: Language to translate to. + - **text**: Text to translate. + - **html**: Set to True if the text contains an HTML structure which needs to + be preserved while translated. + - **alignment**: Toggle for alignment. + - **quality_scores**: Toggle for whether to include the translation's quality scores for each word in HTML format. - :raises: - ValueError: Either source_lang or target_lang haven't been loaded yet. - :return: The translated text. + + ## Exceptions + --- + - `ValueError` Either source_lang or target_lang haven't been loaded yet. + + ## Returns + --- + The translated text. """ if source_lang not in self.loaded_languages: raise ValueError(f"Language {source_lang} is not loaded. Use the load() function first.") if target_lang not in self.loaded_languages: raise ValueError(f"Language {target_lang} is not loaded. Use the load() function first.") - return self._loaded_engines[source_lang][target_lang].translate(text, html, alignment, quality_scores) \ No newline at end of file + return self._loaded_engines[source_lang][target_lang].translate(text, html, alignment, quality_scores)