conversionSetup.py

"""Prepare the input, configuration, and rendering resources for one conversion."""

# This module deliberately gathers the many resources required for one
# conversion into one named result.  Splitting the preparation function or its
# dataclass purely to satisfy Pylint's default size limits would obscure that
# relationship.  Broad catches are also intentional: the legacy configuration
# file is optional, and malformed album input needs a user-facing error.
# pylint: disable=bare-except,broad-exception-caught,too-many-instance-attributes,too-many-locals,too-many-statements

import configparser
import logging
import os
import os.path
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Any

from lxml import etree

from ceweInfo import CeweInfo, ProductInfo, PdfProductStyle
from calendars.entries import CalendarEntries, loadCalendarEntries
from calendars.names import CalendarNames, loadCalendarNames
from calendars.layouts import (CalendarLayouts, applyCalendarLayoutSubstitutions,
                               loadCalendarLayouts)
from calendars.schemas import (CalendarSchemas, applyCalendarSchemaSubstitutions,
                               loadCalendarSchemas)
from clipart.catalog import readClipArtConfigXML
from infrastructure.configUtils import (getConfigurationBool, getConfigurationFloat,
                                        getConfigurationInt)
from conversionState import ConversionState
from infrastructure.extraLoggers import mustsee
from fonts.manager import findAndRegisterFonts
from fonts.line_scales import LineScales
from mcfx import unpackMcfx
from infrastructure.windowsIntegration import findInstalledCeweFolder
from imageUtils import DEFAULT_GEO_LINK_URL_TEMPLATE


@dataclass
class ConversionSetup:
    """Input and read-only resources resolved before the PDF canvas is created.

    Values here describe the album and its configured rendering environment.
    Data discovered while rendering belongs in :class:`ConversionState`
    instead, so it is clear which values are safe to share with all pages.
    """

    key_account_folder: str | None  # Account-specific CEWE data directory when one can be determined.

    configuration: configparser.ConfigParser            # Merged current-directory and album INI configuration.
    default_config_section: Any             # The DEFAULT INI section, passed to renderers needing an individual setting.

    background_locations: tuple[str, ...]   # Ordered directories searched for CEWE page-background images.
    clipart_files: dict[int, str]           # Extra clipart ID-to-file mappings configured in the INI file.
    clipart_paths: tuple[str, ...]          # Clipart XML/resource search paths resolved from the CEWE installation.
    passepartout_folders: tuple[str, ...]   # Ordered directories searched when building the passepartout index.
    calendar_schemas: CalendarSchemas        # Named calendar cell styles loaded from CEWE or minimal test resources.
    calendar_layouts: CalendarLayouts        # Named calendar cell layouts loaded from CEWE or minimal test resources.
    calendar_entries: CalendarEntries        # Localised holiday and observance definitions loaded from CEWE resources.
    calendar_names: CalendarNames            # Localised month, weekday, and week-heading labels loaded from CEWE resources.
    calendar_event_image_folders: tuple[str, ...]  # Portable fallback folders for personal-event thumbnails.

    mcf_xml_name: str           # Actual XML file to parse: the source MCF, or data.mcf unpacked from MCFX.
    mcf_base_folder: str        # Folder containing mcf_xml_name, used to resolve album image references.
    unpacked_folder: str | None # TemporaryDirectory returned when an MCFX archive was unpacked; otherwise None.
    album_base_folder: str      # Original album location, used to find its optional configuration file.

    fotobook: Any       # Root <fotobook> XML element used by the page-processing stage.
    product_style: PdfProductStyle  # Rendering style derived once from the MCF structure.
    album_title: str    # Human-readable album name used in generated album content and as the PDF-title fallback.
    pdf_title: str      # PDF title from [PDF_METADATA], or album_title when it is not configured.
    pdf_author: str     # Optional PDF author from [PDF_METADATA].
    geo_links_enabled: bool  # Whether EXIF GPS locations become invisible map links over photographs.
    geo_link_hotspot_size_mm: float  # Size of the top-left geolocation hotspot in millimetres.
    geo_link_url_template: str  # ``str.format`` template receiving latitude and longitude.

    available_fonts: Any        # Font faces successfully registered with ReportLab for this conversion.
    line_scales: LineScales     # Default and per-font line-spacing rules read from the INI configuration.

    image_resolution: int       # Target DPI for ordinary images.
    background_resolution: int  # Target DPI for page-background images.


