utils

academic_doc_generator.core.utils

Small utility helpers.

find_latest_tex(folder, pattern='bewertung_brief_*.tex')

Find the most recently modified TeX file in a folder matching a pattern.

This function searches for files in the given folder whose names match a specified glob pattern (e.g., bewertung_brief_*.tex). If one or more files match, the function returns the path to the file with the most recent modification time. If no files match, it returns None.

Parameters:

Name	Type	Description	Default
folder	str	Path to the folder where TeX files are searched.	required
pattern	str	Glob pattern for matching file names. Defaults to "bewertung_brief_*.tex".	'bewertung_brief_*.tex'

Returns:

Type	Description
Optional[str]	The absolute path to the newest matching TeX file as a string,
Optional[str]	or None if no file matches the pattern.

Raises:

Type	Description
None directly, but errors may propagate if	The provided folder does not exist. There are permission issues when accessing the folder.

Example

find_latest_tex("/tmp", "bewertung_brief_*.tex") '/tmp/bewertung_brief_12345.tex'

Notes

• The "newest" file is determined by the last modification time (os.path.getmtime).
• The function returns an absolute path suitable for further processing, e.g., compilation with LuaLaTeX.

Source code in src/academic_doc_generator/core/utils.py

def find_latest_tex(folder: str, pattern: str = "bewertung_brief_*.tex") -> Optional[str]:
    """Find the most recently modified TeX file in a folder matching a pattern.

    This function searches for files in the given folder whose names match
    a specified glob pattern (e.g., ``bewertung_brief_*.tex``). If one or more
    files match, the function returns the path to the file with the most
    recent modification time. If no files match, it returns ``None``.

    Args:
        folder: Path to the folder where TeX files are searched.
        pattern: Glob pattern for matching file names.
            Defaults to ``"bewertung_brief_*.tex"``.

    Returns:
        The absolute path to the newest matching TeX file as a string,
        or ``None`` if no file matches the pattern.

    Raises:
        None directly, but errors may propagate if:
            * The provided folder does not exist.
            * There are permission issues when accessing the folder.

    Example:
        >>> find_latest_tex("/tmp", "bewertung_brief_*.tex")
        '/tmp/bewertung_brief_12345.tex'

    Notes:
        - The "newest" file is determined by the last modification time
          (`os.path.getmtime`).
        - The function returns an absolute path suitable for further processing,
          e.g., compilation with LuaLaTeX.
    """
    pat = os.path.join(folder, pattern)
    matches = glob.glob(pat)
    if not matches:
        return None
    return max(matches, key=os.path.getmtime)

get_semester(dt=None)

Determine the semester based on a date.

Winter semester (WS) runs from October 1 to end of February. Summer semester (SoSe) runs from March 1 to end of September.

Parameters:

Name	Type	Description	Default
dt	Optional[datetime]	The date to determine the semester for. Defaults to current date.	None

Returns:

Name	Type	Description
str	str	Semester string in format "WS25/26" or "SoSe25".

Source code in src/academic_doc_generator/core/utils.py

def get_semester(dt: Optional[datetime] = None) -> str:
    """Determine the semester based on a date.

    Winter semester (WS) runs from October 1 to end of February.
    Summer semester (SoSe) runs from March 1 to end of September.

    Args:
        dt: The date to determine the semester for. Defaults to current date.

    Returns:
        str: Semester string in format "WS25/26" or "SoSe25".
    """
    if dt is None:
        dt = datetime.now()
    month = dt.month
    year = dt.year

    if 3 <= month <= 9:
        # Summer semester (March to September)
        return f"SoSe{year % 100}"
    else:
        # Winter semester (October to February)
        if month >= 10:
            return f"WS{year % 100}/{(year + 1) % 100}"
        else:
            return f"WS{(year - 1) % 100}/{year % 100}"

load_global_config()

Load settings from global config.yaml file if it exists.

Returns:

Name	Type	Description
dict	dict	The configuration settings.

Source code in src/academic_doc_generator/core/utils.py

def load_global_config() -> dict:
    """Load settings from global config.yaml file if it exists.

    Returns:
        dict: The configuration settings.
    """
    config_path = Path("config.yaml")
    if config_path.exists():
        try:
            with open(config_path, encoding="utf-8") as f:
                return yaml.safe_load(f) or {}
        except Exception as e:
            print(f"Warning: Could not load config.yaml: {e}")
    return {}

split_student_name(full_name)

Split a student's full name into first and last name.

Handles formats like "Last, First" or "First Last".

Parameters:

Name	Type	Description	Default
full_name	str	The complete name string.	required

Returns:

Type	Description
tuple[str, str]	Tuple of (first_name, last_name).

Source code in src/academic_doc_generator/core/utils.py

def split_student_name(full_name: str) -> tuple[str, str]:
    """Split a student's full name into first and last name.

    Handles formats like "Last, First" or "First Last".

    Args:
        full_name: The complete name string.

    Returns:
        Tuple of (first_name, last_name).
    """
    if not full_name:
        return "Student", "Name"

    if "," in full_name:
        last_name, first_name = full_name.split(",", 1)
        return first_name.strip(), last_name.strip()

    parts = full_name.split()
    if len(parts) > 1:
        first_name = " ".join(parts[:-1])
        last_name = parts[-1]
        return first_name, last_name

    return full_name, "Name"