pipetex.operations

  1""" Operations and utility functions used in the pipeline class
  2
  3The functions described in this module define a single operation which will be
  4executed by the pipeline object. All public functions must adhere to the same
  5signature so the pipeline can dynamically execute them one by one.
  6
  7@author: Max Weise
  8created: 23.07.2022
  9"""
 10
 11from pipetex import exceptions
 12from pipetex.enums import SeverityLevels, ConfigDictKeys
 13
 14import datetime
 15import os
 16import re
 17import shutil
 18import subprocess
 19from typing import Any, Optional, Tuple
 20
 21
 22# === Type Def ===
 23Monad = Tuple[bool, Optional[exceptions.InternalException]]
 24
 25
 26# === Preparation of file / working dir ===
 27def copy_latex_file(file_name: str, config_dict: dict[str, Any]) -> Monad:
 28    """Create a working copy of the specified latex file.
 29
 30    To avoid losing data or corrupting the latex file a copy is created. The
 31    copy can be identified by a prefix added in this function. The new file
 32    name is written in the config dict. It is the responsibility of the
 33    dict owner to update the name of the working file accordingly.
 34
 35    Args:
 36        file_name: The name of the file to be compiled. Does not contain any
 37            file extension.
 38        config_dict: Dictionary containing further settings to run the engine.
 39
 40    Returns:
 41        Monad: Tuple which contains a boolean to indicate success of the
 42            function. If its true, the second value will be None. If its
 43            false, the second value will contain an InternalException object
 44            containing further information.
 45
 46    Raises:
 47        InternalException: Indicates an internal error and is used to
 48            comunicate exceptions and how to handle them back to the calling
 49            interface.
 50            [Please see class definition]
 51        Raised Levels: CRITICAL
 52    """
 53
 54    if f"{file_name}.tex" not in os.listdir():
 55        ex = exceptions.InternalException(
 56            f"The file {file_name}.tex is not in the directory.",
 57            SeverityLevels.CRITICAL
 58        )
 59
 60        return False, ex
 61
 62    file_prefix: str = config_dict[ConfigDictKeys.FILE_PREFIX.value]
 63    new_name: str = f"{file_prefix}_{file_name}"
 64    shutil.copy(f'{file_name}.tex', f'{new_name}.tex')
 65
 66    config_dict[ConfigDictKeys.NEW_NAME.value] = new_name
 67
 68    return True, None
 69
 70
 71def remove_draft_option(file_name: str, config_dict: dict[str, Any]) -> Monad:
 72    """Removes the draft option from a tex file.
 73
 74    Each tex file contains a class definition, where additional options can
 75    be specified, including the draft option (for more info, see the project
 76    specification or the latex documentation). This function finds this option
 77    and removes it, leaving a compilable tex file.
 78
 79    Args:
 80        file_name: The name of the file to be compiled. Does not contain any
 81            file extension.
 82        config_dict: Dictionary containing further settings to run the engine.
 83
 84    Returns:
 85        Monad: Tuple which contains a boolean to indicate success of the
 86            function. If its true, the second value will be None. If its
 87            false, the second value will contain an InternalException object
 88            containing further information.
 89
 90    Raises:
 91        InternalException: Indicates an internal error and is used to comunicate
 92            exceptions and how to handle them back to the calling interface.
 93            [Please see class definition]
 94        Raised Levels: CRITICAL, LOW
 95    """
 96
 97    if f"{file_name}.tex" not in os.listdir():
 98        ex = exceptions.InternalException(
 99            f"The file {file_name}.tex is not found in the current "
100            "working directory",
101            SeverityLevels.CRITICAL
102        )
103
104        return False, ex
105
106    with open(f"{file_name}.tex", "r", encoding="utf-8") as read_file:
107        lines_of_file: list[str] = [line for line in read_file]
108
109    class_line = lines_of_file[0]
110
111    options_list = re.findall(r"\[(.+?)\]", class_line)[0].split(",")
112    doc_class = re.findall(r"\{(.+?)\}", class_line)
113
114    try:
115        options_list.pop(options_list.index(" draft"))
116    except ValueError:
117        ex = exceptions.InternalException(
118            "Draft option is not in the class definition",
119            SeverityLevels.LOW
120        )
121
122        return False, ex
123
124    options_string = "[" + ",".join(options_list) + "]"
125    doc_class = "{" + doc_class[0] + "}"
126
127    lines_of_file[0] = f"\\documentclass{options_string}{doc_class}\n"
128
129    with open(f"{file_name}.tex", "w", encoding="utf-8") as write_file:
130        write_file.writelines(lines_of_file)
131
132    return True, None
133
134
135# === Compilation / Creation of aux files / Generating LaTeX artifacts ===
136def compile_latex_file(file_name: str, config_dict: dict[str, Any]) -> Monad:
137    """Compiles the file with to create a PDF file.
138
139    Compiles a file by using a latex engine on the filename given to the
140    function.
141
142    Args:
143        file_name: The name of the file to be compiled. Does not contain any
144            file extension.
145        config_dict: Dictionary containing further settings to run the engine.
146
147    Returns:
148        Monad: Tuple which contains a boolean to indicate success of the
149            function. If its true, the second value will be None. If its
150            false, the second value will contain an InternalException object
151            containing further information.
152
153    Raises:
154        InternalException: Indicates an internal error and is used to comunicate
155            exceptions and how to handle them back to the calling interface.
156            [Please see class definition]
157        Raised Levels: CRITICAL
158    """
159
160    if f"{file_name}.tex" not in os.listdir():
161        ex = exceptions.InternalException(
162            f"The file {file_name}.tex is not found in the current "
163            "working directory",
164            SeverityLevels.CRITICAL
165        )
166
167        return False, ex
168
169    argument_list: list[str] = ["pdflatex", "-quiet", f"{file_name}.tex"]
170    if config_dict[ConfigDictKeys.VERBOSE.value]:
171        argument_list.pop(argument_list.index("-quiet"))
172
173    subprocess.call(argument_list)
174
175    return True, None
176
177
178def _is_bibfile_present() -> bool:
179    """Searches bibliography file recursively in the current working dir.
180
181    Returns:
182        bool: True, if the bibliography file is present somewhere in the
183            working dir or its subdirs."""
184    file_types: list[str] = []
185    for _, _, files in os.walk(os.getcwd()):
186        for f in files:
187            if "." in f:
188                parts = f.split(".")
189                file_types.append(parts[-1])
190
191    return "bib" in file_types
192
193
194def create_bibliograpyh(file_name: str, config_dict: dict[str, Any]) -> Any:
195    """Creates a bibliography file.
196
197    Runs a script to create a bibliography based on the entries in the main tex
198    file. This does not hinder the creation of the PDF file.  There must be a
199    .bfc file present for the script to run properly. The .bfc file is created
200    when a tex file containing bibliography entries is compiled.
201
202    Args:
203        file_name: The name of the file to be compiled. Does not contain any
204            file extension.
205        config_dict: Dictionary containing further settings to run the engine.
206
207    Returns:
208        Monad: Tuple which contains a boolean to indicate success of the
209            function. If its true, the second value will be None. If its
210            false, the second value will contain an InternalException object
211            containing further information.
212
213    Raises:
214        InternalException: Indicates an internal error and is used to comunicate
215            exceptions and how to handle them back to the calling interface.
216            [Please see class definition]
217        Raised Levels: HIGH
218    """
219    if f"{file_name}.bcf" not in os.listdir():
220        ex = exceptions.InternalException(
221            f"The file {file_name}.bcf has not been created. "
222            "Bibliography can not be created.",
223            SeverityLevels.HIGH
224        )
225
226        return False, ex
227
228    if not _is_bibfile_present():
229        ex = exceptions.InternalException(
230            "There is no bibliography file in the current project. "
231            "Cant create bibliography.",
232            SeverityLevels.HIGH
233        )
234
235        return False, ex
236
237    argument_list: list[str] = ["biber", "-q", f"{file_name}"]
238
239    if config_dict[ConfigDictKeys.VERBOSE.value]:
240        argument_list.pop(argument_list.index("-q"))
241
242    subprocess.call(argument_list)
243
244    return True, None
245
246
247def create_glossary(file_name: str, config_dict: dict[str, Any]) -> Any:
248    """Creates a glossary file.
249
250    Runs a script to create a glossary based on the entries in the main tex
251    file. This does not hinder the creation of the PDF file.  There must be a
252    .glo and .ist file present for the script to run properly. Thees files are
253    created when a tex file containing glossary entries is compiled.
254
255    Args:
256        file_name: The name of the file to be compiled. Does not contain any
257            file extension.
258        config_dict: Dictionary containing further settings to run the engine.
259
260    Returns:
261        Monad: Tuple which contains a boolean to indicate success of the
262            function. If its true, the second value will be None. If its
263            false, the second value will contain an InternalException object
264            containing further information.
265
266    Raises:
267        InternalException: Indicates an internal error and is used to comunicate
268            exceptions and how to handle them back to the calling interface.
269            [Please see class definition]
270        Raised Levels: HIGH
271    """
272    if f"{file_name}.glo" not in os.listdir():
273        ex = exceptions.InternalException(
274            f"The file {file_name}.glo has not been created. "
275            "Glossary can not be created.",
276            SeverityLevels.HIGH
277        )
278
279        return False, ex
280
281    if f"{file_name}.ist" not in os.listdir():
282        ex = exceptions.InternalException(
283            f"The file {file_name}.ist has not been created. "
284            "Glossary can not be created.",
285            SeverityLevels.HIGH
286        )
287
288        return False, ex
289
290    if f"{file_name}.aux" not in os.listdir():
291        ex = exceptions.InternalException(
292            f"The file {file_name}.aux has not been created. "
293            "Glossary can not be created.",
294            SeverityLevels.HIGH
295        )
296
297        return False, ex
298
299    argument_list: list[str] = ["makeglossaries", "-q", f"{file_name}"]
300
301    if config_dict[ConfigDictKeys.VERBOSE.value]:
302        argument_list.pop(argument_list.index("-q"))
303
304    subprocess.call(argument_list)
305
306    return True, None
307
308
309# === tear down / clean up processes ===
310def _move_pdf_file(file_name, new_file_name: Optional[str] = None) -> Monad:
311    """Moves pdf file to seperate folder.
312
313    To avoid that the created pdf file is deleted by the clean up process, this
314    function creates a dedicated folder and moves the pdf file there.
315
316    Args:
317        file_name: The name of the file to be compiled. Does not contain any
318            file extension.
319
320    Returns:
321        Monad: Tuple which contains a boolean to indicate success of the
322            function. If its true, the second value will be None. If its
323            false, the second value will contain an InternalException object
324            containing further information.
325
326    Raises:
327        InternalException: Indicates an internal error and is used to comunicate
328            exceptions and how to handle them back to the calling interface.
329            [Please see class definition]
330        Raised Levels: HIGH
331    """
332    _exeption = None
333    _successvalue = True
334
335    if not new_file_name:
336        cur_date = datetime.datetime.now()
337        formatted_date = cur_date.strftime("%Y_%m_%d_%H_%M")
338        new_file_name = f"{formatted_date}_{file_name}"
339
340    # Create Folder
341    try:
342        os.makedirs("DEPLOY")
343    except FileExistsError:
344        _exeption = exceptions.InternalException(
345            "Folder already exists. Proceed as intended.",
346            SeverityLevels.LOW
347        )
348
349        _successvalue = False
350
351    try:
352        shutil.move(f"{file_name}.pdf", "./DEPLOY")
353        old_name = os.path.join(".", "DEPLOY", f"{file_name}.pdf")
354        new_name = os.path.join(".", "DEPLOY", f"{new_file_name}.pdf")
355        os.rename(old_name, new_name)
356    except FileNotFoundError:
357        _exeption = exceptions.InternalException(
358            "The pdf document could not be found. Perhaps it was not created?",
359            SeverityLevels.CRITICAL
360        )
361
362        _successvalue = False
363
364    return _successvalue, _exeption
365
366
367def clean_working_dir(file_name: str, config_dict: dict[str, Any],
368                      new_file_name: Optional[str] = None) -> Monad:
369    """Cleans the working directory from any generated files.
370
371    Removes unwanted / redundant auxiliary files. Moves the created PDF
372    document to a specified folder.
373
374    Args:
375        file_name: The name of the file to be compiled. Does not contain any
376            file extension.
377        config_dict: Dictionary containing further settings to run the engine.
378
379    Returns:
380        Monad: Tuple which contains a boolean to indicate success of the
381            function. If its true, the second value will be None. If its
382            false, the second value will contain an InternalException object
383            containing further information.
384
385    """
386    _success: bool = True
387    _exception: Optional[exceptions.InternalException] = None
388
389    _success, _exception = _move_pdf_file(file_name, new_file_name)
390
391    if _exception and _exception.severity_level >= 20:
392        return False, _exception
393
394    for file in os.listdir():
395        if config_dict[ConfigDictKeys.FILE_PREFIX.value] in file:
396            os.remove(file)
397
398    return _success, _exception