diff --git a/README.md b/README.md index 95b1c4b..0c0e906 100644 --- a/README.md +++ b/README.md @@ -59,9 +59,16 @@ In [2]: apertium.append_pair_path('..') ### Translation Performing Translations +Method 1: ```python In [1]: import apertium In [2]: t = apertium.Translator('eng', 'spa') In [3]: t.translate('cats') Out[3]: 'Gatos' ``` +Method 2: +```python +In [1]: import apertium +In [2]: apertium.translate('eng', 'spa', 'I love you') +Out[2]: 'Te quieres' +``` diff --git a/apertium/__init__.py b/apertium/__init__.py index fc8d119..7d483fd 100644 --- a/apertium/__init__.py +++ b/apertium/__init__.py @@ -12,8 +12,16 @@ class ModeNotInstalled(ValueError): pass -def update_modes(pair_path): # type: (str) -> None - modes = search_path(pair_path) +def update_modes(path): # type: (str) -> None + """Updates the install modes + + Args: + path(str): A string that is the absolute location to the modes to be installed + + Yelids: + Updates the pairs, analyzers, generator dictionaries with entries + """ + modes = search_path(path) if modes['pair']: for path, lang_src, lang_trg in modes['pair']: pairs['%s-%s' % (lang_src, lang_trg)] = path diff --git a/apertium/analysis/__init__.py b/apertium/analysis/__init__.py index b445b1d..22ee585 100644 --- a/apertium/analysis/__init__.py +++ b/apertium/analysis/__init__.py @@ -8,7 +8,20 @@ class Analyzer: + """An Analyzer object containing it's analysis mode and langugage + + Attributes: + analyzer_cmds (Dict[str, List[List[str]]]): stores the commands for various analyzers to run succesfully. + lang (str): Language of the text which is morphologically analyzed. + path (str): Location to the analyzer mode for a particular language. + mode (str): Name of the mode that for a particular lingustic task. + """ def __init__(self, lang): # type: (Analyzer, str) -> None + """initializes the Analyzer object + + Args: + lang (str): Language of the morphological analyzer + """ self.analyzer_cmds = {} # type: Dict[str, List[List[str]]] self.lang = to_alpha3_code(lang) # type: str if self.lang not in apertium.analyzers: @@ -17,21 +30,24 @@ def __init__(self, lang): # type: (Analyzer, str) -> None self.path, self.mode = apertium.analyzers[self.lang] def _get_commands(self): # type: (Analyzer) -> List[List[str]] + """ + Yeilds: the commands to run for the analysis mode + """ if self.lang not in self.analyzer_cmds: mode_path, mode = apertium.analyzers[self.lang] self.analyzer_cmds[self.lang] = parse_mode_file(mode_path+'/modes/'+mode+'.mode') return self.analyzer_cmds[self.lang] def _postproc_text(self, result): # type: (Analyzer, str) -> List[LexicalUnit] - """ - postprocesses the input - """ lexical_units = list(parse(result)) return lexical_units def analyze(self, in_text, formatting='txt'): # type: (Analyzer, str, str) -> List[LexicalUnit] - """ - runs apertium to analyze the input + """runs apertium to analyze the input + + Args: + in_text (str): The text who's morphological analysis has to be generated + formatting (str): The type of formatting for the output of the analysis """ commands = [['apertium', '-d', self.path, '-f', formatting, self.mode]] result = execute(in_text, commands) @@ -39,5 +55,7 @@ def analyze(self, in_text, formatting='txt'): # type: (Analyzer, str, str) -> L def analyze(lang, in_text, formatting='txt'): # type: (str, str, str) -> List[LexicalUnit] + """directly returns the analysis from apertium + """ analyzer = Analyzer(lang) return analyzer.analyze(in_text, formatting) diff --git a/apertium/generation/__init__.py b/apertium/generation/__init__.py index 470fbfe..6bb2e83 100644 --- a/apertium/generation/__init__.py +++ b/apertium/generation/__init__.py @@ -8,17 +8,43 @@ class Generator: + """An Generator object containing it's generation mode and langugage. The language is taken as input + and then all the generators corresponding to the particular language that are installed are looked up + and used. + + Attributes: + generator_cmds (Dict[str, List[List[str]]]): stores the commands for various generators to run succesfully. + lang (str): Language of the text which is morphologically generated. + """ def __init__(self, lang): # type: (Generator, str) -> None self.generator_cmds = {} # type: Dict[str, List[List[str]]] self.lang = lang # type: str def _get_commands(self): # type: (Generator) -> List[List[str]] + """returns the commands to run for the generation + + Args: + Object of class Generator + + Yeilds: + A List[List[str]] having the commands that need to be run for the particular mode execution. + """ if self.lang not in self.generator_cmds: mode_path, mode = apertium.generators[self.lang] self.generator_cmds[self.lang] = parse_mode_file(mode_path+'/modes/'+mode+'.mode') return self.generator_cmds[self.lang] def generate(self, in_text, formatting='none'): # type: (Generator, str, str) -> Union[str, List[str]] + """generates the word form for the analysis provided + + Args: + in_text (str): The analysis from which a wordform has to be generated + formatting (str): The output format of the generated wordform + + Yields: + List[str] of the output of correct wordform/wordforms of the input. + + """ self.lang = to_alpha3_code(self.lang) if self.lang in apertium.generators: @@ -30,5 +56,7 @@ def generate(self, in_text, formatting='none'): # type: (Generator, str, str) - def generate(lang, in_text, formatting='none'): # type: (str, str, str) -> Union[str, List[str]] + """directly returns the generated output from apertium + """ generator = Generator(lang) return generator.generate(in_text, formatting) diff --git a/apertium/translation/__init__.py b/apertium/translation/__init__.py index d7f41b1..69909cc 100644 --- a/apertium/translation/__init__.py +++ b/apertium/translation/__init__.py @@ -9,12 +9,29 @@ class Translator: + """An Translator object containing it's translation mode and the language pair. The language pair is taken as input + and then the translator corresponding to the particular language that are installed are looked up + and used. + + Attributes: + translation_cmds (Dict[str, List[List[str]]]): stores the commands for various translators to run succesfully. + l1 (str): The language in which the input text is provided + l2 (str): The language in which the input text is to be translated. + """ def __init__(self, l1, l2): # type: (Translator, str, str) -> None self.translation_cmds = {} # type: Dict[Tuple[str, str], List[List[str]]] self.l1 = l1 self.l2 = l2 def _get_commands(self, l1, l2): # type: (Translator, str, str) -> List[List[str]] + """returns the commands to run for the translation + + Args: + Object of class Translator + + Yeilds: + A List[List[str]] having the commands that need to be run for the particular mode execution. + """ if (l1, l2) not in self.translation_cmds: mode_path = apertium.pairs['%s-%s' % (l1, l2)] self.translation_cmds[(l1, l2)] = parse_mode_file(mode_path) @@ -22,6 +39,9 @@ def _get_commands(self, l1, l2): # type: (Translator, str, str) -> List[List[st def _get_format(self, format, deformat, reformat): # type: (Translator, Optional[str], Optional[str], Optional[str]) -> Tuple[Optional[str], Optional[str]] + """ + returns the appropriate deformat and reformat arguments + """ if format: deformat = 'apertium-des' + format reformat = 'apertium-re' + format @@ -34,11 +54,17 @@ def _get_format(self, format, deformat, reformat): return deformat, reformat def _check_ret_code(self, proc): # type: (Translator, Popen) -> None + """ + validates if the process was executed succesfully + """ if proc.returncode != 0: raise CalledProcessError() # type: ignore def _validate_formatters(self, deformat, reformat): # type: (Translator, Optional[str], Optional[str]) -> Tuple[Union[str, object], Union[str, object]] + """ + returns validated formatting arguments + """ def valid1(elt, lst): # type: (Optional[str], List[object]) -> Union[str, object] if elt in lst: return elt @@ -84,6 +110,13 @@ def _get_reformat(self, reformat, text): # type: (Translator, str, str) -> str def translate(self, text, mark_unknown=False, format=None, deformat='txt', reformat='txt'): # type: (Translator, str, bool, Optional[str], str, str) -> str + """ + Args: + text (str): The text to be translated from l1 to l2 + + Yeilds: + str for the translated text + """ if '%s-%s' % tuple(map(to_alpha3_code, [self.l1, self.l2])) in apertium.pairs: # type: ignore pair = map(to_alpha3_code, [self.l1, self.l2]) else: @@ -102,5 +135,8 @@ def translate(self, text, mark_unknown=False, format=None, deformat='txt', refor def translate(l1, l2, text, mark_unknown=False, format=None, deformat='txt', reformat='txt'): # type: (str, str, str, bool, Optional[str], str, str) -> str + """ + directly returns the translation from apertium + """ translator = apertium.Translator(l1, l2) return translator.translate(text, mark_unknown, format, deformat, reformat) diff --git a/apertium/utils.py b/apertium/utils.py index e25fd47..f209741 100644 --- a/apertium/utils.py +++ b/apertium/utils.py @@ -20,6 +20,15 @@ def to_alpha3_code(code): # type: (str) -> str def execute(inp, commands): # type: (str, List[List[str]]) -> str + """exectues the commands in a pipeline fashion and returns the output + + Args: + inp (str): The input to the command that is to be executed + commands (List[List[str]]): A list of the commands to be executed in pipeline manner + + Yeilds: + stringified output when the command is executed + """ procs = [] end = inp.encode() for i, command in enumerate(commands): @@ -31,6 +40,14 @@ def execute(inp, commands): # type: (str, List[List[str]]) -> str def parse_mode_file(mode_path): # type: (str) -> List[List[str]] + """parses the modefile and returns the commands to execute for a gives mode. + + Args: + mode_path (str): Path to where the modes for the language data are stored + + Yeilds: + commands (List[List[str]]): The commands that need to be run for the execution of the mode + """ mode_str = open(mode_path, 'r').read().strip() if mode_str: commands = []