def prepareConversion(albumname, mcfxTmpDir, appDataDir, state: ConversionState,
                      automaticWindows: bool = False) -> ConversionSetup: # noqa: C901
    """Read an album and resolve the configuration and resources it requires."""
    albumTitle, dummy = os.path.splitext(os.path.basename(albumname))

    # Check for the archive format introduced around CEWE 7.3.
    mcfxFormat = albumname.endswith('.mcfx')
    if mcfxFormat:
        albumPathObj = Path(albumname).resolve()
        unpackedFolder, mcfxmlname = unpackMcfx(albumPathObj, mcfxTmpDir)
    else:
        unpackedFolder = None
        mcfxmlname = albumname

    # The original album folder locates configuration; the MCF folder locates images.
    albumBaseFolder = str(Path(albumname).resolve().parent)
    mcfPathObj = Path(mcfxmlname).resolve()
    mcfBaseFolder = str(mcfPathObj.parent)

    # Read as binary so the XML parser retains the file's UTF-8 encoding.
    try:
        with open(mcfxmlname, 'rb') as mcffile:
            mcf = etree.parse(mcffile)
    except Exception as exception:
        invalidmsg = f'Cannot open mcf file {mcfxmlname}'
        if mcfxFormat:
            invalidmsg += f' (unpacked from {albumname})'
        logging.error(f'{invalidmsg}: {repr(exception)}')
        sys.exit(1)

    fotobook = mcf.getroot()
    CeweInfo.ensureAcceptableAlbumMcf(fotobook, albumname, mcfxmlname, mcfxFormat)
    productStyle = ProductInfo.pdfStyleFromMcf(fotobook)

    clipartFiles = {}
    passepartoutFolders = tuple[str]()
    defaultConfigSection = None
    configuration = None
    ceweFolder = None
    keyAccountFolder = None
    backgroundLocations = tuple[str]()
    imageResolution = 150
    backgroundResolution = 150
    calendarSchemas = {}
    calendarLayouts = {}
    calendarEntries = {}
    calendarNames = {}
    calendarEventImageFolders = tuple[str, ...]()

    # Read the current-directory INI first and the album INI second, so the
    # album-specific values override the current-directory defaults. Neither
    # configuration source is required: without a CEWE installation we can
    # still render album-contained photos and ordinary text using local fonts.
    #
    # cewe_folder.txt was the original one-value configuration mechanism. Do
    # not read it: its implicit precedence made configuration hard to reason
    # about. Warn once per distinct file so an existing user can migrate it.
    legacyConfigPaths = {
        os.path.abspath(os.path.join(folder, 'cewe_folder.txt'))
        for folder in (albumBaseFolder, os.path.curdir, os.path.dirname(os.path.realpath(__file__)))
    }
    for legacyConfigPath in legacyConfigPaths:
        if os.path.isfile(legacyConfigPath):
            logging.warning(
                f'Ignoring legacy CEWE configuration file: {legacyConfigPath}. '
                'Move its CEWE folder setting to cewe2pdf.ini.')

    logging.info('Trying cewe2pdf.ini from current directory and from the album directory.')
    configuration = configparser.ConfigParser()
    filesread = configuration.read(['cewe2pdf.ini', os.path.join(albumBaseFolder, 'cewe2pdf.ini')])
    defaultConfigSection = configuration['DEFAULT']
    metadataSection = (configuration['PDF_METADATA']
                       if configuration.has_section('PDF_METADATA') else None)
    geoLinksSection = (configuration['PDF_GEO_LINKS']
                       if configuration.has_section('PDF_GEO_LINKS') else None)
    if automaticWindows:
        # Explorer's context menu is designed for non-programmers: do not
        # require manual INI editing. Local system fonts are also useful in
        # this self-contained mode.
        defaultConfigSection['loadSystemFonts'] = 'True'
    if filesread:
        mustsee.info(f'Using configuration files, in order: {str(filesread)}')
    elif automaticWindows:
        # Explorer mode can discover CEWE from the MCF/MCFX association,
        # so the absence of an INI file is expected rather than a warning.
        mustsee.info(
            'No CEWE configuration found; trying automatic CEWE installation discovery.')
    else:
        mustsee.warning(
            'No CEWE configuration or installation found: continuing with local fonts and '
            'album-contained resources only. CEWE backgrounds, delivered clipart and '
            'passepartouts will be unavailable.')

    configuredCeweFolder = defaultConfigSection.get('cewe_folder', '').strip()
    # An album-side INI can explicitly identify the CEWE folder. In Explorer
    # mode a valid configured folder still wins: the album owner knows best.
    # If it is absent or no longer exists, try to discover the installed CEWE
    # application instead.
    if automaticWindows and (not configuredCeweFolder or
                             not os.path.isdir(configuredCeweFolder)):
        if configuredCeweFolder:
            logging.warning(
                f"Configured CEWE folder does not exist: {configuredCeweFolder}; "
                'trying automatic CEWE installation discovery instead.')
        configuredCeweFolder = findInstalledCeweFolder() or ''
        if configuredCeweFolder:
            mustsee.info(f'Automatically located CEWE folder: {configuredCeweFolder}')
        else:
            mustsee.warning(
                'Could not automatically locate the CEWE installation: '
                'continuing without CEWE resources.')
    if configuredCeweFolder:
        if os.path.isdir(configuredCeweFolder):
            ceweFolder = configuredCeweFolder
            CeweInfo.checkCeweFolder(ceweFolder)
            keyAccountNumber = CeweInfo.getKeyAccountNumber(ceweFolder, defaultConfigSection)
            CeweInfo.SetEnvironmentVariables(ceweFolder, keyAccountNumber)
            keyAccountFolder = CeweInfo.getKeyAccountDataFolder(keyAccountNumber, defaultConfigSection)
            backgroundLocations = CeweInfo.getBaseBackgroundLocations(ceweFolder, keyAccountFolder)
        else:
            logging.warning(
                f"Configured CEWE folder does not exist: {configuredCeweFolder}; "
                'continuing without CEWE resources.')
    else:
        logging.warning(
            "CEWE folder deliberately left unspecified: "
            'continuing without CEWE resources.')

    extraBackgroundFolders = defaultConfigSection.get('extraBackgroundFolders', '').splitlines()
    backgroundLocations += tuple(
        os.path.expandvars(folder) for folder in extraBackgroundFolders if folder)

    extraClipArts = defaultConfigSection.get('extraClipArts', '').splitlines()
    for extraClipArt in extraClipArts:
        if not extraClipArt:
            continue
        definition = os.path.expandvars(extraClipArt).split(',')
        if len(definition) == 2:
            clipartFiles[int(definition[0])] = definition[1].strip()

    configuredPassepartoutFolders = defaultConfigSection.get('passepartoutFolders', '').splitlines()
    if ceweFolder:
        configuredPassepartoutFolders.append(ceweFolder)
    passepartoutFolders = tuple(
        os.path.expandvars(folder) for folder in configuredPassepartoutFolders if folder)

    imageResolution = getConfigurationInt(defaultConfigSection, 'pdfImageResolution', '150', 100)
    backgroundResolution = getConfigurationInt(defaultConfigSection, 'pdfBackgroundResolution', '150', 100)

    mustsee.info(f'Using image resolution {imageResolution}, background resolution {backgroundResolution}')

    lineScales = LineScales(defaultConfigSection)
    if ceweFolder and keyAccountFolder is not None:
        passepartoutFolders += CeweInfo.getCewePassepartoutFolders(ceweFolder, keyAccountFolder)

    if productStyle == PdfProductStyle.Calendar:
        calendarSchemas = loadCalendarSchemas(ceweFolder)
        calendarLayouts = loadCalendarLayouts(ceweFolder)
        calendarEntries = loadCalendarEntries(ceweFolder)
        calendarNames = loadCalendarNames(ceweFolder)
    if productStyle == PdfProductStyle.Calendar and configuration.has_section('CALENDAR'):
        calendarSchemas = applyCalendarSchemaSubstitutions(
            calendarSchemas,
            configuration['CALENDAR'].get('schemaSubstitutions', ''))
        calendarLayouts = applyCalendarLayoutSubstitutions(
            calendarLayouts,
            configuration['CALENDAR'].get('layoutSubstitutions', ''))
        calendarEventImageFolders = tuple(
            str((mcfPathObj.parent / os.path.expandvars(folder.strip())).resolve())
            if not os.path.isabs(os.path.expandvars(folder.strip())) else
            os.path.expandvars(folder.strip())
            for folder in configuration['CALENDAR'].get(
                'calendarEventImageFolders', '').splitlines()
            if folder.strip())

    availableFonts = findAndRegisterFonts(defaultConfigSection, appDataDir, albumBaseFolder, ceweFolder, state)
    # Extra clipart file mappings work independently of the CEWE installation.
    # With no CEWE root this returns an empty delivered catalogue; a later
    # clipart lookup then uses its normal "not found" warning.
    clipartPaths = readClipArtConfigXML(ceweFolder, keyAccountFolder, clipartFiles)

    # An empty title would be less useful than the established filename-based
    # default.  Author deliberately remains empty unless the user supplies it.
    pdfTitle = metadataSection.get('title', '').strip() if metadataSection else ''
    pdfAuthor = metadataSection.get('author', '').strip() if metadataSection else ''
    geoLinksEnabled = getConfigurationBool(geoLinksSection, 'enabled', False)
    geoLinkHotspotSizeMm = (
        getConfigurationFloat(geoLinksSection, 'hotspotSizeMm', '10', 0.1)
        if geoLinksSection else 10.0)
    geoLinkUrlTemplate = (
        geoLinksSection.get('urlTemplate', DEFAULT_GEO_LINK_URL_TEMPLATE).strip()
        if geoLinksSection else DEFAULT_GEO_LINK_URL_TEMPLATE)
    try:
        if not geoLinkUrlTemplate:
            raise ValueError('empty template')
        geoLinkUrlTemplate.format(latitude='0', longitude='0')
    except (IndexError, KeyError, ValueError):
        logging.error(
            'Invalid [PDF_GEO_LINKS] urlTemplate; using the Google Maps default.')
        geoLinkUrlTemplate = DEFAULT_GEO_LINK_URL_TEMPLATE

    # Use names here rather than relying on ConversionSetup's declaration
    # order.  The dataclass is intentionally grouped for readability above,
    # and its fields should be freely rearrangeable without changing values.
    return ConversionSetup(
        key_account_folder=keyAccountFolder,
        configuration=configuration,
        default_config_section=defaultConfigSection,
        background_locations=backgroundLocations,
        clipart_files=clipartFiles,
        clipart_paths=clipartPaths,
        passepartout_folders=passepartoutFolders,
        calendar_schemas=calendarSchemas,
        calendar_layouts=calendarLayouts,
        calendar_entries=calendarEntries,
        calendar_names=calendarNames,
        calendar_event_image_folders=calendarEventImageFolders,
        mcf_xml_name=mcfxmlname,
        mcf_base_folder=mcfBaseFolder,
        unpacked_folder=unpackedFolder,
        album_base_folder=albumBaseFolder,
        fotobook=fotobook,
        product_style=productStyle,
        album_title=albumTitle,
        pdf_title=pdfTitle or albumTitle,
        pdf_author=pdfAuthor,
        geo_links_enabled=geoLinksEnabled,
        geo_link_hotspot_size_mm=geoLinkHotspotSizeMm,
        geo_link_url_template=geoLinkUrlTemplate,
        available_fonts=availableFonts,
        line_scales=lineScales,
        image_resolution=imageResolution,
        background_resolution=backgroundResolution)