Source code for pain001.xml.create_root_element

# Copyright (C) 2023-2026 Pain001. All rights reserved.
# SPDX-License-Identifier: Apache-2.0 OR MIT
#
# Licensed under either of the Apache License, Version 2.0 or the MIT
# License, at your option. You may not use this file except in
# compliance with one of those licences. Copies are provided in
# LICENSE-APACHE and LICENSE-MIT.
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the Licences is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied. See the applicable Licence for the specific language
# governing permissions and limitations.

# pylint: disable=C0301

"""
Module for creating XML payment initiation message documents compliant with
the ISO 20022 standard. The generated XML documents include essential
namespaces and schema locations.

Note: This module does not include additional security features for XML
parsing. It is advisable to consider measures to prevent XML vulnerabilities
when using it.
"""

import xml.etree.ElementTree as et  # nosec B405

# Namespace and schema-related constants
NAMESPACE = "urn:iso:std:iso:20022:tech:xsd:"
XSI_NAMESPACE = "http://www.w3.org/2001/XMLSchema-instance"




def create_root_element(message_type: str) -> et.Element:
    """
    Creates the root Element for a payment initiation XML document based on the
    specified message type. The function sets the required namespaces and
    schema locations.

    Args:
        message_type: The message type, for example "pain.001.001.09".
            Used to construct the namespace and schema location
            attributes.

    Returns:
        et.Element: The root Element node for the XML document,
            configured with the necessary namespaces and schema
            location attributes.

    Examples:
        >>> create_root_element("pain.001.001.09")
        <Element 'Document' at 0x7f8c0a309db0>
    """

    # Create the root element using the ElementTree library
    root = et.Element("Document")

    # Add xmlns (XML Namespace) and xmlns:xsi (XML Schema Instance) attributes
    # to the root element
    root.set("xmlns", NAMESPACE + message_type)
    root.set("xmlns:xsi", XSI_NAMESPACE)

    # Set the schema location for XML validation
    schema_location = f"{NAMESPACE}{message_type} {message_type}.xsd"
    root.set("xsi:schemaLocation", schema_location)

    return root