From 720692bd8971945afc249ecb3bbb14a084159274 Mon Sep 17 00:00:00 2001 From: vagrant Date: Sun, 8 Jul 2018 10:58:40 +0000 Subject: [PATCH 1/2] improved docstrings --- README.md | 7 +++++++ apertium/__init__.py | 7 +++++-- apertium/analysis/__init__.py | 9 +++++++++ apertium/generation/__init__.py | 12 ++++++++++++ apertium/translation/__init__.py | 21 +++++++++++++++++++++ apertium/utils.py | 6 ++++++ 6 files changed, 60 insertions(+), 2 deletions(-) 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..fa7c549 100644 --- a/apertium/__init__.py +++ b/apertium/__init__.py @@ -12,8 +12,11 @@ class ModeNotInstalled(ValueError): pass -def update_modes(pair_path): # type: (str) -> None - modes = search_path(pair_path) +def update_modes(path): # type: (str) -> None + """ + takes a path as input and returns updates the installed modes + """ + 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..1f3c66d 100644 --- a/apertium/analysis/__init__.py +++ b/apertium/analysis/__init__.py @@ -9,6 +9,9 @@ class Analyzer: def __init__(self, lang): # type: (Analyzer, str) -> None + """ + initializes the Analyzer object + """ 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,6 +20,9 @@ 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]] + """ + returns the commands to run for the analysis + """ 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') @@ -39,5 +45,8 @@ 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..4057c49 100644 --- a/apertium/generation/__init__.py +++ b/apertium/generation/__init__.py @@ -9,16 +9,25 @@ class Generator: def __init__(self, lang): # type: (Generator, str) -> None + """ + initializes the Generator object + """ 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 analysis + """ 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]] + """ + returns the generated output from the morphological analysis provided + """ self.lang = to_alpha3_code(self.lang) if self.lang in apertium.generators: @@ -30,5 +39,8 @@ 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..86986e8 100644 --- a/apertium/translation/__init__.py +++ b/apertium/translation/__init__.py @@ -10,11 +10,17 @@ class Translator: def __init__(self, l1, l2): # type: (Translator, str, str) -> None + """ + initializes the Translator object + """ 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 analysis + """ 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 +28,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 +43,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 +99,9 @@ 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 + """ + returns 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 +120,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..bf2bfcf 100644 --- a/apertium/utils.py +++ b/apertium/utils.py @@ -20,6 +20,9 @@ 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 + """ procs = [] end = inp.encode() for i, command in enumerate(commands): @@ -31,6 +34,9 @@ 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 + """ mode_str = open(mode_path, 'r').read().strip() if mode_str: commands = [] From 3ad1027d44b08e26103f2bc1e0481cc0691fabda Mon Sep 17 00:00:00 2001 From: vagrant Date: Tue, 24 Jul 2018 09:32:03 +0000 Subject: [PATCH 2/2] Docstrings Updated --- apertium/__init__.py | 9 +++++++-- apertium/analysis/__init__.py | 29 +++++++++++++++++---------- apertium/generation/__init__.py | 34 +++++++++++++++++++++++--------- apertium/translation/__init__.py | 27 +++++++++++++++++++------ apertium/utils.py | 19 ++++++++++++++---- 5 files changed, 87 insertions(+), 31 deletions(-) diff --git a/apertium/__init__.py b/apertium/__init__.py index fa7c549..7d483fd 100644 --- a/apertium/__init__.py +++ b/apertium/__init__.py @@ -13,8 +13,13 @@ class ModeNotInstalled(ValueError): def update_modes(path): # type: (str) -> None - """ - takes a path as input and returns updates the installed modes + """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']: diff --git a/apertium/analysis/__init__.py b/apertium/analysis/__init__.py index 1f3c66d..22ee585 100644 --- a/apertium/analysis/__init__.py +++ b/apertium/analysis/__init__.py @@ -8,9 +8,19 @@ 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 + """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 @@ -21,7 +31,7 @@ def __init__(self, lang): # type: (Analyzer, str) -> None def _get_commands(self): # type: (Analyzer) -> List[List[str]] """ - returns the commands to run for the analysis + Yeilds: the commands to run for the analysis mode """ if self.lang not in self.analyzer_cmds: mode_path, mode = apertium.analyzers[self.lang] @@ -29,15 +39,15 @@ def _get_commands(self): # type: (Analyzer) -> List[List[str]] 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) @@ -45,8 +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 + """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 4057c49..6bb2e83 100644 --- a/apertium/generation/__init__.py +++ b/apertium/generation/__init__.py @@ -8,16 +8,26 @@ 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 - """ - initializes the Generator object - """ 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 analysis + """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] @@ -25,8 +35,15 @@ def _get_commands(self): # type: (Generator) -> List[List[str]] return self.generator_cmds[self.lang] def generate(self, in_text, formatting='none'): # type: (Generator, str, str) -> Union[str, List[str]] - """ - returns the generated output from the morphological analysis provided + """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) @@ -39,8 +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 + """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 86986e8..69909cc 100644 --- a/apertium/translation/__init__.py +++ b/apertium/translation/__init__.py @@ -9,17 +9,28 @@ 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 - """ - initializes the Translator object - """ 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 analysis + """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)] @@ -100,7 +111,11 @@ 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 """ - returns the translated text + 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]) diff --git a/apertium/utils.py b/apertium/utils.py index bf2bfcf..f209741 100644 --- a/apertium/utils.py +++ b/apertium/utils.py @@ -20,8 +20,14 @@ 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 + """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() @@ -34,8 +40,13 @@ 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 + """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: