pydocmaker.backend.ex_docx ========================== .. py:module:: pydocmaker.backend.ex_docx Attributes ---------- .. autoapisummary:: pydocmaker.backend.ex_docx.can_run_pandoc pydocmaker.backend.ex_docx.Document pydocmaker.backend.ex_docx.log pydocmaker.backend.ex_docx.gwin32 pydocmaker.backend.ex_docx.gcomposer pydocmaker.backend.ex_docx.gmailmerge Classes ------- .. autoapisummary:: pydocmaker.backend.ex_docx.msoPictureCompress pydocmaker.backend.ex_docx.DocxFileW32 pydocmaker.backend.ex_docx.DocxFile pydocmaker.backend.ex_docx.docx_renderer Functions --------- .. autoapisummary:: pydocmaker.backend.ex_docx._make_output pydocmaker.backend.ex_docx._get_bytes_file_or_buffer pydocmaker.backend.ex_docx._test_docxw32_installed pydocmaker.backend.ex_docx.can_use_w32_word pydocmaker.backend.ex_docx.can_use_libreoffice pydocmaker.backend.ex_docx.blue pydocmaker.backend.ex_docx.red pydocmaker.backend.ex_docx.convert_pandoc pydocmaker.backend.ex_docx.convert Module Contents --------------- .. py:data:: can_run_pandoc .. py:data:: Document :value: None .. py:data:: log .. py:data:: gwin32 :value: None .. py:data:: gcomposer :value: None .. py:data:: gmailmerge :value: None .. py:function:: _make_output(bts, output_path_or_buffer) .. py:function:: _get_bytes_file_or_buffer(file_path_or_buffer) .. py:function:: _test_docxw32_installed(verb=0, force_reload=False) tests if win32com and Microsoft Word is available :returns: 0 if both are available, 1 if win32com is not available 2 if win32com is available and word is not available. :rtype: int .. py:function:: can_use_w32_word(verb=0, force_reload=False) test if Microsoft Word is available and win32com library is available :param verb: whether or not to give verbose info. Defaults to 0. :type verb: int, optional :param force_reload: whether or not to force to re-test, if it has been tested before. Defaults to False. :type force_reload: bool, optional :returns: True if both are available, False if not :rtype: bool .. py:function:: can_use_libreoffice(force_reload=False) test if libreoffice is available :param force_reload: whether or not to force to re-test, if it has been tested before. Defaults to False. :type force_reload: bool, optional :returns: True if available, False if not :rtype: bool .. py:class:: msoPictureCompress(*args, **kwds) Bases: :py:obj:`enum.Enum` Enumeration of picture compression types for MS Office. .. py:attribute:: Default :value: 0 .. py:attribute:: HQPrint :value: 1 .. py:attribute:: Print :value: 2 .. py:attribute:: Email :value: 3 .. py:attribute:: Screen :value: 4 .. py:attribute:: Photo :value: 16 .. py:class:: DocxFileW32(docx_path, outpath=None) A context manager for working with DOCX files using Win32COM automation. This class provides methods to manipulate DOCX documents via Microsoft Word's COM interface, including image compression, field updates, and exporting to PDF format. It ensures proper cleanup by closing the Word application and document upon exiting the context manager. WARNING! This class needs the win32com library and word installed to work properly! .. py:method:: is_installed(verb=0, force_reload=False, ret_int=False) :staticmethod: .. py:attribute:: docx_path :value: b'.' .. py:attribute:: outpath :value: None .. py:attribute:: word :value: None .. py:attribute:: worddoc :value: None .. py:attribute:: _created_word_app :value: False .. py:method:: __enter__() Enter the runtime context for the DocxFileW32 instance. if "win32com.client" is not available it will be imported. :returns: The instance itself for use in a 'with' statement. :rtype: DocxFileW32 .. py:method:: compress_images(compressionQuality=msoPictureCompress.Screen) Compress all images within the document based on specified quality settings. :param compressionQuality: The compression level to apply to images. Defaults to msoPictureCompress.Screen (quality 4). :type compressionQuality: msoPictureCompress or int :returns: The instance itself to allow method chaining. :rtype: DocxFileW32 .. py:method:: update_fields() Update all fields in the document, including those in headers and footers. :returns: The instance itself to allow method chaining. :rtype: DocxFileW32 .. py:method:: export(pdf_path=None, optimize_for_screen=True) Export the document to PDF format with specified options. :param pdf_path: The path where the PDF will be saved. If None, uses outpath. :type pdf_path: str, optional :param optimize_for_screen: True for wdExportOptimizeForOnScreen (=1) else wdExportOptimizeForPrint (=0). :type optimize_for_screen: bool :returns: The instance itself to allow method chaining. :rtype: DocxFileW32 :raises AssertionError: If pdf_path is None and outpath is also None. .. py:method:: save() .. py:method:: close() .. py:method:: __exit__(exc_type, exc_value, traceback) Exit the runtime context for the DocxFileW32 instance, saving and closing resources. :param exc_type: Exception type (if any) that occurred during execution. :param exc_value: Exception value (if any) that occurred during execution. :param traceback: Traceback object (if any) that occurred during execution. .. py:class:: DocxFile(file_path_or_buffer) A class to handle operations on DOCX files such as appending multiple documents, replacing fields, and saving the modified document. .. py:attribute:: file_path_or_buffer .. py:attribute:: docx_data .. py:attribute:: inp_data .. py:method:: _get_bytes_file_or_buffer(file_path_or_buffer) Retrieve bytes from a file path or buffer. :param file_path_or_buffer: Path to the DOCX file or a buffer containing DOCX data. :return: Bytes of the DOCX file. .. py:method:: append(*files, verb=0) -> bytes Append multiple Word (.docx) documents into a single document. :param files: Variable length argument list of either (bytes, or file paths, or buffers) to be appended. :param verb: Verbosity level (0 for silent, 1 for verbose). :return: The current instance of DocxFile with the appended DOCX data. .. py:method:: replace_fields(replace_dict) Replace all MergeFields of a DOCX file with given text in form of a dict. :param replace_dict: Dictionary where keys are field names and values are replacement texts. :return: The current instance of DocxFile with the replaced fields. .. py:method:: get_fields() Retrieve the merge fields from the DOCX document. :returns: A list of merge fields present in the DOCX document. :rtype: list .. py:method:: replace_keywords(replace_dict) Edit raw XML content of a DOCX file by replacing specified strings using python-docx. :param replace_dict: Dictionary where keys are strings to be replaced and values are replacement strings. :return: The current instance of DocxFile with the replaced keywords. .. py:method:: replace_keywords_raw(replace_dict) Edit raw XML content of a DOCX file by replacing specified strings in all XML files within the document. :param replace_dict: Dictionary where keys are strings to be replaced and values are replacement strings. :return: The current instance of DocxFile with the replaced keywords in raw XML. .. py:method:: save(output_path_or_buffer=None) Save the modified DOCX data to a file or buffer. :param output_path_or_buffer: File path or buffer to save the DOCX data. :return: The current instance of DocxFile. .. py:function:: blue(run) .. py:function:: red(run) .. py:function:: convert_pandoc(doc: List[dict]) -> bytes .. py:function:: convert(doc: List[dict], template=None, template_params=None, use_w32=False, as_pdf=False, compress_images=False, filename=None, allow_pandoc=True, **kwargs) -> bytes Convert a list of document sections into a DOCX or PDF (via docx) file using a specified template. Parameters: - doc (List[dict]): The document content structured as a list of dictionaries. - template (str, optional): Path to a DOCX template file. Defaults to None. - template_params (dict, optional): Parameters to replace fields in the template. Defaults to None. - use_w32 (bool, optional): Whether to use win32com for document field updating and any of the following arguments, THIS OPTION NEEDS win32com and word installed. Defaults to False. - as_pdf (bool, optional): Whether to output the document as a PDF (via docx and win32com). Defaults to False. - compress_images (bool, optional): Whether to compress images in the document using win32com. Defaults to False. - filename (str, optional): The optional filename to give the document in case saving it as a tempfile is necessary. Default will try to get from metadata and if not found use tempfile.docx. - allow_pandoc (bool, optional): whether or not to allow the usage of pandoc instead of python-docx (usually pandoc creates nicer documents!) - **kwargs: only used to check if invalid keyword arguments were passed. Returns: - bytes: The byte content of the generated DOCX or PDF file. Raises: - ValueError: If attempting to export to PDF without win32com and Word.Application installed and use_w32 set to True. .. py:class:: docx_renderer(template_path: str = None, make_blue=False) Bases: :py:obj:`pydocmaker.backend.baseformatter.BaseFormatter` Helper class that provides a standard way to create an ABC using inheritance. .. py:attribute:: d .. py:attribute:: make_blue :value: False .. py:method:: add_paragraph(newtext, *args, **kwargs) .. py:method:: add_run(text, *args, **kwargs) .. py:method:: digest_text(children, *args, **kwargs) .. py:method:: digest_str(children, *args, **kwargs) .. py:method:: digest_line(children, *args, **kwargs) .. py:method:: digest_markdown(children, *args, **kwargs) .. py:method:: digest_verbatim(children, *args, **kwargs) .. py:method:: digest_latex(children, *args, **kwargs) .. py:method:: handle_error(err, el=None) -> list .. py:method:: digest_iterator(children, *args, **kwargs) .. py:method:: digest_table(children=None, **kwargs) -> str .. py:method:: digest_image(children, *args, **kwargs) .. py:method:: format(*args, **kwargs) :abstractmethod: .. py:method:: doc_to_bytes() .. py:method:: save(filepath)