pydocmaker.templating ===================== .. py:module:: pydocmaker.templating Attributes ---------- .. autoapisummary:: pydocmaker.templating.default_template_dir pydocmaker.templating.registered_template_dirs pydocmaker.templating.res Classes ------- .. autoapisummary:: pydocmaker.templating.TemplateDirSource pydocmaker.templating.DocTemplate Functions --------- .. autoapisummary:: pydocmaker.templating.register_new_template_dir pydocmaker.templating.remove_from_template_dir pydocmaker.templating.get_registered_template_dirs pydocmaker.templating.test_template_exists pydocmaker.templating.get_available_template_ids Module Contents --------------- .. py:data:: default_template_dir .. py:data:: registered_template_dirs .. py:function:: register_new_template_dir(new_template_dir: str, check_exists=True) -> bool Register a new template directory. :param new_template_dir: The path to the new template directory. :type new_template_dir: str :param check_exists: Whether to check if the directory exists. Defaults to True. :type check_exists: bool, optional :raises FileNotFoundError: If the directory does not exist and check_exists is True. :returns: True if the directory was successfully registered, False otherwise. :rtype: bool .. py:function:: remove_from_template_dir(to_remove: str) -> bool Removes an existing template directory if it exists. :param to_remove: The path to remove from the template dirs. :type to_remove: str :returns: Always True :rtype: bool .. py:function:: get_registered_template_dirs(include_default=True) Returns a list of registered template directories. :param include_default: Whether to include the default template directory. Defaults to True. :type include_default: bool, optional :returns: A list of registered template directories. If include_default is True, the default template directory is the first element in the list. :rtype: list .. py:function:: test_template_exists(template_id, tformat='', template_dir=None) tests if a template with a given id and optional in a given format exists :param template_id: the template id to search for e.G. 'base' :type template_id: str :param tformat: optinal the template format to look for (either 'tex', or 'html') if nothing is given the first found template with that name independent of the format is returned. Defaults to ''. :type tformat: str, optional :param template_dir: if this is given only the given template directory is mounted to load jinja templates. Defaults to ''. :type template_dir: str, optional :returns: True if found False otherwise :rtype: bool .. py:function:: get_available_template_ids(template_dir=None) This function retrieves the template IDs from the list of templates. :returns: A list of template IDs, which are the names of the templates without the file extension. :rtype: list .. py:class:: TemplateDirSource(template_dirs: List[str] = None) A class used to manage templates, parameters, and attachments from a specified directory. ... .. attribute:: template_dir a string representing the directory path where the templates are located :type: str .. attribute:: env an Environment object from the jinja2 library used to load templates :type: Environment .. method:: get_params(templates=None) Returns a dictionary of parameters for the specified templates. .. method:: get_templates() Returns a dictionary of templates in the directory. .. method:: get_template_ids() Returns a list of template IDs. .. method:: get_attachments(templates=None) Returns a dictionary of attachments for the specified templates. .. method:: get_all(load_params=True, load_attachments=True) Returns a tuple containing dictionaries of templates, parameters, and attachments. .. method:: resolve_template_id(my_template_id) Returns the full template name corresponding to the given template ID. .. py:attribute:: template_dirs :value: None .. py:attribute:: env .. py:method:: find_undeclared_variables(template) Find undeclared variables in a template. :param template: The template to analyze. :type template: str :returns: A set of undeclared variable names used in the template. :rtype: set .. py:method:: get_params(templates=None) -> dict Returns a dictionary of (default) parameters for the specified templates. :param templates: A dictionary of template params. If None, all templates are loaded. :type templates: iterable str :returns: A dictionary of parameters for the specified templates with dict[template_id, dict[param_name,param_value]]. :rtype: dict .. py:method:: get_templates() -> dict Retrieves all the templates from the directory. :returns: A dictionary of templates where the keys are the template names and the values are the corresponding Jinja2 Template objects. :rtype: dict .. py:method:: get_template_ids() This function retrieves the template IDs from the list of templates. :returns: A list of template IDs, which are the names of the templates without the file extension. :rtype: list .. py:method:: get_attachments(templates=None) Get attachments from the template directory. :param templates: A list or dictionary of templates. If None, all templates will be used. Defaults to None. :type templates: list or dict, optional :returns: A dictionary of attachments, where the keys are the template names and the values are dictionaries of attachments for that template. :rtype: dict .. py:method:: get_all_filenames() Get all filenames in all template directories. .. py:method:: get_all(load_params=True, load_attachments=True) Get all templates, parameters, and attachments. :param load_params: Whether to load parameters. Defaults to True. :type load_params: bool, optional :param load_attachments: Whether to load attachments. Defaults to True. :type load_attachments: bool, optional :returns: A tuple containing templates, parameters, and attachments. :rtype: tuple .. py:method:: resolve_template_id(my_template_id) Resolve the template ID to the actual template file name. :param my_template_id: The template ID to resolve. :type my_template_id: str :returns: The actual template file name. :rtype: str :raises KeyError: If the template ID is not found in the available templates. .. py:method:: __contains__(template_id) Check if a template_id is in any of the template directories. .. py:class:: DocTemplate(template, params=None, attachments=None, env=None, template_id=None) A class used to represent a document template. This class provides methods to load a template from a template directory, render the template with given parameters, and manage attachments. .. attribute:: template A string representation of the template. :type: str .. attribute:: params A dictionary of parameters to be used in the template. :type: dict .. attribute:: attachments A dictionary of attachments to be used in the template. :type: dict .. attribute:: env An instance of the jinja2 Environment class. :type: Environment .. py:method:: from_tid(template_id: str, tformat='', template_dir=None) :staticmethod: Load a template by supplying a template_id and possibly a template format :param template_id: The ID of the template to load e.G. "base" :type template_id: str :param tformat: optinal the template format to get e.G. ".tex" or ".html". Defaults to '' which means first of any format being found. :type tformat: str, optional :param template_dir: The directory containing the templates. If not provided, the default template directory is used. :type template_dir: str, optional :returns: An instance of the DocTemplate class. :rtype: DocTemplate .. py:method:: test_tid_exists(template_id: str, tformat='', template_dir=None) :staticmethod: .. py:method:: get_available_tids(template_dir=None) :staticmethod: .. py:attribute:: template .. py:attribute:: params :value: None .. py:attribute:: attachments :value: None .. py:attribute:: env .. py:attribute:: template_id :value: None .. py:property:: tformat .. py:method:: __str__() .. py:method:: __repr__() .. py:method:: find_undeclared_variables() Find undeclared variables in the template. :returns: A set of undeclared variable names used in the template. :rtype: set .. py:method:: render(**kwargs) Render the Jinja2 template with given parameters. :param \*\*kwargs: Additional parameters to be used in the template. :returns: The rendered template as a string. :rtype: str .. py:data:: res :value: False