generate_wrapper.py

#!/usr/bin/env python
##Copyright 2008-2026 Thomas Paviot (tpaviot@gmail.com)

# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.

# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.

# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

###########
# imports #
###########
import argparse
import ast
import configparser
import copy
import datetime
import hashlib  # to compute md5 function signatures
import keyword  # to prevent using python language keywords
import logging
import os
import platform
import re
import subprocess
import sys
import time
from collections import Counter
from operator import itemgetter
from pathlib import Path
from typing import ClassVar

import CppHeaderParser

from _exclusions import (
    ENUMS_TO_EXLUDE,
    HXX_TO_EXCLUDE_FROM_BEING_INCLUDED,
    HXX_TO_EXCLUDE_FROM_CPPPARSER,
    NCOLLECTION_WRAPPED_CLASSES,
    NODEFAULTCTOR,
    STANDARD_INTEGER_TYPEDEF,
    TEMPLATES_TO_EXCLUDE,
    TYPEDEF_TO_EXCLUDE,
)
from _modules import KEEP_CONSTRUCTOR_ARGS, MODULE_OPTIONS, OCCT_MODULES, TOOLKITS
from _swig_templates import (
    BREPALGOAPI_HEADER,
    BREPTOOLS_WRITE_READ_FROM_STRING,
    BREPTOOLS_WRITE_READ_FROM_STRING_PYI,
    BVH_HEADER_TEMPLATE,
    BYREF_ENUM_TEMPLATE,
    CURVE_ARRAY_EVAL_PYI,
    DOWNCAST_PYI,
    GETSTATE_TEMPLATE,
    GRAPHIC3D_DEFINE_HEADER,
    HARRAY1_TEMPLATE,
    HARRAY1_TEMPLATE_PYI,
    HARRAY2_TEMPLATE,
    HARRAY2_TEMPLATE_PYI,
    HASH_TOPODS_SHAPE_TEMPLATE,
    HSEQUENCE_TEMPLATE,
    HSEQUENCE_TEMPLATE_PYI,
    LICENSE_HEADER,
    NCOLLECTION_ARRAY1_EXTEND_TEMPLATE_PYI,
    NCOLLECTION_ARRAY2_EXTEND_TEMPLATE_PYI,
    NCOLLECTION_ARRAY_NUMPY_PYI,
    NCOLLECTION_DATAMAP_EXTEND_TEMPLATE,
    NCOLLECTION_HEADER_TEMPLATE,
    NCOLLECTION_LIST_EXTEND_TEMPLATE,
    NCOLLECTION_LIST_EXTEND_TEMPLATE_PYI,
    NCOLLECTION_SEQUENCE_EXTEND_TEMPLATE,
    NCOLLECTION_SEQUENCE_EXTEND_TEMPLATE_PYI,
    NUMPY_INIT_TEMPLATE,
    PRS3D_HEADER_TEMPLATE,
    SETSTATE_TEMPLATE,
    SHAPE_ANALYSIS_FREE_BOUNDS_TEMPLATE,
    SHAPE_ANALYSIS_FREE_BOUNDS_TEMPLATE_PYI,
    STANDARD_TRANSIENT_OPERATORS_TEMPLATE,
    SURFACE_ARRAY_EVAL_PYI,
    TEMPLATE__EQ__,
    TEMPLATE__IADD__,
    TEMPLATE__IMUL__,
    TEMPLATE__ISUB__,
    TEMPLATE__ITRUEDIV__,
    TEMPLATE__NE__,
    TEMPLATE_CLASS_EXTENSIONS,
    TEMPLATE_CLASS_EXTENSIONS_PYI,
    TEMPLATE_DUMPJSON,
    TEMPLATE_DUMPJSON_PYI,
    TEMPLATE_GETTER_PYI,
    TEMPLATE_GETTER_SETTER,
    TEMPLATE_INITFROMJSON,
    TEMPLATE_INITFROMJSON_PYI,
    TEMPLATE_KEEP_OWNER,
    TEMPLATE_SETTER_PYI,
    TIMESTAMP_TEMPLATE,
    TOPODS_CLASS,
    TOPODS_CLASS_PYI,
    TOPODS_SHAPE_PICKLE_TEMPLATE,
    TOPODS_SHAPE_TYPES_HEADER,
    WIN_PRAGMAS,
)

# handlers are attached to the root logger by setup_logging()
logger = logging.getLogger(__name__)

# the directory of this script
SRC_DIR = Path(__file__).resolve().parent

##############################################
# Load configuration file and setup settings #
##############################################
# the PYTHONOCC_GENERATOR_CONFIG environment variable, if set, overrides the
# wrapper_generator.conf next to this script (used by the CI)
DEFAULT_CONFIG_PATH = os.environ.get("PYTHONOCC_GENERATOR_CONFIG") or str(
    SRC_DIR / "wrapper_generator.conf"
)

# path settings, set by load_config()
PYTHONOCC_VERSION = ""
OCCT_INCLUDE_DIR = Path()
PYTHONOCC_CORE_PATH = Path()
COMMON_OUTPUT_PATH = Path()
SWIG_OUTPUT_PATH = Path()
HEADERS_OUTPUT_PATH = Path()


def load_config(config_path):
    """Read wrapper_generator.conf and set the module-level path settings.

    Called once at import time with the default path (so the helper functions
    are usable from the unit tests), then again from main() if --config is
    given. No filesystem check is done here, see check_paths().
    """
    global PYTHONOCC_VERSION, OCCT_INCLUDE_DIR, PYTHONOCC_CORE_PATH
    global COMMON_OUTPUT_PATH, SWIG_OUTPUT_PATH, HEADERS_OUTPUT_PATH
    config = configparser.ConfigParser()
    if not config.read(config_path, encoding="utf8"):
        raise FileNotFoundError(f"Configuration file {config_path} not found.")
    # pythonocc version
    PYTHONOCC_VERSION = config.get("pythonocc-core", "version")
    # oce headers location
    OCCT_INCLUDE_DIR = Path(config.get("OCCT", "include_dir"))
    # swig output path
    PYTHONOCC_CORE_PATH = Path(config.get("pythonocc-core", "path"))
    swig_files_path = PYTHONOCC_CORE_PATH / "src" / "SWIG_files"
    COMMON_OUTPUT_PATH = swig_files_path / "common"
    SWIG_OUTPUT_PATH = swig_files_path / "wrapper"
    HEADERS_OUTPUT_PATH = swig_files_path / "headers"


def check_paths():
    """Fail early if the OCCT headers are missing, and create the output
    directories the generator writes into."""
    if not OCCT_INCLUDE_DIR.is_dir():
        raise FileNotFoundError(f"OCCT include dir {OCCT_INCLUDE_DIR} not found.")
    for output_path in (SWIG_OUTPUT_PATH, HEADERS_OUTPUT_PATH, COMMON_OUTPUT_PATH):
        output_path.mkdir(parents=True, exist_ok=True)


load_config(DEFAULT_CONFIG_PATH)

GENERATE_SWIG_FILES = (
    True  # if set to False, skip .i generator, to avoid recompile everything
)


def setup_logging():
    """Log both to stdout and to ${SWIG_OUTPUT_PATH}/generator.log, which is
    emptied at each run. Must be called after check_paths()."""
    log_formatter = logging.Formatter("[%(levelname)-5.5s]  %(message)s")
    log = logging.getLogger()
    log.setLevel(logging.INFO)
    file_handler = logging.FileHandler(
        SWIG_OUTPUT_PATH / "generator.log", mode="w", encoding="utf8"
    )
    file_handler.setFormatter(log_formatter)
    log.addHandler(file_handler)
    console_handler = logging.StreamHandler(sys.stdout)
    console_handler.setFormatter(log_formatter)
    log.addHandler(console_handler)


####################
# Global variables #
####################
DOC_URL = "https://dev.opencascade.org/doc/occt-7.9.0/refman/html"


class GeneratorState:
    """Mutable state shared across the generation pipeline.

    Replaces a dozen module-level globals so the dependencies between passes
    are explicit. A single instance, ``state`` below, is the only authority.
    """

    def __init__(self):
        # set by ModuleWrapper.__init__ for the module currently being wrapped
        self.current_module = ""
        # python modules the current module imports (transitive deps).
        # Reassigned per module; check_dependency() and process_typedefs()
        # append to it.
        self.python_module_dependency = []
        # Like above but for additional headers; reset at every module via
        # reset_header_depency().
        self.header_dependency = []
        # module -> the modules it imports, for the modules processed so far
        self.module_dependencies = {}
        # the types used as template arguments in the typedefs of the
        # current module, set by process_typedefs()
        self.template_argument_types = []

        # occt-800: built lazily by scan_typedef_aliases() — a mapping from
        # canonical template form (e.g. "NCollection_HArray1<gp_Pnt2d>") to
        # the typedef alias (e.g. "TColgp_HArray1OfPnt2d") that pythonocc
        # actually wraps. Many OCCT 8.0 headers replaced typedef names with
        # the canonical template form in their function signatures, but the
        # typedef alias is what carries the SWIG type tag, so we have to
        # rewrite back.
        self.harray_typedef_rewrites = []
        # the same, as a dict: canonical template form -> typedef alias
        self.typedef_rewrite_names = {}
        # Canonical template form -> typedef name, filled by
        # process_templates_from_typedefs() for every module processed so far.
        # Used to emit valid python names in the HArray/HSequence stubs.
        self.template_typedef_names = {}
        # occt-800: names of the `using Alias = Tpl<Args>;` template aliases
        # of the current module that are wrapped as %template(Alias)
        # instantiations (BRepLProp_SLProps, Extrema_ExtPC, Bnd_B2d, ...).
        # Filled by _convert_using_to_typedef(), reset at every module.
        self.template_alias_names = set()
        # occt-800: modules whose nested classes are wrapped as top level
        # classes (see flatten_nested_classes()), from modules.yaml.
        self.flatten_nested_classes = False
        # classes of the current module wrapped even though the module
        # excludes all its classes (exclude_classes: ["*"]), from modules.yaml.
        self.include_classes = []
        # the public fields of the classes are wrapped (e.g. DESTEP_Parameters),
        # from modules.yaml.
        self.wrap_public_fields = False
        # (qualified C++ name, flat SWIG name) of the flattened classes of the
        # current module, e.g. ("BRepGraph::ShapesView", "BRepGraph_ShapesView");
        # a typedef is written for each in the C++ section of the .i file.
        self.flattened_classes = []
        # `using Alias = Outer::Tpl<Args>;` aliases of nested class templates,
        # alias -> (Outer, Tpl, Args); instantiated by flatten_nested_classes().
        self.nested_template_aliases = {}
        # names of the classes of the current module that are not wrapped
        # (templates, excluded classes...) or that cannot be copied (deleted
        # copy constructor): a method returning one of them by value cannot
        # be wrapped. Filled by process_classes().
        self.unwrapped_classes = set()

        # All enums seen so far; populated by process_enums().
        self.all_enums = []
        # Enums passed/returned by reference; need a SWIG-specific template.
        self.all_byref_enums = []

        # HArray1/HArray2/HSequence registries: name -> base type. Populated
        # both from DEFINE_HARRAY{1,2}/DEFINE_HSEQUENCE macros and from
        # `typedef NCollection_HArrayN<X> Y;` aliases scanned upfront.
        self.all_harray1 = {}
        self.all_harray2 = {}
        self.all_hsequence = {}

        # Classes that need %wrap_handle / %make_alias.
        self.all_standard_handles = []
        self.all_standard_transients = ["Standard_Transient"]
        # class name -> name of its first ancestor, for every class seen so
        # far, whatever its module. Filled by build_inheritance_tree().
        self.class_parents = {}

        # since SWIG 4.1.1, static functions can no longer be called as free
        # functions; we emit deprecation shims for the old name.
        self.deprecated_static_functions = []

        # statistics
        self.nb_total_classes = 0
        self.nb_total_methods = 0


state = GeneratorState()


def get_log_header():
    """returns a header to be appended to the SWIG file
    Useful for development
    """
    os_name = f"{platform.system()} {platform.architecture()[0]} {platform.release()}"
    # the generator may be run from a tarball, without git available
    try:
        generator_git_revision = (
            subprocess.check_output(
                ["git", "rev-parse", "--short", "HEAD"],
                cwd=SRC_DIR,
                stderr=subprocess.DEVNULL,
            )
            .strip()
            .decode("utf8")
        )
    except (OSError, subprocess.CalledProcessError):
        generator_git_revision = "unknown"
    # find the OCC VERSION targeted by the wrapper
    # the OCCT version is available from the Standard_Version.hxx header
    # e.g. define OCC_VERSION_COMPLETE     "7.4.0"
    standard_version_header = OCCT_INCLUDE_DIR / "Standard_Version.hxx"
    occ_version = "unknown"
    if standard_version_header.is_file():
        with standard_version_header.open(encoding="utf8") as f:
            file_lines = f.readlines()
        for file_line in file_lines:
            if file_line.startswith("#define OCC_VERSION_COMPLETE"):
                occ_version = file_line.split('"')[1].strip()
    return TIMESTAMP_TEMPLATE.substitute(
        {
            "GITREVISION": generator_git_revision,
            "OS": os_name,
            "OCCTVERSION": occ_version,
            "DATE": f"{datetime.datetime.now().astimezone()}",
        }
    )


def get_log_footer(elapsed_seconds):
    return f"""
#################################################
SWIG interface file generation completed in {elapsed_seconds:.2f}s
#################################################
"""


def reset_header_depency():
    # OSD: the wrapped OSD classes (OSD_ThreadPool) reach every module that
    # imports Message.i, their declaration is required by the SWIG casts.
    # Bnd and TopTools: same for the modules importing TopTools.i (that
    # imports Bnd.i for TopTools_DataMapOfShapeBox) and MoniTool.i (that
    # imports TopTools.i for MoniTool_IndexedDataMapOfShapeTransient)
    state.header_dependency = [
        "TColgp",
        "TColStd",
        "TCollection",
        "Storage",
        "OSD",
        "Bnd",
        "TopTools",
    ]


def check_is_persistent(class_name):
    """
    Checks, whether a class belongs to the persistent classes (and not to the transient ones)
    """
    return any(
        class_name.startswith(occ_module)
        for occ_module in [
            "PFunction",
            "PDataStd",
            "PPrsStd",
            "PDF",
            "PDocStd",
            "PDataXtd",
            "PNaming",
            "PCDM_Document",
        ]
    )


def filter_header_list(header_list, exclusion_list):
    """From a header list, remove hxx to HXX_TO_EXCLUDE
    The files to be excluded are specified in the exclusion list
    """
    for header_to_remove in exclusion_list:
        header_path = str(OCCT_INCLUDE_DIR / header_to_remove)
        if header_path in header_list:
            header_list.remove(header_path)
    # remove platform dependent files
    # this is done to have the same SWIG files on every platform:
    # wnt specific (WNT_*, OSD_WNT), linux (X11, XWD) and osx (Cocoa).
    # Match on the basename only, and case-sensitively, so that neither the
    # include dir path nor names such as Storage_StreamUnknownTypeError
    # ("unknowntype" contains "wnt") are caught by accident.
    platform_markers = ("WNT", "X11", "XWD", "Cocoa")
    return [
        x
        for x in header_list
        if not any(marker in Path(x).name for marker in platform_markers)
    ]


def occt_headers(pattern):
    """The paths, as strings, of the OCCT headers matching the glob pattern,
    in the order of the file system"""
    return [str(path) for path in OCCT_INCLUDE_DIR.glob(pattern)]


def case_sensitive_glob(pattern):
    """
    Case sensitive glob of the OCCT headers, for Windows.
    Designed for handling of GEOM and Geom modules
    This function makes the difference between GEOM_* and Geom_* under Windows
    """
    prefix = pattern.split("*")[0]
    return [
        path for path in occt_headers(pattern) if Path(path).name.startswith(prefix)
    ]


def get_all_module_headers(module_name):
    """Returns a list with all header names"""
    mh = case_sensitive_glob(f"{module_name}.hxx")
    mh += case_sensitive_glob(f"{module_name}_*.hxx")
    mh = filter_header_list(mh, HXX_TO_EXCLUDE_FROM_BEING_INCLUDED)
    return sorted(Path(header).name for header in mh)


def check_has_related_handle(class_name):
    """For a given class :
    Check if a header exists.
    """
    if check_is_persistent(class_name):
        return False

    filename = OCCT_INCLUDE_DIR / f"Handle_{class_name}.hxx"
    other_possible_filename = filename
    if class_name.startswith("Graphic3d"):
        other_possible_filename = OCCT_INCLUDE_DIR / f"{class_name}_Handle.hxx"
    return (
        filename.exists() or other_possible_filename.exists() or need_handle(class_name)
    )


def need_handle(class_name):
    """Returns True if the current parsed class needs an
    Handle to be defined. This is useful when headers define
    handles but no header"""
    # @TODO what about DEFINE_RTTI ?
    return (
        class_name in state.all_standard_handles
        or class_name in state.all_standard_transients
    )


_DEFINE_STANDARD_HANDLE_RE = re.compile(
    r"DEFINE_STANDARD_HANDLE[\s]*\([\w\s]+,+[\w\s]+\)"
)
# occt-800: many classes that derive from Standard_Transient no longer carry
# a DEFINE_STANDARD_HANDLE; they only have DEFINE_STANDARD_RTTI{,_INLINE,EXT}
# (C, Parent). Treat that as an implicit handle declaration so
# check_has_related_handle picks them up. DEFINE_DERIVED_ATTRIBUTE marks XCAF
# shape tools and similar classes as TDataStd_GenericEmpty subtypes.
_DEFINE_RTTI_RE = re.compile(
    r"DEFINE_(?:STANDARD_RTTI(?:_INLINE|EXT)?|DERIVED_ATTRIBUTE)\s*"
    r"\(\s*([\w]+)\s*,\s*[\w:]+\s*\)"
)
_DEFINE_HARRAY1_RE = re.compile(r"DEFINE_HARRAY1[\s]*\([\w\s]+,+[\w\s]+\)")
_DEFINE_HARRAY2_RE = re.compile(r"DEFINE_HARRAY2[\s]*\([\w\s]+,+[\w\s]+\)")
_DEFINE_HSEQUENCE_RE = re.compile(r"DEFINE_HSEQUENCE[\s]*\([\w\s]+,+[\w\s]+\)")
# Strip Standard_DEPRECATED("...") and Standard_DEPRECATED_STD("...") entirely
# (with the parens), so they disappear from the source rather than leaving a
# dangling //comment. OCCT 8.0 places these attributes mid-declaration (e.g.
# inside `using ... = X;`) which would otherwise produce malformed C++.
_STANDARD_DEPRECATED_RE = re.compile(
    r"Standard_DEPRECATED(?:_STD|_WARNING)?\s*\(\s*"
    r'(?:".*?(?:\\"|[^"])*?"(?:\s*".*?(?:\\"|[^"])*?")*)\s*\)'
)
_USING_ALIAS_RE = re.compile(r"\busing\s+([A-Za-z_]\w*)\s*=\s*([^;]+);")
# `Outer::Tpl<Args>`, an instantiation of a class template nested in Outer
_NESTED_TEMPLATE_ALIAS_RE = re.compile(r"(\w+)::(\w+)<(.+)>")
_HANDLE_PARENS_RE = re.compile(r"Handle[\s]*\([\w\s]*\)")


def _collect_handle_macros(header_content):
    """Populate state.all_standard_handles with names declared via DEFINE_STANDARD_HANDLE
    or one of the DEFINE_STANDARD_RTTI* / DEFINE_DERIVED_ATTRIBUTE macros."""
    for match in _DEFINE_STANDARD_HANDLE_RE.findall(header_content):
        state.all_standard_handles.append(match.split("(")[1].split(",")[0])
    for match in _DEFINE_RTTI_RE.findall(header_content):
        if match not in state.all_standard_handles:
            state.all_standard_handles.append(match)


def _collect_harray_macros(header_content):
    """Populate state.all_harray1/2 and state.all_hsequence from DEFINE_HARRAY{1,2} /
    DEFINE_HSEQUENCE macros."""
    for regex, store, label in (
        (_DEFINE_HARRAY1_RE, state.all_harray1, "HARRAY1"),
        (_DEFINE_HARRAY2_RE, state.all_harray2, "HARRAY2"),
        (_DEFINE_HSEQUENCE_RE, state.all_hsequence, "HSEQUENCE"),
    ):
        for match in regex.findall(header_content):
            typename = match.split("(")[1].split(",")[0]
            base_typename = match.split(",")[1].split(")")[0]
            logger.info("Found %s definition %s:%s", label, typename, base_typename)
            store[typename] = base_typename.strip()


def _comment_out_macros(header_content):
    """Replace macros that confuse CppHeaderParser by their //commented form."""
    for token in (
        "DEFINE_STANDARD_HANDLE",
        "DEFINE_STANDARD_RTTIEXT",
        "DEFINE_STANDARD_RTTI_INLINE",
        "NCOLLECTION_HSEQUENCE",
    ):
        header_content = header_content.replace(token, f"//{token}")
    # Standard_DEPRECATED("...") form: drop the whole macro+parens first, then
    # //comment any bare leftover identifier. Order matters.
    header_content = _STANDARD_DEPRECATED_RE.sub("", header_content)
    for token in (
        "Standard_DEPRECATED",
        "DECLARE_TOBJOCAF_PERSISTENCE",
        "DEFINE_DERIVED_ATTRIBUTE",
    ):
        header_content = header_content.replace(token, f"//{token}")
    return header_content


_CXX_ATTRIBUTE_RE = re.compile(r"\[\[[^\]]*\]\]")


def _strip_macros(header_content):
    """Drop attribute macros that prevent CppHeaderParser from working."""
    for token in ("DEFINE_STANDARD_ALLOC", "Standard_EXPORT", "Standard_NODISCARD"):
        header_content = header_content.replace(token, "")
    # C++11 attributes such as [[nodiscard]] (occt-800: BRepGraph)
    return _CXX_ATTRIBUTE_RE.sub("", header_content)


def _rewrite_handle_parens(header_content):
    """Rewrite legacy `Handle(X)` syntax to `opencascade::handle<X>`."""
    for match in _HANDLE_PARENS_RE.findall(header_content):
        # matches are of the form ['Handle(Graphic3d_Structure)',
        # 'Handle(Graphic3d_DataStructureManager)']
        normalized = match.replace(" ", "")
        class_name = normalized.split("Handle(")[1].split(")")[0]
        if class_name == "" or not class_name[0].isupper():
            continue
        header_content = header_content.replace(
            normalized, f"opencascade::handle<{class_name}>"
        )
    return header_content


_template_header_cache: dict[str, str | None] = {}


def find_template_header(template_name):
    """Return the basename of the OCCT header that declares the class template
    template_name, None if there is none. OCCT 8.0 templates are usually
    declared in a header of their own name (Extrema_GGExtPC.hxx, Bnd_B2.hxx)
    but not always: GeomLProp_SLPropsBase lives in GeomLProp_SLProps.hxx."""
    if template_name in _template_header_cache:
        return _template_header_cache[template_name]
    header = None
    candidate = f"{template_name}.hxx"
    if (OCCT_INCLUDE_DIR / candidate).is_file():
        header = candidate
    else:
        # a class definition, not a forward declaration
        class_re = re.compile(
            rf"\bclass\s+{re.escape(template_name)}\b\s*(?::[^;{{]*)?\{{"
        )
        prefix = template_name.split("_")[0]
        for path in sorted(OCCT_INCLUDE_DIR.glob(f"{prefix}_*.hxx")):
            content = path.read_text(encoding="utf8", errors="replace")
            if "template" in content and class_re.search(content):
                header = path.name
                break
    _template_header_cache[template_name] = header
    return header


def is_wrappable_template_alias(alias, rhs):
    """occt-800: tell whether the template alias `using alias = rhs;` (rhs
    being an instantiation such as GeomLProp_SLPropsBase<BRepAdaptor_Surface>)
    can be wrapped as a %template of the same name.

    OCCT 8.0 turned many classes into aliases of class templates
    (BRepLProp_SLProps, Extrema_ExtPC, Bnd_B2d, math_IntegerVector, ...).
    They are wrapped by %including the template header and instantiating the
    template under the alias name, see process_templates_from_typedefs().
    Only aliases named after the module being processed are considered (this
    skips class-scope aliases and the copies of math_Vector found in other
    packages), the template must be an OCCT class with its own header, and
    NCollection aliases keep going through the NCollection typedef pipeline.
    Aliases listed in TEMPLATES_TO_EXCLUDE are skipped, e.g. LProp_CLProps3d
    would make LProp import GeomLProp, which itself imports LProp."""
    if alias in TEMPLATES_TO_EXCLUDE:
        return False
    if "_" not in alias or alias.split("_")[0] != state.current_module:
        return False
    template_name = rhs.split("<", 1)[0].strip()
    # nested or namespaced templates (Foo::Bar<...>, opencascade::handle<...>)
    if not re.fullmatch(r"[A-Za-z_]\w*", template_name):
        return False
    if template_name.startswith("NCollection_"):
        return False
    return find_template_header(template_name) is not None


def _convert_using_to_typedef(header_content):
    """occt-800: rewrite C++11 `using X = Y;` aliases into classic
    `typedef Y X;` so the typedef pipeline picks them up. Many OCCT 8.0
    headers (GCE2d_MakeEllipse, ...) became `using` aliases for renamed
    classes, others (BRepLProp_SLProps, Extrema_ExtPC, ...) aliases of class
    template instantiations. The latter are converted only when
    is_wrappable_template_alias() accepts them, and recorded in
    state.template_alias_names."""

    def _replace(match):
        alias = match.group(1)
        rhs = " ".join(match.group(2).split())
        if "<" in rhs:
            nested = _NESTED_TEMPLATE_ALIAS_RE.fullmatch(rhs)
            if nested is not None and state.flatten_nested_classes:
                # instantiated by flatten_nested_classes(), left as is here
                state.nested_template_aliases[alias] = nested.groups()
                return match.group(0)
            if not is_wrappable_template_alias(alias, rhs):
                return match.group(0)
            state.template_alias_names.add(alias)
        return f"typedef {rhs} {alias};"

    return _USING_ALIAS_RE.sub(_replace, header_content)


def adapt_header_file(header_content):
    """Pre-process an OCCT header so CppHeaderParser can parse it.

    - Skips OCCT 8.0 deprecated alias headers entirely.
    - Collects DEFINE_STANDARD_HANDLE / DEFINE_STANDARD_RTTI* / DEFINE_HARRAY*
      / DEFINE_HSEQUENCE declarations into the corresponding global registries.
    - Strips or //comments out macros that the parser cannot handle.
    - Normalizes `occ::handle` and `Handle(X)` to `opencascade::handle<X>`.
    - Rewrites `using X = Y;` aliases to `typedef Y X;` (template aliases
      only when they can be wrapped as a %template instantiation).
    """
    if ("Deprecated alias to moved class" in header_content) or (
        "Alias to moved class" in header_content
    ):
        return ""

    _collect_handle_macros(header_content)
    _collect_harray_macros(header_content)
    header_content = _comment_out_macros(header_content)
    header_content = _strip_macros(header_content)
    # occ::handle must be normalized before using-to-typedef (a `using X =
    # occ::handle<Z>;` is template-aliased and intentionally skipped by the
    # rewrite); Handle(X) rewriting comes last because it introduces template
    # syntax that earlier passes don't expect.
    header_content = header_content.replace("occ::handle", "opencascade::handle")
    header_content = _convert_using_to_typedef(header_content)
    return _rewrite_handle_parens(header_content)


def parse_header(header_filename):
    """Use CppHeaderParser module to parse header_filename"""
    with Path(header_filename).open(encoding="utf-8") as header_content:
        adapted_header_content = adapt_header_file(header_content.read())
        try:
            cpp_header = CppHeaderParser.CppHeader(adapted_header_content, "string")
        except CppHeaderParser.CppParseError as e:
            error_message = f"Error: cannot parse {header_filename}\n"
            error_message += f"Reason: {e}"
            raise RuntimeError(error_message) from e
    return cpp_header


def filter_typedefs(typedef_dict):
    """Remove some strange thing that generated SWIG
    errors
    """
    if "{" in typedef_dict:
        del typedef_dict["{"]
    if ":" in typedef_dict:
        del typedef_dict[":"]
    for key in list(typedef_dict):
        if key in TYPEDEF_TO_EXCLUDE:
            del typedef_dict[key]
            continue
        # remove typedefs that ends with function callbacks
        if key.endswith("Function"):
            logger.info("Skip typedef %s because ends with 'Function'", key)
            del typedef_dict[key]
            continue
        # remove typedefs tha ends with _fp (means function pointer?)
        if key.endswith("_fp"):
            logger.info("Skip typedef %s because ends with '_fp'", key)
            del typedef_dict[key]
            continue
        # remove typedefs tha ends with Func (function pointer)
        if key.endswith("Func"):
            logger.info("Skip typedef %s because ends with 'Func'", key)
            del typedef_dict[key]
            continue
        # occt-800: skip pointer typedefs (e.g. typedef NCollection_List<X>* Plos)
        # SWIG cannot generate %template(...) Foo<X>*; with a pointer
        if typedef_dict[key].rstrip().endswith("*"):
            logger.info("Skip typedef %s because target is a pointer type", key)
            del typedef_dict[key]
    for key in list(typedef_dict):
        typedef_dict[key] = typedef_dict[key].replace(" ::", "::")
        typedef_dict[key] = typedef_dict[key].replace(" , ", ", ")
    return typedef_dict


def get_type_for_ncollection_array(ncollection_array: str) -> str:
    """input : NCollection_Array1<Standard_Real>
    output : Standard_Real
    """
    return ncollection_array.split("<")[1].split(">", maxsplit=1)[0].strip()


# the item types of the NCollection_Array1/Array2 instantiations extended by
# the *NumpyTemplate macros of ArrayMacros.i (Poly_Triangle: Array1 only)
_NUMPY_ARRAY_BASE_TYPES = frozenset(
    {
        "Standard_ShortReal",
        "float",
        "Standard_Real",
        "double",
        "Standard_Integer",
        "int",
        "Poly_Triangle",
        "gp_XY",
        "gp_Vec2d",
        "gp_Pnt2d",
        "gp_Dir2d",
        "gp_XYZ",
        "gp_Vec",
        "gp_Pnt",
        "gp_Dir",
    }
)


def process_templates_from_typedefs(list_of_typedefs):
    """Generate the SWIG %template directives and the .pyi hints of the
    template instantiations in list_of_typedefs."""
    wrapper_str = "/* templates */\n"
    pyi_str = ""
    # template headers already %included in this module, see below
    included_template_headers = set()
    for t in list_of_typedefs:
        template_name = t[1].replace(" ", "")
        template_type = t[0]
        if "unsigned" not in template_type and "const" not in template_type:
            template_type = template_type.replace(" ", "")
        state.template_typedef_names.setdefault(template_type, template_name)
        # we must include
        if not template_type.endswith(("::Iterator", "::Type")):  # it's not an iterator
            wrap_template = all(
                forbidden_template not in template_type
                for forbidden_template in TEMPLATES_TO_EXCLUDE
            )
            if template_name in TEMPLATES_TO_EXCLUDE:
                continue
            # sometimes the template name is weird (parenthesis, comma etc.)
            # don't consider this
            if "_" not in template_name:
                wrap_template = False
                # del typedef_dict[key]
            if wrap_template:
                # wrapper_str += f"%template({template_name}) {template_type};\n"
                # if a NCollection_Array1, extend this template to benefit from pythonic methods
                # All "Array1" classes are considered as python arrays
                # TODO : it should be a good thing to use decorators here, to avoid code duplication
                basetype_hint = (
                    adapt_type_for_hint(get_type_for_ncollection_array(template_type))
                    or "Any"
                )
                if template_name in state.template_alias_names:
                    # occt-800: `using Alias = Tpl<Args>;`. The template class
                    # itself is not wrapped (see process_classes), SWIG parses
                    # its header directly, as done for the NCollection
                    # templates. Checked first: the NCollection_* tests below
                    # also match an NCollection argument of the template.
                    template_class = template_type.split("<", 1)[0]
                    template_header = find_template_header(template_class)
                    if template_header not in included_template_headers:
                        included_template_headers.add(template_header)
                        wrapper_str += TEMPLATE_CLASS_EXTENSIONS.get(template_class, "")
                        wrapper_str += f'%include "{template_header}";\n'
                    wrapper_str += f"%template({template_name}) {template_type};\n"
                elif "NCollection_Array1" in template_type:
                    # in this cas, we use the Array1ExtendIter(T) macro by default
                    # if the NCollection_Array1 involves Standard_Integer or Standard_Real
                    # then the NCollection_Array1 can be wrapped as a numpy array and the
                    # macro Array1NumpyTemplate is used.
                    base_type = template_type[:-1].split("NCollection_Array1<")[1]
                    # occt-800 typedefs use plain `double`/`int`/`float` instead
                    # of the Standard_* aliases; treat both forms identically
                    if base_type in ("Standard_ShortReal", "float"):
                        wrapper_str += "%apply (float* IN_ARRAY1, int DIM1) { (float* numpyArray1, int nRows1) };\n"
                        wrapper_str += "%apply (float* ARGOUT_ARRAY1, int DIM1) { (float* numpyArray1Argout, int nRows1Argout) };\n"
                        wrapper_str += f"Array1NumpyTemplate({template_name}, float, {base_type})\n"
                    elif base_type in ("Standard_Real", "double"):
                        wrapper_str += "%apply (double* IN_ARRAY1, int DIM1) { (double* numpyArray1, int nRows1) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray1Argout, int nRows1Argout) };\n"
                        wrapper_str += f"Array1NumpyTemplate({template_name}, double, {base_type})\n"
                    elif base_type in ("Standard_Integer", "int"):
                        wrapper_str += "%apply (long long* IN_ARRAY1, int DIM1) { (long long* numpyArray1, int nRows1) };\n"
                        wrapper_str += "%apply (long long* ARGOUT_ARRAY1, int DIM1) { (long long* numpyArray1Argout, int nRows1Argout) };\n"
                        wrapper_str += f"Array1NumpyTemplate({template_name}, long long, {base_type})\n"
                    elif base_type == "Poly_Triangle":
                        wrapper_str += "%apply (long long* IN_ARRAY2, int DIM1, int DIM2) { (long long* numpyArray2, int nRows2, int nDims2) };\n"
                        wrapper_str += "%apply (long long* ARGOUT_ARRAY1, int DIM1) { (long long* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += f"Array1OfTriaNumpyTemplate({template_name}, Poly_Triangle)\n\n"

                    # 2D elements, i.e. that provides X() and Y() methods
                    elif base_type in ["gp_XY", "gp_Vec2d", "gp_Pnt2d", "gp_Dir2d"]:
                        wrapper_str += "%apply (double* IN_ARRAY2, int DIM1, int DIM2) { (double* numpyArray2, int nRows2, int nDims2) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += (
                            f"Array1Of2DNumpyTemplate({template_name}, {base_type})\n"
                        )
                    # 3D elements, i.e. that provides X(), Y() and Z() methods
                    elif base_type in ["gp_XYZ", "gp_Vec", "gp_Pnt", "gp_Dir"]:
                        wrapper_str += "%apply (double* IN_ARRAY2, int DIM1, int DIM2) { (double* numpyArray2, int nRows2, int nDims2) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += (
                            f"Array1Of3DNumpyTemplate({template_name}, {base_type})\n"
                        )
                    else:  # no numpy support
                        wrapper_str += f"%template({template_name}) {template_type};\n"
                        wrapper_str += f"Array1ExtendIter({base_type})\n\n"
                    pyi_str += NCOLLECTION_ARRAY1_EXTEND_TEMPLATE_PYI.substitute(
                        {
                            "NCollection_Array1_Template_Instanciation": template_name,
                            "Type_T": f"{basetype_hint}",
                        }
                    )
                    if base_type in _NUMPY_ARRAY_BASE_TYPES:
                        pyi_str += NCOLLECTION_ARRAY_NUMPY_PYI
                elif "NCollection_Array2" in template_type:
                    # same than NCollection_Array1
                    base_type = template_type.split("NCollection_Array2<")[1].split(
                        ">"
                    )[0]
                    # occt-800: typedefs use plain `double`/`int`/`float`
                    if base_type in ("Standard_ShortReal", "float"):
                        wrapper_str += "%apply (float* IN_ARRAY2, int DIM1, int DIM2) { (float* numpyArray2, int nRows2, int nCols2) };\n"
                        wrapper_str += "%apply (float* ARGOUT_ARRAY1, int DIM1) { (float* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += f"Array2NumpyTemplate({template_name}, float, {base_type})\n"
                    elif base_type in ("Standard_Real", "double"):
                        wrapper_str += "%apply (double* IN_ARRAY2, int DIM1, int DIM2) { (double* numpyArray2, int nRows2, int nCols2) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += f"Array2NumpyTemplate({template_name}, double, {base_type})\n"
                    elif base_type in ("Standard_Integer", "int"):
                        wrapper_str += "%apply (long long* IN_ARRAY2, int DIM1, int DIM2) { (long long* numpyArray2, int nRows2, int nCols2) };\n"
                        wrapper_str += "%apply (long long* ARGOUT_ARRAY1, int DIM1) { (long long* numpyArray2Argout, int aSizeArgout) };\n"
                        wrapper_str += f"Array2NumpyTemplate({template_name}, long long, {base_type})\n"
                    # 2D elements
                    elif base_type in ["gp_XY", "gp_Vec2d", "gp_Pnt2d", "gp_Dir2d"]:
                        wrapper_str += "%apply (double* IN_ARRAY3, int DIM1, int DIM2, int DIM3) { (double* numpyArray3, int nRows3, int nCols3, int nDims3) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray3Argout, int aSizeArgout) };\n"
                        wrapper_str += (
                            f"Array2Of2DNumpyTemplate({template_name}, {base_type})\n"
                        )
                    # 3D elements
                    elif base_type in ["gp_XYZ", "gp_Vec", "gp_Pnt", "gp_Dir"]:
                        wrapper_str += "%apply (double* IN_ARRAY3, int DIM1, int DIM2, int DIM3) { (double* numpyArray3, int nRows3, int nCols3, int nDims3) };\n"
                        wrapper_str += "%apply (double* ARGOUT_ARRAY1, int DIM1) { (double* numpyArray3Argout, int aSizeArgout) };\n"
                        wrapper_str += (
                            f"Array2Of3DNumpyTemplate({template_name}, {base_type})\n"
                        )
                    else:
                        wrapper_str += f"%template({template_name}) {template_type};\n"
                    pyi_str += NCOLLECTION_ARRAY2_EXTEND_TEMPLATE_PYI.substitute(
                        {
                            "NCollection_Array2_Template_Instanciation": template_name,
                            "Type_T": f"{basetype_hint}",
                        }
                    )
                    if (
                        base_type in _NUMPY_ARRAY_BASE_TYPES
                        and base_type != "Poly_Triangle"
                    ):
                        pyi_str += NCOLLECTION_ARRAY_NUMPY_PYI
                elif "NCollection_List" in template_type:
                    wrapper_str += f"%template({template_name}) {template_type};\n"
                    # derive the matching ListIterator typedef name from the
                    # list typedef (TopTools_ListOfShape -> TopTools_ListIteratorOfListOfShape)
                    list_iter_name = template_name.replace(
                        "ListOf", "ListIteratorOfListOf", 1
                    )
                    wrapper_str += NCOLLECTION_LIST_EXTEND_TEMPLATE.substitute(
                        {
                            "NCollection_List_Template_Instanciation": template_type,
                            "NCollection_ListIterator_Name": list_iter_name,
                        }
                    )
                    pyi_str += NCOLLECTION_LIST_EXTEND_TEMPLATE_PYI.substitute(
                        {
                            "NCollection_List_Template_Instanciation": template_name,
                            "Type_T": f"{basetype_hint}",
                        }
                    )
                elif "NCollection_Sequence" in template_type:
                    wrapper_str += f"%template({template_name}) {template_type};\n"
                    wrapper_str += NCOLLECTION_SEQUENCE_EXTEND_TEMPLATE.substitute(
                        {"NCollection_Sequence_Template_Instanciation": template_type}
                    )
                    pyi_str += NCOLLECTION_SEQUENCE_EXTEND_TEMPLATE_PYI.substitute(
                        {
                            "NCollection_Sequence_Template_Instanciation": template_name,
                            "Type_T": f"{basetype_hint}",
                        }
                    )
                elif "NCollection_DataMap" in template_type:
                    # NCollection_Datamap is similar to a Python dict,
                    # it's a (key, value) store. Defined as
                    # template < class TheKeyType,
                    # class TheItemType,
                    # class Hasher = NCollection_DefaultHasher<TheKeyType> >
                    # some occt methods return such an object, but the iterator can't be accessed
                    # through Python. Se we extend this class with a Keys() method that iterates over
                    # NCollection_DataMap keys and returns a Python list of key objects.
                    # Note : works for standard_Integer keys only so far
                    # occt-800: ignore Items()/KeyValues() returning ItemsView<...>
                    # which is non-default-constructible and cannot be wrapped by SWIG
                    wrapper_str += f"%ignore {template_type}::Items;\n"
                    wrapper_str += f"%ignore {template_type}::KeyValues;\n"
                    wrapper_str += f"%template({template_name}) {template_type};\n"
                    if "<Standard_Integer" in template_type or "<int" in template_type:
                        wrapper_str += NCOLLECTION_DATAMAP_EXTEND_TEMPLATE.substitute(
                            {
                                "NCollection_DataMap_Template_Instanciation": template_type,
                                "NCollection_DataMap_Template_Name": template_name,
                            }
                        )
                elif (
                    "NCollection_IndexedMap" in template_type
                    or "NCollection_IndexedDataMap" in template_type
                ):
                    # occt-800: NCollection_IndexedMap/IndexedDataMap expose
                    # IndexedItems()/Items()/KeyValues() returning a non-default-
                    # constructible View<...>. SWIG cannot wrap them.
                    wrapper_str += f"%ignore {template_type}::Items;\n"
                    wrapper_str += f"%ignore {template_type}::KeyValues;\n"
                    wrapper_str += f"%ignore {template_type}::IndexedItems;\n"
                    # occt-800rc5 bug: Contained() references a non-existent
                    # IndexedDataMapNode::Key field (should be Key1)
                    wrapper_str += f"%ignore {template_type}::Contained;\n"
                    wrapper_str += f"%template({template_name}) {template_type};\n"
                elif template_type.startswith(
                    (
                        "NCollection_HArray1<",
                        "NCollection_HArray2<",
                        "NCollection_HSequence<",
                    )
                ):
                    # occt-800: NCollection_HArray1/HArray2/HSequence are now
                    # plain template classes deriving from Standard_Transient.
                    # Register the typedef -> ALL_HARRAY{1,2}/HSEQUENCE so that
                    # process_handles emits %wrap_handle and process_harrayN
                    # emits the fake class definition + %make_alias (the same
                    # path used in OCCT 7.9 with the DEFINE_HARRAY1 macro).
                    inner = template_type.split("<", 1)[1].rsplit(">", 1)[0].strip()
                    if template_type.startswith("NCollection_HArray1<"):
                        state.all_harray1[template_name] = (
                            f"NCollection_Array1<{inner}>"
                        )
                    elif template_type.startswith("NCollection_HArray2<"):
                        state.all_harray2[template_name] = (
                            f"NCollection_Array2<{inner}>"
                        )
                    else:
                        state.all_hsequence[template_name] = (
                            f"NCollection_Sequence<{inner}>"
                        )
                else:
                    wrapper_str += f"%template({template_name}) {template_type};\n"

        elif (
            template_name.endswith("Iter") or "_ListIteratorOf" in template_name
        ):  # it's a lst iterator, we use another way to wrap the template
            # #%template(TopTools_ListIteratorOfListOfShape) NCollection_TListIterator<TopTools_ListOfShape>;
            if "IteratorOf" in template_name:
                if "::handle" not in template_type:
                    typ = (template_type.split("<")[1]).split(">")[0]
                else:
                    h_typ = (template_type.split("<")[2]).split(">")[0]
                    typ = f"opencascade::handle<{h_typ}>"
            else:  # template_name.endswith("Iter") — guaranteed by the elif above
                typ = template_name.split("Iter")[0]
            wrapper_str += (
                f"%template({template_name}) NCollection_TListIterator<{typ}>;\n"
            )
    wrapper_str += "/* end templates declaration */\n"
    return wrapper_str, pyi_str


def adapt_type_for_hint_typedef(typedef_type_str):
    typedef_type_str = typedef_type_str.replace(" *", "")
    typedef_type_str = typedef_type_str.replace("&OutValue", "")
    typedef_type_str = typedef_type_str.replace("class", "")
    if "char" in typedef_type_str or "Char" in typedef_type_str:
        typedef_type_str = "str"
    if (
        "_int" in typedef_type_str
        or " int" in typedef_type_str
        or " long" in typedef_type_str
    ):
        typedef_type_str = "int"
    if "double" in typedef_type_str:
        typedef_type_str = "float"
    if "void" in typedef_type_str or (
        "VOID" in typedef_type_str and "avoid" not in typedef_type_str
    ):
        typedef_type_str = "None"
    if "GUID" in typedef_type_str:
        typedef_type_str = "str"
    if "size_t" in typedef_type_str:
        typedef_type_str = "int"
    if "struct" in typedef_type_str:
        typedef_type_str = "int"
    return typedef_type_str


def str_in(list_of_patterns, a_string):
    """a utility function that returns True if any of the item
    of the list patterns is in the a_string"""
    return any(patt in a_string for patt in list_of_patterns)


def sort_templates_by_dependency(templates):
    """Order the [template_type, template_name] pairs so that an
    instantiation comes after the typedefs its arguments refer to, e.g.
    Extrema_EPCOfExtPC (Extrema_GGenExtPC<..., Extrema_PCFOfEPCOfExtPC>) after
    Extrema_PCFOfEPCOfExtPC. The input order is kept otherwise."""
    names = {template_name for _, template_name in templates}
    remaining = list(templates)
    ordered = []
    emitted = set()
    while remaining:
        ready = [
            item
            for item in remaining
            if (names & set(re.findall(r"\w+", item[0]))) - {item[1]} <= emitted
        ]
        if not ready:  # circular typedefs, keep them as they are
            ordered.extend(remaining)
            break
        ordered.extend(ready)
        emitted.update(item[1] for item in ready)
        remaining = [item for item in remaining if item not in ready]
    return ordered


def process_typedefs(typedefs_dict):
    """Take a typedef dictionary and returns a SWIG definition string"""
    templates_str = ""
    typedef_pyi_str = ""  # NewTypes related to typedef aliases
    # pythoncode for typedef aliases, to be inserted at the end of the swig interface file
    typedef_aliases_str = "/* class aliases */\n%pythoncode {\n"

    typedef_str = "/* typedefs */\n"
    templates = []
    # careful, there might be some strange things returned by CppHeaderParser
    # they should not be taken into account
    filtered_typedef_dict = filter_typedefs(typedefs_dict)
    # we check if there is any type def type that relies on an opencascade::handle
    # if this is the case, we must add the corresponding python module
    # as a dependency otherwise it leads to a runtime issue

    for template_type in filtered_typedef_dict.values():
        if "opencascade::handle" in template_type:  # we must add a PYTHON DEPENDENCY
            if template_type.count("<") == 2:
                h_typ = (template_type.split("<")[2]).split(">")[0]
            elif template_type.count("<") == 1:
                h_typ = (template_type.split("<")[1]).split(">")[0]
            else:
                logger.warning(
                    "This template type cannot be handled: %s", template_type
                )
                continue
            module = h_typ.split("_")[0]
            # need to be added to the list of dependent object
            if (
                module != state.current_module
                and module not in state.python_module_dependency
                and is_module(module)
            ):
                state.python_module_dependency.append(module)

    # occt-800: a `using Alias = Tpl<Args>;` template alias instantiates a
    # template that may live in another module, with argument types from yet
    # other modules (BRepLProp_SLProps is a GeomLProp_SLPropsBase of a
    # BRepAdaptor_Surface). They all have to be imported, otherwise SWIG
    # wraps the arguments as opaque pointers.
    for alias in sorted(state.template_alias_names):
        if alias in filtered_typedef_dict:
            for identifier in re.findall(
                r"\b[A-Za-z]\w*_\w+\b", filtered_typedef_dict[alias]
            ):
                check_dependency(identifier)

    sorted_list_of_typedefs = sorted(filtered_typedef_dict.keys())
    for typedef_value in sorted_list_of_typedefs:
        # some occttype defs are actually templated classes,
        # for instance
        # typedef NCollection_Array1<Standard_Real> TColStd_Array1OfReal;
        # this must be wrapped as a typedef but rather as an instaicated class
        # the good way to proceed is:
        # %{include "NCollection_Array1.hxx"}
        # %template(TColStd_Array1OfReal) NCollection_Array1<Standard_Real>;
        # we then check if > or < are in the typedef string then we process it.
        typedef_type = filtered_typedef_dict[typedef_value]
        typedef_str += f"typedef {typedef_type} {typedef_value};\n"
        #
        # Check if the typedef is a template
        #
        if str_in(["<", ">"], f"{typedef_type}"):
            templates.append([typedef_type, typedef_value])
        #
        # Check if it's just a class alias
        #
        elif not str_in(["*", ":", " ", "Standard"], f"{typedef_type}"):
            # we create the alias in python
            # e.g.
            # BRepOffsetAPI_= BRepAlgoAPI_Cut
            # only if the type is a module class (exclude char, Standard_Real etc.)
            #
            typedef_module_name = typedef_type.split("_")[0]
            if is_module(typedef_module_name):
                if state.current_module == typedef_module_name:
                    typedef_aliases_str += f"{typedef_value}={typedef_type}\n"
                else:
                    typedef_aliases_str += f"{typedef_value}=OCC.Core.{typedef_module_name}.{typedef_type}\n"
        check_dependency(typedef_type.split()[0])
        # Define a new type, only for aliases
        type_to_define = typedef_type
        match_1 = [
            "<",
            ":",
            "struct",
            "union",
            ")",
            "NCollection_Array1",
            "NCollection_List",
            "NCollection_DataMap",
            "NCollection_Sequence",
        ]
        if typedef_value in state.template_alias_names:
            # occt-800: class instantiated by %template in the .i file. Its
            # methods are those of the template header, not known here.
            typedef_pyi_str += (
                f"\nclass {typedef_value}:"
                "\n    def __init__(self, *args: Any, **kwargs: Any) -> None: ..."
                "\n    def __getattr__(self, name: str) -> Any: ...\n"
            )
            # but for the members added by TEMPLATE_CLASS_EXTENSIONS
            template_class = typedef_type.split("<", 1)[0].strip()
            if template_class in TEMPLATE_CLASS_EXTENSIONS_PYI:
                item_type = typedef_type.split("<", 1)[1].rsplit(">", 1)[0].strip()
                typedef_pyi_str += TEMPLATE_CLASS_EXTENSIONS_PYI[
                    template_class
                ].substitute(
                    Type_T={"double": "float", "int": "int"}.get(item_type, "Any")
                )
        elif (
            all(match not in type_to_define for match in match_1)
            and type_to_define is not None
            and ")" not in typedef_value
        ):
            type_to_define = adapt_type_for_hint_typedef(type_to_define)
            if is_module(type_to_define.split("_")[0]):
                # alias of an OCC class (e.g. GCE2d_MakeSegment is
                # GC_MakeSegment2d): a NewType would only accept an instance
                # of the aliased class as constructor argument
                typedef_pyi_str += f"\n{typedef_value} = {type_to_define}"
            else:
                typedef_pyi_str += (
                    f'\n{typedef_value} = NewType("{typedef_value}", {type_to_define})'
                )
        elif (
            ")" not in typedef_value
            and "(" not in typedef_value
            and ":" not in typedef_value
            and "NCollection_Array1" not in type_to_define
            and "NCollection_List" not in type_to_define
            and "NCollection_DataMap" not in type_to_define
            and "NCollection_Sequence" not in type_to_define
        ):
            typedef_pyi_str += "\n# the following typedef cannot be wrapped as is"
            typedef_pyi_str += f'\n{typedef_value} = NewType("{typedef_value}", Any)'

    # the modules of the template arguments, see ModuleWrapper. Not for the
    # namespace typedefs (IMeshData::VectorOfVertex), that are not wrapped
    # and would make modules import each other (IMeshData and BRepMesh)
    state.template_argument_types = [
        identifier
        for template_type, typedef_name in templates
        if "::" not in typedef_name
        for identifier in re.findall(
            r"\b[A-Za-z]\w*_\w+\b", template_type.split("<", 1)[1]
        )
    ]
    typedef_pyi_str += "\n"
    typedef_str += "/* end typedefs declaration */\n\n"
    # then we process templates
    # at this stage, we get a list as follows
    templates_def, templates_pyi = process_templates_from_typedefs(
        sort_templates_by_dependency(templates)
    )
    templates_str += templates_def
    templates_str += "\n"
    # close aliases
    typedef_aliases_str += "}\n"
    return (
        templates_str + typedef_str,
        typedef_pyi_str + templates_pyi,
        typedef_aliases_str,
    )


def adapt_enum_value(enum_value):
    """Take for example Graphic3d_TextureSetBits.hxx

    //! Standard texture units combination bits.
    enum Graphic3d_TextureSetBits
    {
      Graphic3d_TextureSetBits_NONE              = 0,
      Graphic3d_TextureSetBits_BaseColor         = (unsigned int )(1 << int(Graphic3d_TextureUnit_BaseColor)),
      Graphic3d_TextureSetBits_Emissive          = (unsigned int )(1 << int(Graphic3d_TextureUnit_Emissive)),
      Graphic3d_TextureSetBits_Occlusion         = (unsigned int )(1 << int(Graphic3d_TextureUnit_Occlusion)),
      Graphic3d_TextureSetBits_Normal            = (unsigned int )(1 << int(Graphic3d_TextureUnit_Normal)),
      Graphic3d_TextureSetBits_MetallicRoughness = (unsigned int )(1 << int(Graphic3d_TextureUnit_MetallicRoughness)),
    };

    The values (unsigned int )(1 << int(Graphic3d_TextureUnit_BaseColor)) cannot be processed as is by SWIG.
    We transform them to Graphic3d_TextureUnit_BaseColor
    """
    if isinstance(enum_value, int) or "int (" not in enum_value:
        return enum_value

    return enum_value.split("int ( ")[1].split(")")[0].strip()


def process_enums(enums_list):
    """Take an enum list and generate a compliant SWIG string
    Then create a python class that mimics the enum
    for instance, from the TopAbs_Orientation.hxx header, we have
    enum TopAbs_Orientation
    {
    TopAbs_FORWARD,
    TopAbs_REVERSED,
    TopAbs_INTERNAL,
    TopAbs_EXTERNAL
    };

    In SWIG, this will be wrapped in the interface file as

    enum TopAbs_Orientation {
      TopAbs_FORWARD = 0,
      TopAbs_REVERSED = 1,
      TopAbs_INTERNAL = 2,
      TopAbs_EXTERNAL = 3,
    };

    However, python does not know anything about TopAbs_Orientation, he only knows TopAbs_FORWARD
    So we also create a python class that mimics the enum and let python know about the TopAbs_Orientation type

    %pythoncode {
    class TopAbs_Orientation:
        TopAbs_FORWARD = 0
        TopAbs_REVERSED = 1
        TopAbs_INTERNAL = 2
        TopAbs_EXTERNAL = 3
    }

    Then, from python, it's possible to use:
    >>> TopAbs_Orientation.TopAbs_FORWARD

    Note: this only makes sense for named enums
    """
    enum_str = "/* public enums */\n"

    enum_python_proxies = "/* python proxy classes for enums */\n" + "%pythoncode {\n"
    enum_pyi_str = ""
    # loop over enums
    for enum in enums_list:
        number_of_string_aliases = 0
        # count the number of lines such
        # as Quantity_NOC_GREEN1 = Quantity_NOC_GREEN
        # in this case, the integers must ne be incremented
        # in the wrapper otherwise ther's an offset
        alias_str = ""
        # stub only: SWIG names the values of a scoped enum Enum_Value
        scoped_alias_str = ""
        python_proxy = True
        if "name" not in enum:
            enum_name = ""
            python_proxy = False
        else:
            enum_name = enum["name"]
            if enum_name not in state.all_enums:
                state.all_enums.append(enum_name)

        if enum_name in ENUMS_TO_EXLUDE:
            logger.info("Skipping Enum: %s", enum_name)
            continue

        # occt-800: respect "enum class X" (scoped enum) so values like
        # gp_Dir::D::X don't collide with member functions like gp_Dir::X()
        is_enum_class = enum.get("isclass", False)
        enum_keyword = "enum class" if is_enum_class else "enum"
        logger.info("Enum: %s", enum_name)
        enum_str += f"{enum_keyword} {enum_name}" + " {\n"
        if python_proxy:
            enum_python_proxies += f"\nclass {enum_name}(IntEnum):\n"
            enum_pyi_str += f"\nclass {enum_name}(IntEnum):\n"
        for enum_value in enum["values"]:
            adapted_enum_value = adapt_enum_value(enum_value["value"])
            if state.current_module == "Quantity":
                # special case for Quantity_Color
                if isinstance(adapted_enum_value, str):
                    # if adapted_enum_value.isalpha():
                    number_of_string_aliases += 1
                else:
                    adapted_enum_value -= number_of_string_aliases
            enum_str += f"\t{enum_value['name']} = {adapted_enum_value},\n"
            if python_proxy:
                # occt-800: rename enum members that collide with Python
                # keywords (e.g. `None` in GProp_PEquation::Type)
                py_name = enum_value["name"]
                if py_name in keyword.kwlist:
                    py_name = f"{py_name}_"
                enum_python_proxies += f"\t{py_name} = {adapted_enum_value}\n"
                # mypy: enum members must be left unannotated
                pyi_value = (
                    adapted_enum_value if isinstance(adapted_enum_value, int) else "..."
                )
                enum_pyi_str += f"    {py_name} = {pyi_value}\n"
                # then, in both proxy and stub files, we create the alias for each named enum,
                # for instance
                # gp_IntrisicXYZ = gp_EulerSequence.gp_IntrinsicXYZ
                alias_str += f"{py_name} = {enum_name}.{py_name}\n"
                if is_enum_class:
                    # SWIG prefixes a python keyword with _, e.g. Type__None
                    swig_value_name = (
                        f"_{enum_value['name']}"
                        if enum_value["name"] in keyword.kwlist
                        else enum_value["name"]
                    )
                    scoped_alias_str += (
                        f"{enum_name}_{swig_value_name} = {enum_name}.{py_name}\n"
                    )
            else:
                # anonymous enum (e.g. the MeshVS_DMF_* flags): SWIG exposes
                # its values as module constants
                enum_pyi_str += f"{enum_value['name']}: int\n"
        enum_python_proxies += alias_str
        enum_pyi_str += "\n" + alias_str + scoped_alias_str
        enum_str += "};\n\n"

    enum_python_proxies += "};\n"
    enum_str += "/* end public enums declaration */\n\n"
    enum_python_proxies += "/* end python proxy for enums */\n\n"
    return enum_str + enum_python_proxies, enum_pyi_str


def is_return_type_enum(return_type):
    """This method returns True is an enum is returned. For instance:
    BRepCheck_Status &
    BRepCheck_Status
    """
    return any(r in state.all_enums for r in return_type.split())


def _apply_typedef_rewrites(text):
    """Repeatedly substitute canonical NCollection template forms with
    their typedef aliases until the string stabilises. Multiple passes are
    required because nested templates are usually defined in terms of
    other typedefs (e.g. NCollection_List<TopoDS_Shape> -> TopTools_ListOfShape
    must run before the IndexedDataMap that contains it can match)."""
    if not state.harray_typedef_rewrites:
        return text
    # CppHeaderParser emits ">>" as "> >" - collapse the gap so the rewrite
    # keys (which are normalized) match.
    text = re.sub(r">\s+>", ">>", text)
    for _ in range(5):  # bounded loop, 5 nesting levels is more than enough
        prev = text
        for tpl, name in state.harray_typedef_rewrites:
            if tpl in text:
                text = text.replace(tpl, name)
        if text == prev:
            break
    return text


def adapt_param_type(param_type):
    param_type = param_type.strip()
    # occt-800: rewrite canonical NCollection<...> forms back to the typedef
    # alias so SWIG type tags match across modules. The list is built from
    # TopTools_/TColgp_/TColStd_/... headers in scan_typedef_aliases().
    param_type = _apply_typedef_rewrites(param_type)
    if "CString" in param_type:
        param_type = param_type.replace("const Standard_CString", "Standard_CString")
        param_type = param_type.replace("Standard_CString &", "Standard_CString")
    param_type = param_type.replace("DrawType", "NIS_Drawer::DrawType")
    if param_type == "const TCollection_AsciiString &":
        param_type = "TCollection_AsciiString"
    if param_type == "const TCollection_ExtendedString &":
        param_type = "TCollection_ExtendedString"
    # some enums are type defs and not properly handled by swig
    # these are Standard_Integer
    for pattern in STANDARD_INTEGER_TYPEDEF:
        if pattern in param_type:
            if "const" in param_type and "&" in param_type:
                # const pattern is wrapped as an integer
                param_type = param_type.replace(pattern, "int")
                param_type = param_type.replace("const", "")
                param_type = param_type.replace("&", "")
            elif "const" in param_type:
                param_type = param_type.replace("const", "")
                param_type = param_type.replace(pattern, "int")
            elif "&" in param_type:  # pattern & is an out value
                param_type = param_type.replace("&", "")
                param_type = param_type.replace(pattern, "Standard_Integer &OutValue")
            elif pattern == param_type:
                param_type = param_type.replace(pattern, "int")
            else:
                logger.warning("Unknown pattern in Standard_Integer typedef")
    # replace Standard_IStream with std::istream
    # so that SWIG template can apply
    param_type = param_type.replace("Standard_IStream", "std::istream")
    param_type = param_type.replace("Standard_SStream", "std::stringstream")
    param_type = param_type.strip()
    check_dependency(param_type)
    return param_type


def adapt_param_type_and_name(param_type_and_name):
    """We sometime need to replace some argument type and name
    to properly deal with byref values
    """
    # bool, int and double passed by reference in c++
    if (
        ("Standard_Real &" in param_type_and_name)
        or ("Quantity_Parameter &" in param_type_and_name)
        or ("Quantity_Length &" in param_type_and_name)
        or ("V3d_Coordinate &" in param_type_and_name)
        or (param_type_and_name.startswith("double &"))
    ) and "const" not in param_type_and_name:
        adapted_param_type_and_name = "Standard_Real &OutValue"
    elif (
        ("Standard_ShortReal &" in param_type_and_name)
        or (param_type_and_name.startswith("float &"))
    ) and "const" not in param_type_and_name:
        adapted_param_type_and_name = "Standard_ShortReal &OutValue"
    elif (
        ("Standard_Integer &" in param_type_and_name)
        or (param_type_and_name.startswith("int &"))
    ) and "const" not in param_type_and_name:
        adapted_param_type_and_name = "Standard_Integer &OutValue"
    elif (
        "Standard_OStream&" in param_type_and_name
        or "Standard_OStream &" in param_type_and_name
        or "std::ostream&" in param_type_and_name
        or "std::ostream &" in param_type_and_name
    ):
        adapted_param_type_and_name = "std::ostream &OutValue"
    elif (
        ("Standard_Boolean &" in param_type_and_name)
        or (param_type_and_name.startswith("bool &"))
    ) and "const" not in param_type_and_name:
        adapted_param_type_and_name = "Standard_Boolean &OutValue"
    elif (
        "opencascade::handle<TCollection_HAsciiString> &" in param_type_and_name
    ) and "const" not in param_type_and_name:
        adapted_param_type_and_name = (
            "opencascade::handle<TCollection_HAsciiString> &OutValue"
        )
    # some enums can also be passed as reference, among them
    # we look for getenirc patterns such as
    # TopAbs_Orientation &Or
    # FairCurve_AnalysisCode &Code
    # etc.
    elif (param_type_and_name.split()[0] in state.all_enums) and (
        param_type_and_name.split()[1].startswith("&")
    ):
        enum_name = param_type_and_name.split()[0]
        if enum_name not in state.all_byref_enums:
            state.all_byref_enums.append(enum_name)
        logger.info(
            "Enum passed by reference: %s changed to %s &OutValue",
            param_type_and_name,
            enum_name,
        )
        adapted_param_type_and_name = f"{enum_name} &OutValue"
    else:
        adapted_param_type_and_name = param_type_and_name
    if "& &" in adapted_param_type_and_name:
        adapted_param_type_and_name = adapted_param_type_and_name.replace("& &", "&")
    return adapted_param_type_and_name


def check_dependency(item):
    """For any type or class name passe to this function,
    returns the module name to which it belongs.
    a. Handle_Geom_Curve -> Geom
    b. Handle ( Geom2d_Curve) -> Geom2d
    c. opencascade::handle<TopoDS_TShape> -> TopoDS
    d. TopoDS_Shape -> TopoDS
    For the case 1 (a, b, c), the module has to be added to the headers list
    For the case 2 (d), the module TopoDS.i has to be added as a dependency in
    order that the class hierarchy is propagated.
    """
    if not item:
        return False
    filt = [
        "const ",
        "static ",
        "virtual ",
        "clocale_t",
        "pointer",
        "size_type",
        "void",
        "reference",
        "const_",
        "inline ",
    ]
    for f in filt:
        item = item.replace(f, "")
    if not item:  # if item list is empty
        return False
    # the element can be either a template ie Handle(Something) else Something_
    # or opencascade::handle<Some_Class>
    if item.startswith("Handle ("):
        item = item.split("Handle ( ")[1].split(")")[0].strip()
        module = item.split("_")[0]
    elif item.startswith("Handle_"):
        module = item.split("_")[1]
    elif item.startswith("opencascade::handle<"):
        item = item.split("<")[1].split(">")[0].strip()
        module = item.split("_")[0]
    elif item.startswith("occ::handle<"):
        # occt-800 introduced the occ::handle alias for opencascade::handle
        item = item.split("<")[1].split(">")[0].strip()
        module = item.split("_")[0]
    elif item.count("_") > 0:  # Standard_Integer or NCollection_CellFilter_InspectorXYZ
        module = item.split("_")[0]
    else:  # do nothing, it's a trap
        return False
    # we strip the module, who knows, there maybe trailing spaces
    module = module.strip()
    # TODO : is the following line really necessary ?
    if module == "Font":  # forget about Font dependencies, issues with FreeType
        return True
    # need to be added to the list of dependent object
    if (
        module != state.current_module
        and module not in state.python_module_dependency
        and is_module(module)
    ):
        state.python_module_dependency.append(module)
    return module


def _is_returned_as_copy(return_type):
    """The const references to curves and surfaces are wrapped as copies."""
    return (
        "const" in return_type
        and "&" in return_type
        and ("Surface" in return_type or "Curve" in return_type)
        and "handle" not in return_type
    )


def adapt_return_type(return_type):
    """adapt the type definition"""
    replaces = [
        "public",
        "protected : private",  # TODO: CppHeaderParser may badly parse these methods
        "DEFINE_NCOLLECTION_ALLOC :",
        "DEFINE_NCOLLECTION_ALLOC",
    ]
    for replace in replaces:
        return_type = return_type.replace(replace, "")
    return_type = return_type.strip()
    # occt-800: rewrite canonical NCollection<...> forms back to typedef alias
    return_type = _apply_typedef_rewrites(return_type)

    if _is_returned_as_copy(return_type):
        logger.warning("%s wrapped as a copy", return_type)
        return_type = return_type.replace("const", "")
        return_type = return_type.replace("&", "").strip()
        # the module of the returned type must be imported, else SWIG
        # returns an opaque pointer (TColGeom_SequenceOfCurve in HelixGeom)
        check_dependency(return_type)
        return return_type
    # replace Standard_CString with char *
    return_type = return_type.replace("const Standard_CString", "Standard_CString")
    return_type = return_type.replace("Standard_CString &", "Standard_CString")
    # remove const if const virtual double *
    return_type = return_type.replace(": static", "static")
    return_type = return_type.replace(": const", "const")
    return_type = return_type.replace("const virtual double *", "virtual double *")
    return_type = return_type.replace(
        "TAncestorMap", "TopTools_IndexedDataMapOfShapeListOfShape"
    )
    # for instance "const TopoDS_Shape & -> ["const", "TopoDS_Shape", "&"]
    # opencascade::handle may contain extra spaces, that has to be removed
    if "opencascade::handle" in return_type:
        return_type = return_type.replace(" >", ">")
    if _is_reference_returned_by_value(return_type):
        return_type = return_type.replace("&", "").strip()
    check_dependency(return_type)
    # check is it is an enum
    if is_return_type_enum(return_type) and "&" in return_type:
        # remove the reference
        return_type = return_type.replace("&", "")
    return return_type


def _is_reference_returned_by_value(return_type):
    """The references to the gp and TopoDS classes are returned by value."""
    return (("gp" in return_type) and "TColgp" not in return_type) or (
        "TopoDS" in return_type
    )


def adapt_function_name(f_name):
    """Some function names may result in errors with SWIG"""
    return f_name.replace("operator", "operator ")


def get_module_docstring(module_name):
    """The module docstring is not provided anymore in cdl files since
    opencascade 7 and higher was released.
    Instead, the link to the official package documentation is
    used, for instance, for the gp package:
    https://www.opencascade.com/doc/occt-7.4.0/refman/html/package_gp.html
    """
    module_docstring = f"{module_name} module, see official documentation at\n"
    module_docstring += f"{DOC_URL}/package_{module_name.lower()}.html"
    return module_docstring


def process_function_docstring(f):
    """Create the docstring, for the function f,
    that will be used by the wrapper.
    For that, first check the function parameters and type
    then add the doxygen value.
    We use the numpy doc docstring convention see
    https://numpydoc.readthedocs.io/en/latest/format.html
    """
    function_name = f["name"]
    function_name = adapt_function_name(function_name)
    string_to_return = '\t\t%feature("autodoc", "'
    # the returns
    ret = []
    # first process parameters
    parameters_string = ""
    if f["parameters"]:  # at least one element in the list, i.e. at least one parameter
        # we add a "Parameters section"
        parameters_string += "\nParameters\n----------\n"
        for param in f["parameters"]:
            param_type = adapt_param_type(param["type"])
            # remove const and &
            param_type = fix_type(param_type)
            # we change opencascade::handle<XXX> & to XXX
            if "opencascade::handle" in param_type:
                param_type = param_type.split("opencascade::handle<")[1].split(">")[0]
            # in the docstring, we don't care about the "&"
            # it's not the matter of a python user
            param_type = param_type.replace("&", "")
            # same for the const
            param_type = param_type.replace("const", "")
            param_type = param_type.strip()
            # a TCollection_AsciiString expects a str
            if param_type in ["TCollection_AsciiString", "TCollection_ExtendedString"]:
                param_type = "str"
            # check the &OutValue
            the_type_and_name = param["type"] + param["name"]
            if "OutValue" in adapt_param_type_and_name(the_type_and_name):
                # this parameter has to be added to the
                # returns, not the parameters of the python method
                ret.append(f"{param['name']}: {param_type}")
                continue
            # add the parameter to the list
            parameters_string += f"{param['name']}: {param_type}"
            if "defaultValue" in param:
                def_value = adapt_default_value(param["defaultValue"])
                parameters_string += f" (optional, default to {def_value})"
            parameters_string += "\n"
        parameters_string += "\n"

    # return types:
    returns_string = "Return\n-------\n"
    method_return_type = adapt_return_type(f["rtnType"])
    if ret:  # at least on by ref parameter
        for r in ret:
            returns_string += f"{r}\n"
    elif method_return_type != "void":
        method_return_type = method_return_type.replace("&", "")
        # ret = ret.replace("virtual", "")
        method_return_type = fix_type(method_return_type)
        method_return_type = method_return_type.replace(": static ", "")
        method_return_type = method_return_type.replace("static ", "")
        method_return_type = method_return_type.strip()
        returns_string += f"{method_return_type}\n"
    else:
        returns_string += "None\n"
    returns_string += "\n"

    # process doxygen strings
    doxygen_string = "No available documentation.\n"
    # since occt-7.9.0, doxygen strings are slightly changed
    # have to remove the first line //@name if ever it is present
    if "doxygen" in f:
        doxygen_string = f["doxygen"]
        if doxygen_string.startswith("//! @name "):
            doxy_lines = doxygen_string.split("\n")
            doxygen_string = "\n".join(doxy_lines[1:])
    if "doxygen" not in f or len(doxygen_string) <= 5:
        doxygen_string = "No available documentation.\n"
    else:  # process doxygen string
        # remove comment separator
        doxygen_string = doxygen_string.replace("//! ", "")
        # replace " with '
        doxygen_string = doxygen_string.replace('"', "'")
        # remove ??/ that causes a compilation issue in InterfaceGraphic
        doxygen_string = doxygen_string.replace("??", "")
        # remove <br>
        # first, a strange thing in BSplClib
        doxygen_string = doxygen_string.replace("\\ <br>", " ")
        doxygen_string = doxygen_string.replace("<br>", "")
        # replace <me> with <self>, which is more pythonic
        doxygen_string = doxygen_string.replace("<me>", "<self>")
        # make '\r' correctly processed
        doxygen_string = doxygen_string.replace(r"\\return", "Return")
        doxygen_string = doxygen_string.replace("\\r", "")
        # replace \n with space
        doxygen_string = doxygen_string.replace("\n", " ")
        doxygen_string = doxygen_string.replace("'\\n'", "A newline")
        # replace TRUE and FALSE with True and False
        doxygen_string = doxygen_string.replace("TRUE", "True")
        doxygen_string = doxygen_string.replace("FALSE", "False")
        # misc
        doxygen_string = doxygen_string.replace("@return", "\nReturn:")
        # the input parameters
        doxygen_string = doxygen_string.replace("@param[in]", "\nInput parameter:")
        doxygen_string = doxygen_string.replace("@param ", "\nParameter ")
        # see also
        doxygen_string = doxygen_string.replace("@sa", "\nSee also:")
        # replace the extra spaces
        doxygen_string = doxygen_string.replace("    ", " ")
        doxygen_string = doxygen_string.replace("   ", " ")
        doxygen_string = doxygen_string.replace("  ", " ")
        doxygen_string = doxygen_string.replace(" : ", ": ")
        if not doxygen_string.endswith("."):
            doxygen_string = f"{doxygen_string}."
        # then remove spaces from start and end
        doxygen_string = doxygen_string.strip() + "\n"
    # concatenate everything
    final_string = (
        parameters_string
        + returns_string
        + "Description\n-----------\n"
        + doxygen_string
    )
    string_to_return += f'{final_string}") {function_name};\n'
    return string_to_return


def adapt_default_value(def_value):
    """adapt default value"""
    def_value = def_value.replace(" ", "")
    def_value = def_value.replace('"', "'")
    def_value = def_value.replace("''", '""')
    if def_value == "0L":  # only in VrmlData
        def_value = "0"
    return def_value


def adapt_default_value_parmlist(param, parent_class=None):
    """adapts default value to be used in swig parameter list"""
    def_value = param["defaultValue"].replace(" ", "")
    # a constant or an enum value of the class: SWIG (compactdefaultargs)
    # evaluates the default value out of the class scope, qualify it
    if parent_class is not None and re.fullmatch(r"[A-Za-z_]\w*", def_value):
        class_names = {p["name"] for p in parent_class["properties"]["public"]}
        for enum in parent_class["enums"]["public"]:
            class_names.update(v["name"] for v in enum.get("values", []))
        if def_value in class_names:
            return f"{parent_class['name']}::{def_value}"
    return def_value


def filter_member_functions(
    class_name, class_public_methods, member_functions_to_exclude, class_is_abstract
):
    """This functions removes member function to exclude from
    the class methods list. Some of the members functions have to be removed
    because they can't be wrapped (usually, this results in a linkage error)

    The member function to exclude are defined by their names or their
    md5 signature. The latter allows selecting which method to exclude
    if there are several different signatures for one same method name.
    """
    # split wrapped methods into two lists
    constructors = []
    other_methods = []

    for public_method in class_public_methods:
        method_name = public_method["name"]
        public_method_signature = get_function_md5_signature(public_method)
        if (method_name in member_functions_to_exclude) or (
            f"{method_name}::{public_method_signature}" in member_functions_to_exclude
        ):
            logger.info(
                "    explicitly excluded method %s::%s",
                class_name,
                public_method_signature,
            )
            continue
        if class_is_abstract and public_method["constructor"]:
            logger.info("    Constructor skipped for abstract class %s", class_name)
            continue
        if "<" in method_name:
            logger.info("    %s skipped because invalid name", method_name)
            continue
        # finally, we add this method to process in the correct list
        if public_method["constructor"]:
            constructors.append(public_method)
        else:
            other_methods.append(public_method)
    return constructors, other_methods


_TYPE_HINT_QUALIFIERS = ("const", "static", "virtual", "inline", "constexpr")
_FIXED_WIDTH_INT_HINT_RE = re.compile(r"u?int(8|16|32|64)_t")


def _builtin_type_hint(type_str):
    """The type hint of a C++ builtin type, whatever its qualifiers (static
    double, const int &, unsigned long...), or of a class named after its
    module (const BRepGraph &). None if type_str is none of those."""
    if "*" in type_str or "<" in type_str or ":" in type_str:
        return None
    words = [
        w for w in type_str.replace("&", " ").split() if w not in _TYPE_HINT_QUALIFIERS
    ]
    if not words:
        return None
    if "&" in type_str and "const" not in type_str:
        # a non const reference: an output parameter (see
        # adapt_param_type_and_name) or, returned, an opaque SWIG pointer
        return None
    if all(w in ("unsigned", "signed", "long", "short", "int") for w in words):
        return "int"
    if len(words) != 1:
        return None
    word = words[0]
    if word in ("double", "float"):
        return "float"
    if word == "bool":
        return "bool"
    if word == "size_t":
        return "int"
    if _FIXED_WIDTH_INT_HINT_RE.fullmatch(word):
        # opaque to SWIG unless the module includes stdint.i, see
        # _write_swig_module_specific_templates
        return "int" if state.flatten_nested_classes else None
    if "_" not in word and is_module(word):
        # %rename(brepgraph) BRepGraph, see process_classes
        return word.lower()
    return None


_NESTED_NAME_RE = re.compile(r"([A-Za-z0-9]+_\w+)::(\w+)")
_class_enums_cache: dict[tuple[str, str], bool] = {}


def _is_class_enum(class_name, enum_name):
    """True if the header of class_name declares the enum enum_name"""
    key = (class_name, enum_name)
    if key not in _class_enums_cache:
        header = OCCT_INCLUDE_DIR / f"{class_name}.hxx"
        try:
            content = header.read_text(encoding="utf8", errors="replace")
        except OSError:
            content = ""
        _class_enums_cache[key] = (
            re.search(rf"\benum\s+(class\s+)?{enum_name}\b", content) is not None
        )
    return _class_enums_cache[key]


_TYPE_QUALIFIERS_RE = re.compile(r"\b(?:const|static|virtual|inline)\b|&")


def _template_typedef_name(type_str):
    """The typedef wrapping a template instantiation, e.g. TColgp_Array1OfPnt
    for `const NCollection_Array1<gp_Pnt > &`, None if there is none."""
    if "<" not in type_str or "OutValue" in type_str:
        return None
    if "&" in type_str and "const" not in type_str:
        # a non const reference is an output parameter
        return None
    canonical = re.sub(r"\s+", "", _TYPE_QUALIFIERS_RE.sub("", type_str))
    if canonical.startswith(("opencascade::handle<", "occ::handle<")):
        # a handle is typed with the class it holds, see adapt_type_for_hint
        return None
    if "::" in canonical:
        # a nested type, e.g. an iterator, not wrapped
        return None
    name = state.template_typedef_names.get(canonical)
    if name is None:
        name = state.typedef_rewrite_names.get(canonical)
    if name is None:
        return None
    if not _stub_can_import(name.split("_")[0]):
        return None
    return name


def _stub_can_import(module):
    """True if the stub of the current module can import module: a module
    it depends on, or a module already processed that does not depend on it,
    else the stubs would import each other (Media and Graphic3d)."""
    if module == state.current_module or module in state.python_module_dependency:
        return True
    if module not in state.module_dependencies:
        return False
    seen = set()
    stack = [module]
    while stack:
        dependency = stack.pop()
        if dependency == state.current_module:
            return False
        if dependency not in seen:
            seen.add(dependency)
            stack.extend(state.module_dependencies.get(dependency, ()))
    return True


def adapt_type_for_hint(type_str):
    """convert c++ types to python types, for type hints
    Returns False if there's no possible type
    """
    if type_str == "0":  # huu ? in XCAFDoc, skip it
        logger.warning("    [TypeHint] Skipping unknown type, 0")
        return False
    typedef_name = _template_typedef_name(type_str)
    if typedef_name is not None:
        return typedef_name
    if "void" in type_str or type_str == "":
        return "None"
    # the substring tests below don't apply to a template argument, e.g.
    # const NCollection_Vec3<float> & is not a float
    is_template = "<" in type_str and not re.match(
        r"(const\s+)?opencascade::handle<", type_str
    )
    if " int" in type_str and not is_template:  # const int, unsigned int etc.
        return "int"
    if ("char *" in type_str or "CString" in type_str) and not is_template:
        return "str"
    if "bool" in type_str and not is_template:
        return "bool"
    if "float" in type_str and not is_template:
        return "float"
    if "integer *" in type_str:
        return "int"
    if "doublereal" in type_str:
        return "float"
    if type_str == "int":
        return "int"
    if type_str == "int *":
        return "int"
    if type_str == "double":
        return "float"
    if type_str == "const double":
        return "float"
    if type_str == "double *":
        return "float"
    if type_str == "opencascade::handle<TCollection_HAsciiString> &OutValue":
        return "str"
    if type_str == "std::istream &":
        return "str"
    if "std::ostream &" in type_str:
        return "str"
    builtin_hint = _builtin_type_hint(type_str)
    if builtin_hint is not None:
        return builtin_hint
    if "_" not in type_str:  # TODO these are special cases, e.g. nested classes
        logger.warning("    [TypeHint] Skipping type %s, should contain _", type_str)
        return False  # returns a boolean to prevent type hint creation, the type will not be found
    # we only keep what is
    for tp in type_str.split(" "):
        if "_" in tp:
            type_str = tp.strip()
            break

    type_str = type_str.replace("Standard_Integer", "int")
    type_str = type_str.replace("Standard_Real", "float")
    type_str = type_str.replace("Standard_ShortReal", "float")
    type_str = type_str.replace("Standard_Boolean", "bool")
    type_str = type_str.replace("Standard_Character", "str")
    type_str = type_str.replace("Standard_Byte", "str")
    type_str = type_str.replace("Standard_Address", "None")
    type_str = type_str.replace("Standard_Size", "int")
    type_str = type_str.replace("Standard_Time", "float")

    # transform opencascade::handle<Message_Alert> to return Message_Alert
    if type_str.startswith("opencascade::handle<"):
        type_str = type_str[20:].split(">")[0].strip()
    nested_enum = _NESTED_NAME_RE.fullmatch(type_str)
    if (
        nested_enum
        and nested_enum.group(1) not in state.unwrapped_classes
        and _is_class_enum(*nested_enum.groups())
    ):
        # e.g. gp_Dir::D, whose stub is written in the class body
        return f"{nested_enum.group(1)}.{nested_enum.group(2)}"
    if ":" in type_str:
        logger.warning("    [TypeHint] Skip type %s, because of trailing :", type_str)
        return False
    if "_" in type_str and not is_module(type_str.split("_")[0]):
        logger.warning(
            "    [TypeHint] Skipping unknown type %s, %s not in module list",
            type_str,
            type_str.split("_")[0],
        )
        return False
    if type_str.count("<") >= 1:  # at least one <, it's a template
        logger.warning(
            "    [TypeHint] Skipping type %s, seems to be a template", type_str
        )
        return False

    if type_str in ["TCollection_AsciiString", "TCollection_ExtendedString"]:
        type_str = "str"

    return type_str


def get_classname_from_handle(handle_name):
    """input : opencascade::handle<Something>
    returns: Something
    """
    if handle_name.startswith("opencascade::handle<"):
        return handle_name[20:].split(">")[0].strip()
    raise AssertionError(
        f"Should be an opencascade handle, you provided a {handle_name}"
    )


def adapt_type_hint_parameter_name(param_name_str):
    """some parameter names may conflict with python keyword,
    for instance with, False etc.
    Returns the modified name, and whether to take it into account"""
    if keyword.iskeyword(param_name_str):
        new_param_name = f"{param_name_str}_"
        success = True
    elif param_name_str in ["", "&"]:
        # some parameter names maybe missing
        # for example
        # Standard_EXPORT static int mma1her_(const integer *  ,
        #            doublereal * ,
        #            integer *   );
        logger.warning("    [TypeHint] param name missing or '&', generic name used")
        new_param_name = ""
        success = False
    else:  # default
        new_param_name = param_name_str
        success = True
    if "[" in new_param_name:
        param_name = new_param_name.split("[")[0]
        param_name = param_name.replace(")", "")
        if param_name == "":
            success = False
        else:
            new_param_name = f"{param_name}_list"
            success = True
    return new_param_name, success


def _is_python_expression(expr_str):
    """True if expr_str is a valid python expression where a type hint or a
    default value is expected. A bare tuple such as "OSD_SIGBUS," is not."""
    try:
        ast.parse(f"def _() -> {expr_str}: ...")
    except SyntaxError:
        return False
    return True


def adapt_type_hint_default_value(default_value_str):
    """default values such as Standard_True etc. must be
    converted to correct python values
    """
    if default_value_str in ("Standard_True", "true"):
        new_default_value_str = "True"
    elif default_value_str in ("Standard_False", "false"):
        new_default_value_str = "False"
    elif "Precision::" in default_value_str:
        # the class is renamed precision, and not imported by the other stubs
        new_default_value_str = "..."
    elif default_value_str in ("NULL", "nullptr"):
        new_default_value_str = "None"
    elif "opencascade::handle" in default_value_str:
        # case opencascade::handle<Message_ProgressIndicator>()
        # should be Message_ProgressIndicator()
        classname = get_classname_from_handle(default_value_str)
        if (
            classname == "Message_ProgressIndicator"
        ):  # no constructor defined, abstract class
            new_default_value_str = "'Message_ProgressIndicator()'"
        else:
            new_default_value_str = classname + default_value_str.split(">")[1]
    elif default_value_str.endswith(
        "f"
    ):  # some float values are defined as 0.0f or 0.1f
        str_removed_final_f = default_value_str[:-1]
        try:
            float(str_removed_final_f)
            is_float = True
        except ValueError:
            is_float = False
        new_default_value_str = str_removed_final_f if is_float else default_value_str
    elif default_value_str == "0L":
        new_default_value_str = "0"
    else:
        new_default_value_str = default_value_str
    # C++ expressions such as TCollection_AsciiString::EmptyString() or
    # NCollection_DataMap<...>() are not valid python: use the stub ellipsis
    if not _is_python_expression(new_default_value_str):
        new_default_value_str = "..."
    success = True
    return new_default_value_str, success


def get_function_md5_signature(f):
    """
    Computes the MD5 hash of a function's signature provided in the input dictionary.

    The function's signature is normalized by removing all whitespace and converting
    all characters to lowercase before calculating the MD5 hash. This normalization
    process ensures that insignificant differences in formatting do not affect the
    hash value, providing a consistent identifier for function signatures across
    different releases of tools like cppheaderparser.

    Parameters:
    - f (dict): A dictionary representing the function, where the function's signature
      is expected to be associated with the 'debug' key. The signature is a string
      that typically includes the function's name, return type, and parameter types.

    Returns:
    - str: The MD5 hash of the normalized function signature as a hexadecimal string.

    Note:
    This function is used for excluding specific function signature from
    the wrapper.

    Example:
    >>> function_info = {"debug": "int add(int a, int b)"}
    >>> get_function_md5_signature(function_info)
    '9b74c9897bac770ffc029102a200c5de'
    """
    function_signature = f["debug"]
    # remove spaces, capital letters etc.
    # this id done to prevent the function signature to change
    # between two different releases of cppheaderparser
    # remove all white spaces
    function_signature = "".join(function_signature.split())
    # then lower
    function_signature = function_signature.lower()
    return hashlib.md5(bytes(function_signature, encoding="utf8")).hexdigest()


_OPERATOR_WRAPPERS = {
    "+": None,  # wrapped by SWIG, no need for a custom template
    "-": None,
    "*": None,
    "/": None,
    "==": TEMPLATE__EQ__,
    "!=": TEMPLATE__NE__,
    "+=": TEMPLATE__IADD__,
    "*=": TEMPLATE__IMUL__,
    "-=": TEMPLATE__ISUB__,
    "/=": TEMPLATE__ITRUEDIV__,
}

_PRIMITIVE_BY_REF_RETURNS = {
    "Standard_Integer &",
    "Standard_Real &",
    "Standard_Boolean &",
    "Standard_Integer&",
    "Standard_Real&",
    "Standard_Boolean&",
}


# the python methods of the C++ operators, by operand and number of
# parameters. SWIG wraps the arithmetic ones, the _OPERATOR_WRAPPERS templates
# the others. == and != are not stubbed, object declares them already
_OPERATOR_DUNDERS = {
    ("+", 0): "__pos__",
    ("+", 1): "__add__",
    ("-", 0): "__neg__",
    ("-", 1): "__sub__",
    ("*", 1): "__mul__",
    ("/", 1): "__truediv__",
    ("+=", 1): "__iadd__",
    ("-=", 1): "__isub__",
    ("*=", 1): "__imul__",
    ("/=", 1): "__itruediv__",
}


def _operator_dunder(f, function_name):
    """The python method name of a member operator, None if it has no stub"""
    if f["parent"] is None or f["static"] or f["friend"]:
        return None
    operand = function_name.split("operator ")[1].strip()
    return _OPERATOR_DUNDERS.get((operand, len(f["parameters"])))


def _wrap_operator(f, function_name, parent_class_name):
    """If f is a wrappable C++ operator, return (swig_str, type_hint_str) or
    ('', ''); None if function_name is not an operator at all, or if SWIG
    wraps it natively."""
    if "operator" not in function_name:
        return None
    operand = function_name.split("operator ")[1].strip()
    if operand not in _OPERATOR_WRAPPERS:
        logger.info("    operand %s cannot be wrapped", operand)
        return "", ""
    template = _OPERATOR_WRAPPERS[operand]
    if template is None:
        return None  # SWIG handles +,-,*,/ natively
    param_type = f["parameters"][0]["type"].replace("&", "").strip()
    type_hint = ""
    dunder = _operator_dunder(f, function_name)
    if dunder is not None:
        # the in-place operator returns the instance, see the templates
        param_hint = adapt_type_for_hint(adapt_param_type(f["parameters"][0]["type"]))
        type_hint = (
            "    @overload\n"
            f"    def {dunder}(self, right: {param_hint or 'Any'}) -> typing.Self: ...\n"
        )
    return (
        template.substitute({"TYPE": param_type, "CLASS": parent_class_name}),
        type_hint,
    )


def _build_getter_setter_pair(f, function_name, return_type):
    """Generate a Get*/Set* pair when a method returns a primitive by-ref.
    Returns (swig_str, type_hint_str)."""
    logger.info("    Creating Get and Set methods for method %s", function_name)
    modified_return_type = return_type.split(" ")[0]
    getter_params_type_and_names = []
    getter_params_only_names = []
    getter_param_hints = ["self"]
    for param in f["parameters"]:
        adapted_type = adapt_param_type(param["type"])
        getter_params_type_and_names.append(f"{adapted_type} {param['name']}")
        getter_params_only_names.append(param["name"])
        getter_param_hints.append(
            f"{param['name']}: {adapt_type_for_hint(adapted_type)}"
        )

    setter_params_type_and_names = [
        *getter_params_type_and_names,
        f"{modified_return_type} value",
    ]
    hint_output_type = adapt_type_for_hint(modified_return_type)
    setter_param_hints = [*getter_param_hints, f"value: {hint_output_type}"]

    swig_str = TEMPLATE_GETTER_SETTER.substitute(
        {
            "Return_Type": modified_return_type,
            "Function_Name": function_name,
            "Getter_Parameters_Types_Names": ",".join(getter_params_type_and_names),
            "Getter_Parameters_Names": ",".join(getter_params_only_names),
            "Setter_Parameters_Types_Names": ",".join(setter_params_type_and_names),
        }
    )
    getter_hint_str = TEMPLATE_GETTER_PYI.substitute(
        {
            "Function_Name": function_name,
            "Getter_Parameters_Hints": ", ".join(getter_param_hints),
            "Hint_Output_Type": hint_output_type,
        }
    )
    setter_hint_str = TEMPLATE_SETTER_PYI.substitute(
        {
            "Function_Name": function_name,
            "Setter_Parameters_Hints": ", ".join(setter_param_hints),
        }
    )
    return swig_str, getter_hint_str + setter_hint_str


def _compute_return_type(f):
    """Derive the SWIG-ready return type, accounting for constructors,
    virtual, and static modifiers."""
    return_type = "" if f["constructor"] else adapt_return_type(f["rtnType"])
    if f["virtual"]:
        return_type = "virtual " + return_type
    if f["static"] and "static" not in return_type:
        return_type = "static " + return_type
    if f["static"] and f["parent"] is None:
        return_type = "static " + return_type
    return return_type


def _build_swig_parameter_list(f):
    """Build the SWIG parameter list for a function. Returns
    (parameters_types_and_names, parameters_definition_strs, has_handle_t_ref).
    has_handle_t_ref = True means this function should be skipped entirely."""
    parameters_types_and_names = []
    parameters_definition_strs = []
    for param in f["parameters"]:
        param_type = adapt_param_type(param["type"])
        if "Handle_T &" in param_type:
            # something like a template; would raise a compilation exception
            return None, None, True

        if "array_size" in param:
            # entries are [type, name] or [type, name, default_value]
            param_type_and_name = [
                param_type,
                f"{param['name']}[{param['array_size']}]",
            ]
        else:
            param_type_and_name = [param_type, param["name"]]

        param_string = adapt_param_type_and_name(" ".join(param_type_and_name))
        if "defaultValue" in param:
            def_value = adapt_default_value_parmlist(param, f.get("parent"))
            param_string += f" = {def_value}"
            param_type_and_name.append(def_value)

        parameters_types_and_names.append(param_type_and_name)
        parameters_definition_strs.append(param_string)
    return parameters_types_and_names, parameters_definition_strs, False


_STRING_CLASS_PARAM_RE = re.compile(
    r"^\s*(?:const\s+)?(TCollection_(?:Ascii|Extended)String)\s*(?:&\s*)?$"
)


def _widen_parameter_hint(param_type, hint):
    """The hint of a parameter the typemaps accept in several forms: a
    std::istream from a str or bytes (IOStream.i), a TCollection string from a
    str or an instance (FunctionTransformers.i)."""
    if hint != "str" or state.current_module == "TCollection":
        # the TCollection string classes overload their methods for both
        return hint
    if "istream" in param_type:
        return "str | bytes"
    match = _STRING_CLASS_PARAM_RE.match(param_type)
    if match and ("&" not in param_type or "const" in param_type):
        return f"str | {match.group(1)}"
    return hint


_NON_CONST_HANDLE_REF_RE = re.compile(r"opencascade::handle<[^&]*>\s*&")


_SCALAR_REF_RETURN_RE = re.compile(
    r"^\s*((?:unsigned\s+|signed\s+)?(?:int|long|short|long long|double|float|bool|size_t))\s*&\s*$"
)


def _build_typehint(
    f,
    function_name,
    parameters_types_and_names,
    return_type,
    parent_class_name,
    overload,
):
    """Build the .pyi type-hint string for a function."""
    if "operator" in function_name:
        # an arithmetic operator SWIG wraps natively, e.g. operator+ is
        # __add__. Always declared as an overload, the single ones are fixed
        # once the class is complete, see _drop_single_overloads
        function_name = _operator_dunder(f, function_name)
        if function_name is None:
            return ""
        overload = True

    str_typehint = ""
    # adapt_type_for_hint returns False for a type it can't translate: Any
    # (not the "False" string, which is not a valid type hint)
    # a non-const reference to a scalar is returned by value, see the
    # FunctionTransformers.i out typemaps (int &, double &, bool &...)
    return_type = _SCALAR_REF_RETURN_RE.sub(r"\1", return_type)
    types_returned = [adapt_type_for_hint(return_type) or "Any"]
    all_parameters_type_hint = ["self"]

    if overload:
        str_typehint += "    @overload\n"
    if f["constructor"]:
        str_typehint += "    def __init__("
    else:
        if f["static"]:
            str_typehint += "    @staticmethod\n"
            all_parameters_type_hint = []  # static methods don't take self
            if (
                parent_class_name is not None
                and "<" not in parent_class_name
                and function_name.isalnum()
            ):
                state.deprecated_static_functions.append(
                    (parent_class_name, function_name)
                )
        str_typehint += f"    def {function_name}("

    for i, par in enumerate(parameters_types_and_names):
        ov = adapt_param_type_and_name(" ".join(par))
        if "OutValue" in ov:
            type_to_add = adapt_type_for_hint(ov) or "Any"
            if types_returned[0] == "None":
                types_returned[0] = type_to_add
            else:
                types_returned.append(type_to_add)
            continue
        # a type that can't be translated is written Any, the method is kept
        par_typ = _widen_parameter_hint(par[0], adapt_type_for_hint(par[0]) or "Any")
        # a non-const handle reference is an output: None can be passed, and
        # the handle is also appended to the returned values by the
        # OccHandle.i argout typemap (None if the handle is null)
        is_handle_output = not f["constructor"] and _NON_CONST_HANDLE_REF_RE.fullmatch(
            par[0].strip()
        )
        if is_handle_output:
            par_typ = f"Optional[{par_typ}]"
            if types_returned[0] == "None":
                types_returned[0] = par_typ
            else:
                types_returned.append(par_typ)
        # if there's a default value, the type becomes Optional[type] = value
        if len(par) == 3:
            hint_def_value, adapted = adapt_type_hint_default_value(par[2])
            if is_handle_output:
                par_typ = par_typ[len("Optional[") : -1]
            par_typ = (
                f"Optional[{par_typ}] = {hint_def_value}"
                if adapted
                else f"Optional[{par_typ}]"
            )
        par_nam, success = adapt_type_hint_parameter_name(par[1])
        if not success:
            par_nam = f"arg{i}"
        if par_nam.endswith("_list"):
            par_typ = f"list[{par_typ}]"
        all_parameters_type_hint.append(f"{par_nam}: {par_typ}")

    is_find_attribute = (
        function_name == "FindAttribute"
        and f["parent"] is not None
        and f["parent"]["name"] in ("TDF_Label", "TDF_Attribute")
    )
    if is_find_attribute:
        # the attribute found has the type of the one passed, see below
        all_parameters_type_hint = [
            p.replace(": TDF_Attribute", ": _TDF_AttributeT")
            if p.endswith(": TDF_Attribute")
            else p
            for p in all_parameters_type_hint
        ]
    str_typehint += ", ".join(all_parameters_type_hint)
    if len(types_returned) == 1:
        returned_type_hint = types_returned[0]
    elif len(types_returned) > 1:
        returned_type_hint = f"Tuple[{', '.join(types_returned)}]"
    else:
        raise AssertionError("Method should at least have one returned type.")
    if not _is_python_expression(returned_type_hint):
        # e.g. a std::variant return type mangled by CppHeaderParser
        returned_type_hint = "Any"
    if is_find_attribute:
        # the OccHandle.i typemap returns the attribute (with its dynamic
        # type), or None if not found, in place of the bool result
        returned_type_hint = "Optional[_TDF_AttributeT]"
    str_typehint += f") -> {returned_type_hint}: ...\n"
    return str_typehint


_PYI_METHOD_DEF_RE = re.compile(r"^    def (\w+)\(", re.MULTILINE)


def _drop_single_overloads(class_pyi):
    """Remove the @overload decorator of the methods of a class stub that are
    declared once: a lone overload is an error for the type checkers"""
    counts = Counter(_PYI_METHOD_DEF_RE.findall(class_pyi))
    lines = class_pyi.split("\n")
    kept = []
    for i, line in enumerate(lines):
        if line == "    @overload":
            j = i + 1
            while j < len(lines) and lines[j].startswith("    @"):
                j += 1
            match = _PYI_METHOD_DEF_RE.match(lines[j]) if j < len(lines) else None
            if match and counts[match.group(1)] == 1:
                continue
        kept.append(line)
    return "\n".join(kept)


def _should_skip_function(f, function_name):
    """Early-return cases where the function should not be wrapped at all."""
    if f["destructor"] or f["returns"] == "~":
        return True
    if f.get("deleted"):  # occt-800: e.g. `X(const X&) = delete;` in public sections
        return True
    if "TYPENAME" in f["rtnType"]:  # something in NCollection
        return True
    if function_name in ("DEFINE_STANDARD_RTTIEXT", "Handle"):
        # Handle (something) func can not be handled by swig
        return True
    if re.fullmatch(r"operator[A-Za-z_]\w*", function_name):
        # conversion operator, e.g. operator BRepGraph_NodeId()
        return True
    if any(_is_unqualified_nested_type(param["type"]) for param in f["parameters"]):
        return True
    if state.flatten_nested_classes:
        return _should_skip_unwrappable_function(f)
    return False


# typedefs declared in a base class and used unqualified in the derived
# classes: the wrapper function is not in the class scope, the type is not
# found there (DE_Provider::ReadStreamList in DESTEP_Provider::Read)
_UNQUALIFIED_NESTED_TYPES = frozenset({"ReadStreamList", "WriteStreamList"})


def _is_unqualified_nested_type(param_type):
    """True for a parameter type of _UNQUALIFIED_NESTED_TYPES"""
    base = re.sub(r"\bconst\b|[&*]", "", param_type).strip()
    return base in _UNQUALIFIED_NESTED_TYPES


def _should_skip_unwrappable_function(f):
    """occt-800: the move-only and non copyable classes of BRepGraph. SWIG
    binds an rvalue reference as an lvalue one and copies the values it
    returns, which the compiler rejects for these classes. The other
    modules keep their wrappers: an rvalue reference constructor is wrapped
    as the copy constructor there."""
    for param in f["parameters"]:
        # an rvalue reference, e.g. a move constructor X(X&&): CppHeaderParser
        # reports the type 'X & &' when the parameter is named, 'X &' and the
        # name '&' otherwise
        param_type = param.get("type", "").rstrip()
        if "& &" in param_type or "&&" in param_type:
            return True
        if param.get("name") == "&" and param_type.endswith("&"):
            return True
    if "&&" in f.get("debug", ""):
        # the raw declaration has an rvalue reference CppHeaderParser lost
        return True
    if (
        f["constructor"]
        and f["parent"] is not None
        and len(f["parameters"]) == 1
        and f["parameters"][0]["type"].replace("const", "").strip()
        == f["parent"]["name"]
        and "&" not in f["parameters"][0]["type"]
    ):
        # X(X theOther): a move constructor X(X&&) whose reference was lost,
        # a copy constructor by value does not exist in C++
        return True
    # returned by value, SWIG would copy a class that is not wrapped
    rtn_type = f["rtnType"].replace("const", "").strip()
    return (
        "&" not in rtn_type
        and "*" not in rtn_type
        and rtn_type.split("<")[0].strip() in state.unwrapped_classes
    )


def process_function(f, overload=False):
    """Generate SWIG bindings + a .pyi type hint for a single C++ function.

    Returns (swig_str, type_hint_str). Either may be empty when the function
    is intentionally skipped; swig_str may be False when the function would
    cause a SWIG compilation error.
    """
    function_signature_md5 = get_function_md5_signature(f)
    if f["template"]:
        return False, ""
    function_name = adapt_function_name(f["name"])

    if _should_skip_function(f, function_name):
        return "", ""

    if f["static"] and f["parent"] is not None:
        parent_class_name = f["parent"]["name"]
        if parent_class_name == state.current_module:
            parent_class_name = parent_class_name.lower()
    else:
        parent_class_name = None

    operator_result = _wrap_operator(f, function_name, parent_class_name)
    if operator_result is not None:
        return operator_result

    state.nb_total_methods += 1

    if function_name == "DumpJson":
        return TEMPLATE_DUMPJSON, TEMPLATE_DUMPJSON_PYI
    if function_name == "InitFromJson":
        return TEMPLATE_INITFROMJSON, TEMPLATE_INITFROMJSON_PYI

    # only wrap free functions that live in the current module's namespace
    function_namespace = f["namespace"]
    function_parent_class_name = f["parent"]["name"] if f["parent"] is not None else ""
    if (
        function_namespace[:-2] != state.current_module
        and function_parent_class_name == ""
    ):
        return "", ""

    # Build the docstring before _compute_return_type so the order of
    # check_dependency() calls (which append to state.python_module_dependency)
    # matches the legacy single-block implementation: parameter deps land
    # before return-type deps.
    docstring = process_function_docstring(f)
    return_type = _compute_return_type(f)
    if return_type in _PRIMITIVE_BY_REF_RETURNS:
        return _build_getter_setter_pair(f, function_name, return_type)

    # SWIG declaration prefix
    str_function = (
        f"\t\t/****** {function_parent_class_name}::{function_name} ******/\n"
        f"\t\t/****** md5 signature: {function_signature_md5} ******/\n"
        f'\t\t%feature("compactdefaultargs") {function_name};\n'
        + docstring
        + f"\t\t{return_type} {function_name}"
    )

    parameters_types_and_names, parameters_definition_strs, skip = (
        _build_swig_parameter_list(f)
    )
    if skip:
        return False, ""

    str_function += "(" + ", ".join(parameters_definition_strs) + ");\n"
    str_typehint = _build_typehint(
        f,
        function_name,
        parameters_types_and_names,
        return_type,
        parent_class_name,
        overload,
    )

    # collapse occasional duplicate "const const" produced by adapt_return_type
    str_function = str_function.replace("const const", "const") + "\n"
    return str_function, str_typehint


def process_free_functions(free_functions_list: list[dict]):
    """process a string for free functions"""
    str_free_functions = ""
    sorted_free_functions_list = sorted(free_functions_list, key=itemgetter("name"))
    for free_function in sorted_free_functions_list:
        # skip namespaced free functions, SWIG would emit them at file scope
        # and the C++ compiler would not find the symbol (occt-800 introduces
        # several functions in inner namespaces such as BVH::EncodeMortonCode)
        if free_function.get("namespace", ""):
            logger.info(
                "    Skipping namespaced free function %s%s",
                free_function.get("namespace", ""),
                free_function["name"],
            )
            continue
        ok_to_wrap = process_function(free_function)
        if ok_to_wrap:
            str_free_functions += ok_to_wrap
    return str_free_functions


def process_constructors(constructors_list):
    """this function process constructors.
    The constructors_list is a list of constructors
    """
    # first, assume that all methods are constructors
    for c in constructors_list:
        if not c["constructor"]:
            raise AssertionError("This method is not a constructor")
    # then we count the number of available constructors
    number_of_constructors = len(constructors_list)
    # if there are more than one constructor, then the __init__ method
    # has to be tagged as overloaded using the @overload decorator
    need_overload = False
    if number_of_constructors > 1:
        need_overload = True
        logger.info(
            "    [TypeHint] More than 1 constructor, @overload decorator needed."
        )
    # then process the constructors
    str_functions = ""
    type_hints = ""
    for constructor in constructors_list:
        ok_to_wrap, ok_hints = process_function(constructor, need_overload)
        if ok_to_wrap:
            str_functions += ok_to_wrap
            type_hints += ok_hints
    return str_functions, type_hints


_HANDLE_OUTPUT_TYPE_RE = re.compile(
    r"^\s*(?:opencascade|occ)::handle\s*<\s*(\w+)\s*>\s*&\s*$"
)


def is_subclass(class_name, ancestor_name):
    """True if class_name derives from ancestor_name, according to the
    classes processed so far (state.class_parents)."""
    seen = set()
    parent = state.class_parents.get(class_name)
    while parent is not None and parent not in seen:
        if parent == ancestor_name:
            return True
        seen.add(parent)
        parent = state.class_parents.get(parent)
    return False


def _overrides_handle_outputs(f, g):
    """True if the parameters of f and g are the same, but for non-const
    handle outputs whose types in f derive from the ones in g, e.g.
    TDocStd_Application::NewDocument(format, handle<TDocStd_Document>&) and
    NewDocument(format, handle<CDM_Document>&)."""
    if len(f["parameters"]) != len(g["parameters"]):
        return False
    derived = False
    for param_f, param_g in zip(f["parameters"], g["parameters"], strict=True):
        type_f, type_g = param_f["type"].strip(), param_g["type"].strip()
        if type_f == type_g:
            continue
        handle_f = _HANDLE_OUTPUT_TYPE_RE.match(type_f)
        handle_g = _HANDLE_OUTPUT_TYPE_RE.match(type_g)
        if not (
            handle_f and handle_g and is_subclass(handle_f.group(1), handle_g.group(1))
        ):
            return False
        derived = True
    return derived


def derived_handle_outputs_first(methods_list):
    """Order the overloads so that the one whose handle outputs are the most
    derived comes first. SWIG tries the overloads in their declaration order
    and the typecheck of a handle output accepts None and any subclass: the
    base class overload would always be chosen, and return the base class."""
    result = list(methods_list)
    moved = True
    while moved:
        moved = False
        for i, f in enumerate(result):
            for j in range(i):
                g = result[j]
                if g["name"] == f["name"] and _overrides_handle_outputs(f, g):
                    result.insert(j, result.pop(i))
                    moved = True
                    break
            if moved:
                break
    return result


def process_methods(methods_list):
    """process a list of public process_methods"""
    str_functions = ""
    type_hints = ""
    # sort methods according to the method name
    sorted_methods_list = derived_handle_outputs_first(
        sorted(methods_list, key=itemgetter("name"))
    )
    keep_owner_names = _names_returning_owned_references(sorted_methods_list)
    # create a dict to map function names and the number of occurrences,
    # to determine whether or not use the @overload decorator
    for function in sorted_methods_list:
        # Skip free functions that live in a namespace different from
        # state.current_module: SWIG would emit them at file scope but the underlying
        # C symbol lives in the namespace, so the call would fail to link
        # (occt-800: e.g. BVH::EncodeMortonCode in BVH_RadixSorter.hxx).
        # When the namespace matches state.current_module, the .i file emits
        # `using namespace X;` so the unqualified call is fine
        # (e.g. namespace TopoDS::Wire/Edge/Face etc).
        if not function.get("parent"):
            ns = function.get("namespace", "").rstrip(":")
            if ns and ns != state.current_module:
                continue
        # don't process friend methods
        need_overload = False
        if not function["friend"]:
            # check if this method is many times in the function list
            names_count = 0
            function_name = function["name"]
            for f in sorted_methods_list:
                if f["name"] == function_name:
                    names_count += 1
            if names_count > 1:
                need_overload = True
            ok_to_wrap, ok_hints = process_function(function, need_overload)
            if ok_to_wrap:
                if function_name in keep_owner_names:
                    keep_owner_names.remove(function_name)
                    str_functions += TEMPLATE_KEEP_OWNER.substitute(
                        {"MethodName": adapt_function_name(function_name)}
                    )
                str_functions += ok_to_wrap
                type_hints += ok_hints
    return str_functions, type_hints


# the referenced types SWIG does not wrap as a proxy pointing into the owner:
# numbers and strings (FunctionTransformers.i), handles (OccHandle.i), streams.
# The type is matched once the qualifiers, '&', '*' and '::' are removed.
_NOT_OWNED_REFERENCE_TYPES_RE = re.compile(
    r"^(?:Standard_(?:Integer|Real|Boolean|ShortReal|Size|Character|Byte"
    r"|ExtCharacter|Utf8Char|CString|ExtString|Address|OStream|IStream|SStream)"
    r"|(?:unsigned )?(?:int|long|short|char)|double|float|bool|size_t|void"
    r"|std \w+|(?:opencascade |occ )?handle ?<.*>|Handle_\w+)$"
)


def _returns_owned_reference(f):
    """True if the method returns a reference to an object stored in the
    instance, e.g. NCollection_HArray1::Array1() or Geom_BSplineCurve::Poles().
    SWIG wraps it as a proxy that does not own the referenced object, which is
    freed with the instance (issue #1499)."""
    if f["constructor"] or f["static"] or f["friend"] or f["parent"] is None:
        return False
    if not adapt_function_name(f["name"]).isidentifier():  # operators
        return False
    rtn_type = _apply_typedef_rewrites(f["rtnType"])
    if "*" not in rtn_type and (
        "&" not in rtn_type
        or _is_returned_as_copy(rtn_type)
        or _is_reference_returned_by_value(rtn_type)
        or is_return_type_enum(rtn_type)
    ):
        return False
    referenced_type = re.sub(
        r"\b(?:const|virtual|inline|static|public|protected|private"
        r"|Standard_EXPORT|DEFINE_NCOLLECTION_ALLOC)\b|[&*:]",
        " ",
        rtn_type,
    )
    referenced_type = " ".join(referenced_type.split())
    return not _NOT_OWNED_REFERENCE_TYPES_RE.match(referenced_type)


def _names_returning_owned_references(methods_list):
    """Names of the methods whose returned reference must keep the instance
    alive. The SWIG feature applies to all the overloads of a name: a name
    with a static overload is left out, the python wrapper has no self."""
    names = {f["name"] for f in methods_list if _returns_owned_reference(f)}
    return names - {f["name"] for f in methods_list if f["static"]}


def must_ignore_default_destructor(klass):
    """Some classes, like for instance BRepFeat_MakeCylindricalHole
    has a protected destructor that must explicitly be ignored
    This is done by the directive
    %ignore Class::~Class() just before the wrapper definition
    """
    class_protected_methods = klass["methods"]["protected"]
    for protected_method in class_protected_methods:
        if protected_method["destructor"]:
            return True
    class_private_methods = klass["methods"]["private"]
    # finally, return True, the default constructor can be safely defined
    return any(private_method["destructor"] for private_method in class_private_methods)


def has_public_default_constructor(klass):
    """True if the class declares a public constructor callable without
    arguments, e.g. `X();` or `X(int theArg = 0);`."""
    for method in klass["methods"]["public"]:
        if (
            method["constructor"]
            and method["name"] == klass["name"]
            and not method.get("deleted")
            and all("defaultValue" in p for p in method["parameters"])
        ):
            return True
    return False


def class_can_have_default_constructor(klass):
    """Check if the class can have a defaultctor wrap
    or, if not, return False if the %nodefaultctor is required
    """
    if klass["name"] in NODEFAULTCTOR:
        return False
    # class must not be an abstract class
    if klass["abstract"]:
        logger.info("    Class %s is abstract, using %%nodefaultctor.", klass["name"])
        return False
    # check if the class has at least one public constructor defined
    has_one_public_constructor = False
    class_public_methods = klass["methods"]["public"]
    for public_method in class_public_methods:
        if public_method["constructor"] and public_method["name"] == klass["name"]:
            if public_method.get("deleted") and not public_method["parameters"]:
                # occt-800: `X() = delete;`
                logger.info(
                    "    Class %s has a deleted default constructor.", klass["name"]
                )
                return False
            if not public_method.get("deleted"):
                has_one_public_constructor = True
    # we have to ensure that no private or protected constructor is defined
    # we look for protected () constructor
    has_one_protected_constructor = False
    class_protected_methods = klass["methods"]["protected"]
    for protected_method in class_protected_methods:
        if (
            protected_method["constructor"]
            and protected_method["name"] == klass["name"]
        ):
            has_one_protected_constructor = True
    # check for private constructor
    has_one_private_constructor = False
    class_private_methods = klass["methods"]["private"]
    for private_method in class_private_methods:
        if private_method["constructor"] and private_method["name"] == klass["name"]:
            has_one_private_constructor = True
    # no default constructor if all the constructors are private or protected,
    # otherwise no need to use the %nodefaultctor
    return has_one_public_constructor or not (
        has_one_private_constructor or has_one_protected_constructor
    )


def build_inheritance_tree(classes_dict):
    """From the classes dict, return a list of classes
    with the class ordered from the most abstract to
    the more specialized. The more abstract will be
    processed first.
    """
    # first, we build two dictionaries
    # the first one, level_0_classes
    # contain class names that does not inherit from
    # any other class
    # they will be processed first
    level_0_classes = []
    # the inheritance dict contains the relationships
    # betwwen a class and its upper class.
    # the dict schema is as the following :
    # inheritance_dict = {'base_class_name': 'upper_class_name'}
    inheritance_dict = {}
    for klass in classes_dict.values():
        class_name = klass["name"]
        upper_classes = klass["inherits"]
        nbr_upper_classes = len(upper_classes)
        if nbr_upper_classes > 0:
            state.class_parents[class_name] = upper_classes[0]["class"]
        if nbr_upper_classes == 0:
            level_0_classes.append(class_name)
        # if class has one or more ancestors
        # for class with one or two ancestors, let's process them
        # the same. Anyway, if there are two ancestors (only a few cases),
        # one of the two ancestors come from another module.
        elif nbr_upper_classes == 1:
            upper_class_name = upper_classes[0]["class"]
            # if the upper class depends on another module
            # add it to the level 0 list.
            if upper_class_name.split("_")[0] != state.current_module:
                level_0_classes.append(class_name)
            # else build the inheritance tree
            else:
                inheritance_dict[class_name] = upper_class_name
        elif nbr_upper_classes == 2:
            # if one, or the other
            upper_class_name_1 = upper_classes[0]["class"]
            class_1_module = upper_class_name_1.split("_")[0]
            upper_class_name_2 = upper_classes[1]["class"]
            class_2_module = upper_class_name_2.split("_")[0]
            if class_1_module == upper_class_name_2 == state.current_module:
                logger.warning(
                    "This is a special case, where the 2 ancestors belong the same module. Class %s skipped.",
                    class_name,
                )
            if class_1_module == state.current_module:
                inheritance_dict[class_name] = upper_class_name_1
            elif class_2_module == state.current_module:
                inheritance_dict[class_name] = upper_class_name_2
            elif (
                upper_class_name_1 == upper_class_name_2
            ):  # the samemodule, but external, not the current one
                level_0_classes.append(class_name)
            inheritance_dict[class_name] = upper_class_name_1
        else:
            # prevent multiple inheritance: OCCT only has single
            # inheritance
            logger.warning(
                "Class %s has %s ancestors and is skipped.",
                class_name,
                nbr_upper_classes,
            )

    # then, after that, we process both dictionaries, list so
    # that we reorder class.
    # first, we build something called the inheritance_depth.
    # that is to say a dict with the class name and the number of upper classes
    # inheritance_depth = {'Standard_Transient':0, 'TopoDS_Shape':1}
    inheritance_depth = {}
    # first we fill in with level_0:
    for class_name in level_0_classes:
        inheritance_depth[class_name] = 0
    upper_classes = inheritance_dict.values()
    for base_class_name in inheritance_dict:
        tmp = base_class_name
        i = 0
        while tmp in inheritance_dict:
            tmp = inheritance_dict[tmp]
            i += 1
        inheritance_depth[base_class_name] = i
    # after that, we traverse the inheritance depth dict
    # to order classes names according to their depth.
    # first classes with level 0, then 1, 2 etc.
    # at last, we return the class_list containing a list
    # of ordered classes.
    class_list = []
    for class_name, _ in sorted(
        inheritance_depth.items(), key=lambda kv: (kv[1], kv[0])
    ):
        if class_name in classes_dict:  # TODO: should always be the case!
            class_list.append(classes_dict[class_name])
    # Then we build the list of all classes that inherit from Standard_Transient
    # at some point. These classes will need the %wrap_handle and %make_alias_macros
    for klass in class_list:
        upper_class = klass["inherits"]
        class_name = klass["name"]
        # a class that inherits from a Standard_Transient base class is added
        # to the state.all_standard_transients list
        if (
            upper_class
            and upper_class[0]["class"] in state.all_standard_transients
            and class_name not in state.all_standard_transients
        ):
            state.all_standard_transients.append(class_name)
    return class_list


def fix_type(type_str):
    """used in docstrings"""
    type_str = type_str.replace("Standard_Boolean &", "bool")
    type_str = type_str.replace("Standard_Boolean", "bool")
    type_str = type_str.replace("Standard_Real", "float")
    type_str = type_str.replace("Standard_ShortReal", "float")
    type_str = type_str.replace("Standard_Integer", "int")
    type_str = type_str.replace("Standard_CString", "str")
    type_str = type_str.replace("std::istream &", "str")
    type_str = type_str.replace("const", "")
    return type_str.replace("& &", "&")


def _container_pyi_mapping(h_class_name, type_key, cpp_type):
    """Substitution mapping for the HArray1/HArray2/HSequence stub templates.
    The C++ container type (e.g. NCollection_Array1<gp_Pnt>) is not valid
    python: replace it with its typedef name (TColgp_Array1OfPnt). If there is
    none, fall back to Any and inherit only from Standard_Transient.
    """
    normalized = re.sub(r"\s+", "", cpp_type)
    py_type = state.template_typedef_names.get(
        normalized, _apply_typedef_rewrites(normalized)
    )
    if py_type.isidentifier():
        bases = f"{py_type}, Standard_Transient"
    else:
        py_type = "Any"
        bases = "Standard_Transient"
    return {"HClassName": h_class_name, type_key: py_type, "Bases": bases}


def _container_item_type_hint(cpp_type):
    """The type hint of the items of a container type, e.g. float for
    NCollection_Array1<double>"""
    item_type = cpp_type.strip().split("<", 1)[1].rsplit(">", 1)[0].strip()
    return adapt_type_for_hint(item_type) or "Any"


def process_harray1():
    """special wrapper for NCollection_HArray1
    Returns both the definition and the hint
    """
    wrapper_str = "/* harray1 classes */\n"
    pyi_str = "\n# harray1 classes\n"
    for h_class_name, array1_type in state.all_harray1.items():
        if h_class_name.startswith(state.current_module + "_"):
            wrapper_str += HARRAY1_TEMPLATE.substitute(
                {"HClassName": f"{h_class_name}", "Array1Type": f"{array1_type}"}
            )
            # type hint
            mapping = _container_pyi_mapping(h_class_name, "Array1Type", array1_type)
            mapping["ItemType"] = _container_item_type_hint(array1_type)
            pyi_str += HARRAY1_TEMPLATE_PYI.substitute(mapping)
    return wrapper_str, pyi_str


def process_harray2():
    wrapper_str = "/* harray2 classes */"
    pyi_str = "# harray2 classes\n"
    for h_class_name, array2_type in state.all_harray2.items():
        if h_class_name.startswith(state.current_module + "_"):
            wrapper_str += HARRAY2_TEMPLATE.substitute(
                {"HClassName": f"{h_class_name}", "Array2Type": f"{array2_type}"}
            )
            # type hint
            mapping = _container_pyi_mapping(h_class_name, "Array2Type", array2_type)
            mapping["ItemType"] = _container_item_type_hint(array2_type)
            pyi_str += HARRAY2_TEMPLATE_PYI.substitute(mapping)
    wrapper_str += "\n"
    return wrapper_str, pyi_str


def process_hsequence():
    wrapper_str = "/* hsequence classes */"
    pyi_str = "# hsequence classes\n"
    for h_class_name, sequence_type in state.all_hsequence.items():
        if h_class_name.startswith(state.current_module + "_"):
            wrapper_str += HSEQUENCE_TEMPLATE.substitute(
                {"HClassName": f"{h_class_name}", "SequenceType": f"{sequence_type}"}
            )
            # type hint: Append(theItem) overloads the inherited
            # Sequence.Append(theItem), it must be declared along with
            # Append(theSequence) or mypy only sees the latter
            mapping = _container_pyi_mapping(
                h_class_name, "SequenceType", sequence_type
            )
            mapping["ItemType"] = _container_item_type_hint(sequence_type)
            pyi_str += HSEQUENCE_TEMPLATE_PYI.substitute(mapping)
    wrapper_str += "\n"
    pyi_str += "\n"
    return wrapper_str, pyi_str


def resolve_exclude_classes(classes_dict, exclude_classes):
    """exclude_classes: ["*"] excludes all the classes of the module, but the
    ones of the include_classes option of the module."""
    if exclude_classes != ["*"]:
        return exclude_classes
    all_classes = []
    for klass in classes_dict:
        class_name = klass.split("::")[0].split("<")[0]
        if class_name not in all_classes:
            all_classes.append(class_name)
    return [c for c in all_classes if c not in state.include_classes]


def process_handles(classes_dict, exclude_classes):
    """Check whether a class has to be wrapped as a handle
    using the wrap_handle swig macro.
    This code is a bit redundant with process_classes, but this step
    appeared to be placed before typedef and templates definition
    """
    wrap_handle_str = "/* handles */\n"
    if exclude_classes == ["*"] and not state.include_classes:
        return ""  # don't wrap any class
    exclude_classes = resolve_exclude_classes(classes_dict, exclude_classes)
    inheritance_tree_list = build_inheritance_tree(classes_dict)
    # occt-800: propagate "needs handle" through the inheritance chain. Many
    # 8.0 classes (e.g. XCAFDoc_ShapeTool) have no DEFINE_STANDARD_RTTI* of
    # their own but inherit from a Standard_Transient subclass via several
    # levels - their handle is still required for the typemaps.
    inherited_handle_classes = set()
    for klass in inheritance_tree_list:
        cn = klass["name"]
        for base in klass.get("inherits", []):
            base_name = base.get("class") if isinstance(base, dict) else base
            if base_name and (
                base_name in state.all_standard_handles
                or base_name in state.all_standard_transients
                or base_name in inherited_handle_classes
            ):
                inherited_handle_classes.add(cn)
                if cn not in state.all_standard_handles:
                    state.all_standard_handles.append(cn)
                break
    for klass in inheritance_tree_list:
        # class name
        class_name = klass["name"]
        if class_name in exclude_classes:
            # if the class has to be excluded,
            # we go on with the next one to be processed
            continue
        if check_has_related_handle(class_name) or class_name == "Standard_Transient":
            wrap_handle_str += f"%wrap_handle({class_name})\n"
    for h_class_name in state.all_harray1:
        if h_class_name.startswith(state.current_module + "_"):
            wrap_handle_str += f"%wrap_handle({h_class_name})\n"
    for h_class_name in state.all_harray2:
        if h_class_name.startswith(state.current_module + "_"):
            wrap_handle_str += f"%wrap_handle({h_class_name})\n"
    for h_class_name in state.all_hsequence:
        if h_class_name.startswith(state.current_module + "_"):
            wrap_handle_str += f"%wrap_handle({h_class_name})\n"
    wrap_handle_str += "/* end handles declaration */\n\n"
    return wrap_handle_str


_PRIMITIVE_REF_TO_CTYPE = {
    "Standard_Real": "double",
    "double": "double",
    "Standard_Integer": "int",
    "int": "int",
    "Standard_Boolean": "bool",
    "bool": "bool",
}


_PRIMITIVE_CTYPE_TO_HINT = {"double": "float", "int": "int", "bool": "bool"}
_PRIMITIVE_BY_REF_RETURNS_NO_SPACE = {
    t.replace(" ", "") for t in _PRIMITIVE_BY_REF_RETURNS
}


def _synthesize_primitive_ref_getter_setters(class_name, other_methods):
    """occt-800: synthesize SetXxx/GetXxx pairs for parameterless methods that
    return a reference to a primitive (Standard_Real&, Standard_Integer&,
    Standard_Boolean&). OCCT 8.0 dropped the explicit setters, exposing only
    a `Type& Foo()` accessor that Python cannot assign through. Restores the
    API pythonocc has exposed since 2014 (commit 78c320c3).
    Returns (swig_str, type_hint_str)."""
    out = ""
    pyi = ""
    for m in other_methods:
        rtype = (m.get("rtnType") or "").strip()
        if "&" not in rtype or m.get("parameters"):
            continue
        if rtype.startswith("const") or " const " in rtype:
            continue
        base = rtype.replace("&", "").strip()
        cpp_type = _PRIMITIVE_REF_TO_CTYPE.get(base)
        if cpp_type is None:
            continue
        mname = m["name"]
        if mname == class_name or mname.startswith("~"):
            continue
        out += "\t\t%extend{\n"
        out += f"\t\t\t{cpp_type} Get{mname}() {{ return self->{mname}(); }}\n"
        out += (
            f"\t\t\tvoid Set{mname}({cpp_type} value) {{ self->{mname}() = value; }}\n"
        )
        out += "\t\t};\n"
        if rtype.replace(" ", "") not in _PRIMITIVE_BY_REF_RETURNS_NO_SPACE:
            # else process_function already wrote these hints
            hint = _PRIMITIVE_CTYPE_TO_HINT[cpp_type]
            pyi += f"    def Get{mname}(self) -> {hint}: ...\n"
            pyi += f"    def Set{mname}(self, value: {hint}) -> None: ...\n"
    return out, pyi


def _class_specific_extensions(class_name):
    """Return (extra_def_str, extra_pyi_str) for classes that need ad-hoc SWIG
    extensions (TDF_Label name accessor, BRepTools serialization, math_*
    setters, TopoDS_Shape pickling, ...)."""
    extra_def, extra_pyi = "", ""
    # the numpy members added after the class, see process_classes
    if class_name in ("Geom_Curve", "Geom2d_Curve"):
        extra_pyi += CURVE_ARRAY_EVAL_PYI
    if class_name == "Geom_Surface":
        extra_pyi += SURFACE_ARRAY_EVAL_PYI
    if class_name in ("BRepTools", "BRepTools_ShapeSet"):
        extra_def += BREPTOOLS_WRITE_READ_FROM_STRING
        extra_pyi += BREPTOOLS_WRITE_READ_FROM_STRING_PYI
    if class_name == "TCollection_ExtendedString":
        # str() returns the text, decoded from UTF-8
        extra_def += "\t\t%extend{\n"
        extra_def += "\t\t\tstd::string __str__() {\n"
        extra_def += "\t\t\tstd::string txt(self->LengthOfCString(), '\\0');\n"
        extra_def += "\t\t\tchar* str = &txt[0];\n"
        extra_def += "\t\t\tself->ToUTF8CString(str);\n"
        extra_def += "\t\t\treturn txt;}\n"
        extra_def += "\t\t};\n"
        extra_pyi += "    def __str__(self) -> str: ...\n"
    if class_name == "TCollection_AsciiString":
        extra_def += "\t\t%extend{\n"
        extra_def += "\t\t\tstd::string __str__() {\n"
        extra_def += "\t\t\treturn std::string(self->ToCString(), self->Length());}\n"
        extra_def += "\t\t};\n"
        extra_pyi += "    def __str__(self) -> str: ...\n"
    if class_name == "TDF_Label":
        extra_def += '%feature("autodoc", "Returns the label name") GetLabelName;\n'
        extra_def += "\t\t%extend{\n"
        extra_def += "\t\t\tstd::string GetLabelName() {\n"
        extra_def += "\t\t\tstd::string txt;\n"
        extra_def += "\t\t\tHandle(TDataStd_Name) name;\n"
        extra_def += "\t\t\tif (!self->IsNull() && self->FindAttribute(TDataStd_Name::GetID(),name)) {\n"
        extra_def += "\t\t\tTCollection_ExtendedString extstr = name->Get();\n"
        extra_def += "\t\t\tchar* str = new char[extstr.LengthOfCString()+1];\n"
        extra_def += "\t\t\textstr.ToUTF8CString(str);\n"
        extra_def += "\t\t\ttxt = str;\n"
        extra_def += "\t\t\tdelete[] str;}\n"
        extra_def += "\t\t\treturn txt;}\n"
        extra_def += "\t\t};\n"
        extra_pyi += "    def GetLabelName(self) -> str: ...\n"
    # occt-800: StlAPI_Writer dropped SetASCIIMode and exposes the flag
    # through `bool& ASCIIMode()`. Add a Python-friendly setter shim.
    if class_name == "StlAPI_Writer":
        extra_def += "\t\t%extend{\n"
        extra_def += (
            "\t\t\tvoid SetASCIIMode(bool theMode) { self->ASCIIMode() = theMode; }\n"
        )
        extra_def += "\t\t};\n"
        # its stub is written with GetASCIIMode, see
        # _synthesize_primitive_ref_getter_setters
    # occt-800: math_Matrix still exposes mutable Value() returning a reference
    # but Python cannot assign through it - add Get/SetValue shims (math_Vector:
    # see MATH_VECTORBASE_EXTEND).
    if class_name == "math_Matrix":
        extra_def += "\t\t%extend{\n"
        extra_def += "\t\t\tdouble GetValue(int row, int col) const { return self->Value(row, col); }\n"
        extra_def += "\t\t\tvoid SetValue(int row, int col, double v) { self->Value(row, col) = v; }\n"
        extra_def += "\t\t};\n"
        extra_pyi += "    def GetValue(self, row: int, col: int) -> float: ...\n"
        extra_pyi += (
            "    def SetValue(self, row: int, col: int, v: float) -> None: ...\n"
        )
    return extra_def, extra_pyi


def _render_excluded_classes_proxies(exclude_classes):
    """Emit Python placeholders that raise ClassNotWrapped at use time, plus
    matching .pyi entries. Skips classes that NCollection.i actually wraps,
    since the placeholder would shadow them."""
    if not exclude_classes:
        return "", ""
    def_str = "/* python proxy for excluded classes */\n%pythoncode {\n"
    pyi_str = ""
    for excluded_class in exclude_classes:
        if excluded_class in NCOLLECTION_WRAPPED_CLASSES:
            continue
        def_str += f"@classnotwrapped\nclass {excluded_class}:\n\tpass\n\n"
        pyi_str += f"\n#classnotwrapped\nclass {excluded_class}: ...\n"
    def_str += "}\n/* end python proxy for excluded classes */\n"
    return def_str, pyi_str


def _split_template_args(args_str):
    """Splits 'A, B<C, D>, E' on the top level commas."""
    args, depth, current = [], 0, ""
    for char in args_str:
        if char == "," and depth == 0:
            args.append(current.strip())
            current = ""
            continue
        depth += char == "<"
        depth -= char == ">"
        current += char
    args.append(current.strip())
    return args


def _rewrite_nested_names(type_str, scope, classes_dict, nested_map):
    """Rewrites the nested class and enum names of type_str, as seen from
    the class named scope (qualified C++ name), to their flat names.

    'BRepGraph::ShapesView::Result' -> 'BRepGraph_ShapesView_Result',
    'Result' (from BRepGraph::ShapesView) -> 'BRepGraph_ShapesView_Result',
    'Kind' (from BRepGraph_NodeId::Typed) -> 'BRepGraph_NodeId::Kind'."""
    for qualified, flat in sorted(nested_map.items(), key=lambda item: -len(item[0])):
        type_str = re.sub(rf"(?<![\w:]){re.escape(qualified)}\b", flat, type_str)
    scopes = [scope]
    while "::" in scopes[-1]:
        scopes.append(scopes[-1].rsplit("::", 1)[0])
    for current_scope in scopes:
        for qualified, flat in nested_map.items():
            if qualified.rsplit("::", 1)[0] == current_scope:
                short = qualified.rsplit("::", 1)[1]
                type_str = re.sub(rf"(?<![\w:]){short}\b", flat, type_str)
        if current_scope != scope and current_scope in classes_dict:
            # enums and typedefs of an enclosing class are qualified
            owner = nested_map.get(current_scope, current_scope)
            names = [
                enum["name"]
                for enum in classes_dict[current_scope]["enums"]["public"]
                if enum.get("name")
            ]
            names.extend(classes_dict[current_scope]["typedefs"]["public"])
            for name in names:
                type_str = re.sub(rf"(?<![\w:]){name}\b", f"{owner}::{name}", type_str)
    return type_str


def _rewrite_class_types(klass, scope, classes_dict, nested_map):
    """Applies _rewrite_nested_names to every type of a class dict."""
    for prop in klass["properties"]["public"]:
        prop["type"] = _rewrite_nested_names(
            prop["type"], scope, classes_dict, nested_map
        )
    for inherit in klass["inherits"]:
        inherit["class"] = _rewrite_nested_names(
            inherit["class"], scope, classes_dict, nested_map
        )
    for access in ("public", "protected", "private"):
        for method in klass["methods"][access]:
            rtn_type = method["rtnType"]
            # CppHeaderParser drops the const, & and * of a return type when
            # it qualifies a nested type name, they are reported as flags
            if method.get("returns_reference") and "&" not in rtn_type:
                rtn_type += " &"
            if method.get("returns_pointer") and "*" not in rtn_type:
                rtn_type += " *"
            if method.get("returns_const") and not rtn_type.startswith("const"):
                rtn_type = f"const {rtn_type}"
            method["rtnType"] = _rewrite_nested_names(
                rtn_type, scope, classes_dict, nested_map
            )
            for param in method["parameters"]:
                for key in ("type", "raw_type"):
                    if param.get(key):
                        param[key] = _rewrite_nested_names(
                            param[key], scope, classes_dict, nested_map
                        )


def _instantiate_nested_template(alias, outer, template_name, args_str, classes_dict):
    """Returns the class dict of the instantiation `alias` of the class
    template Outer::Tpl<Args>, None when it cannot be instantiated.

    The template parameters must be non-type parameters (e.g. an enum
    value): the parameter names are replaced by the arguments in every
    method, as the compiler would do; the template name by the alias."""
    template = classes_dict.get(f"{outer}::{template_name}")
    if template is None:
        return None
    params = re.fullmatch(r"template\s*<(.*)>", template.get("template", "").strip())
    if params is None:
        return None
    param_names = []
    for param in _split_template_args(params.group(1)):
        words = param.replace("=", " ").split()
        if not words or words[0] in ("typename", "class"):
            return None  # a type parameter, its uses cannot be rewritten
        param_names.append(words[1] if len(words) > 1 else words[0])
    args = _split_template_args(args_str)
    if len(args) != len(param_names):
        return None

    def substitute(text):
        for name, arg in zip(param_names, args, strict=True):
            text = re.sub(rf"\b{name}\b", arg, text)
        text = re.sub(rf"\b{outer}::{template_name}\b", alias, text)
        return re.sub(rf"(?<![\w:]){template_name}\b", alias, text)

    # a shallow copy of the CppHeaderParser class keeps its attributes, the
    # methods and parameters are copied before being rewritten
    klass = copy.copy(template)
    klass["name"] = alias
    klass["template"] = ""
    klass["parent"] = None
    klass["nested_classes"] = []
    klass["methods"] = {
        access: [dict(method) for method in template["methods"][access]]
        for access in ("public", "protected", "private")
    }
    for access in ("public", "protected", "private"):
        methods = []
        for method in klass["methods"][access]:
            if method.get("template"):
                continue  # method templates cannot be instantiated here
            method["parameters"] = [dict(param) for param in method["parameters"]]
            method["name"] = substitute(method["name"])
            method["rtnType"] = substitute(method["rtnType"])
            for param in method["parameters"]:
                for key in ("type", "raw_type"):
                    if param.get(key):
                        param[key] = substitute(param[key])
            method["parent"] = klass
            methods.append(method)
        klass["methods"][access] = methods
    return klass


_ACCESS_RE = re.compile(r"^\s*(public|protected|private)\s*:")


def _nested_class_access(klass, parent):
    """Returns the access ('public', 'protected' or 'private') of a nested
    class, from the last access specifier written between the declaration
    of the parent class and the nested class in the header. CppHeaderParser
    does not record it."""
    header = klass.get("_header")
    if header is None or "line_number" not in klass or "line_number" not in parent:
        return "public"
    if header != parent.get("_header"):
        # defined out of line, in its own header: forward declared in the
        # public section of its parent
        return "public"
    with Path(header).open(encoding="utf8", errors="replace") as f:
        lines = f.readlines()
    access = "public" if parent.get("declaration_method") == "struct" else "private"
    depth = 0
    for line in lines[parent["line_number"] - 1 : klass["line_number"] - 1]:
        # only the access specifiers of the parent body itself, not those
        # of the nested classes declared before
        if depth == 1:
            match = _ACCESS_RE.match(line)
            if match:
                access = match.group(1)
        depth += line.count("{") - line.count("}")
    return access


def flatten_nested_classes(classes_dict):
    """occt-800: wraps the nested classes of a module as top level classes.

    SWIG does not support nested classes defined out of line
    (`class BRepGraph::ShapesView { ... };`). Each nested class Outer::Inner
    is wrapped as a top level class Outer_Inner, a `typedef Outer::Inner
    Outer_Inner;` written in the C++ section of the .i file makes the
    generated code compile. The nested names are rewritten in every
    signature. Aliases of nested class templates (`using BRepGraph_FaceId =
    BRepGraph_NodeId::Typed<...>;`) are instantiated as classes too."""
    # the instantiations of the nested class templates
    for alias, (
        outer,
        template_name,
        args_str,
    ) in state.nested_template_aliases.items():
        klass = _instantiate_nested_template(
            alias, outer, template_name, args_str, classes_dict
        )
        if klass is None:
            logger.info("    nested template alias %s not instantiated", alias)
            continue
        klass["_scope"] = f"{outer}::{template_name}"
        classes_dict[alias] = klass
        logger.info("    nested template alias %s instantiated", alias)
    # the flat names, of the public nested classes
    nested_map = {}
    for name, klass in classes_dict.items():
        if "::" in name and not name.startswith("std::"):
            parent = classes_dict.get(name.rsplit("::", 1)[0])
            if parent is not None and _nested_class_access(klass, parent) != "public":
                klass["_skip"] = True
                logger.info("    nested class %s is not public, skipped", name)
                continue
            nested_map[name] = name.replace("::", "_")
    for name, klass in classes_dict.items():
        scope = klass.get("_scope", name)
        _rewrite_class_types(klass, scope, classes_dict, nested_map)
        if name in nested_map:
            klass["name"] = nested_map[name]
            klass["_qualified"] = name
            if not klass.get("template"):
                state.flattened_classes.append((name, nested_map[name]))
        short_name = name.rsplit("::", 1)[-1]
        for access in ("public", "protected", "private"):
            for method in klass["methods"][access]:
                # constructors and destructors carry the short name, and an
                # explicit constructor is not flagged as such by CppHeaderParser
                if method["name"] == short_name:
                    method["name"] = klass["name"]
                    method["constructor"] = True
                elif method["name"] == f"~{short_name}":
                    method["name"] = f"~{klass['name']}"
                    method["destructor"] = True
    # the classes are looked up by name
    for qualified, flat in nested_map.items():
        classes_dict[flat] = classes_dict.pop(qualified)


_PRIMITIVE_PROPERTY_TYPES = {
    "bool",
    "int",
    "double",
    "float",
    "size_t",
    "uint32_t",
    "int32_t",
    "uint64_t",
    "int64_t",
    "uint8_t",
    "unsigned int",
    "long",
    "unsigned long",
    "char",
    "Standard_Integer",
    "Standard_Real",
    "Standard_Boolean",
    "Standard_ShortReal",
}


# the string classes converted from and to python str by the typemaps
_STRING_FIELD_TYPES = ("TCollection_AsciiString", "TCollection_ExtendedString")


def _is_foreign_enum(type_str):
    """True for an enum of a module not imported, e.g. STEPControl_StepModelType
    in DESTEP: OCCT declares each enum in a header of its own name."""
    module = type_str.split("_")[0]
    if (
        module == state.current_module
        or module in state.python_module_dependency
        or not is_module(module)
    ):
        return False
    header = OCCT_INCLUDE_DIR / f"{type_str}.hxx"
    return (
        header.is_file()
        and re.search(
            rf"\benum\s+{re.escape(type_str)}\b", header.read_text(errors="replace")
        )
        is not None
    )


def _is_wrappable_property_type(type_str, klass):
    """A public field is wrapped when its type is a primitive, an enum or a
    typedef of the class itself or qualified by a wrapped class of the
    module, or a class of a wrapped module. Pointers, templates and
    unresolved names are not."""
    type_str = type_str.replace("const", "").strip()
    if type_str in _PRIMITIVE_PROPERTY_TYPES:
        return True
    own_names = {enum.get("name") for enum in klass["enums"]["public"]}
    own_names.update(klass["typedefs"]["public"])
    if type_str in own_names:
        return True
    if any(token in type_str for token in ("<", "*", "&", "std::", " ")):
        return False
    if "::" in type_str:
        return type_str.split("::")[0].split("_")[0] == state.current_module
    return "_" in type_str and is_module(type_str.split("_")[0])


def _is_nested_base_of_module(base_class):
    """True for a base class nested in a class of the current module, e.g.
    BRepGraph_ReverseIterator::EdgeParentsOf<...>, which is not wrapped."""
    return (
        "::" in base_class
        and base_class.split("::")[0].split("_")[0] == state.current_module
    )


def _propagate_abstract_classes(classes_dict):
    """Flags as abstract the classes that inherit pure virtual methods of a
    base class of the module without overriding them. CppHeaderParser only
    flags a class declaring pure virtual methods itself."""
    by_name = {klass["name"]: klass for klass in classes_dict.values()}
    memo = {}

    def unimplemented(klass):
        """The pure virtual methods klass does not implement."""
        if klass["name"] in memo:
            return memo[klass["name"]]
        memo[klass["name"]] = set()  # guards against inheritance cycles
        pure, implemented = set(), set()
        for access in ("public", "protected", "private"):
            for method in klass["methods"][access]:
                if method.get("pure_virtual"):
                    pure.add(method["name"])
                else:
                    implemented.add(method["name"])
        for inherit in klass["inherits"]:
            base = by_name.get(inherit["class"])
            if base is not None:
                pure |= unimplemented(base)
        memo[klass["name"]] = pure - implemented
        return memo[klass["name"]]

    for klass in classes_dict.values():
        if klass.get("abstract") or not klass["inherits"]:
            continue
        missing = unimplemented(klass)
        if missing:
            logger.info(
                "    %s is abstract, it does not override %s",
                klass["name"],
                sorted(missing),
            )
            klass["abstract"] = True


def process_classes(classes_dict, exclude_classes, exclude_member_functions):
    """Generate the SWIG string for the class wrapper.
    Works from a dictionary of all classes, generated with CppHeaderParser.
    All classes but the ones in exclude_classes are wrapped.
    excludes_classes is a list with the class names to exclude_classes
    exclude_member_functions is a dict with classes names as keys and member
    function names as values
    """
    exclude_classes = resolve_exclude_classes(classes_dict, exclude_classes)

    class_def_str = ""  # the string for class definition
    class_pyi_str = ""  # the string for class type hints

    if state.flatten_nested_classes:
        flatten_nested_classes(classes_dict)
    _propagate_abstract_classes(classes_dict)
    for klass in classes_dict.values():
        # the nested classes of an excluded class are excluded too
        outer_names = klass.get("_qualified", "").split("::")
        if any(
            "_".join(outer_names[:i]) in exclude_classes
            for i in range(1, len(outer_names))
        ):
            klass["_skip"] = True
        if (
            klass.get("template")
            or klass.get("_skip")
            or klass["name"] in exclude_classes
            or any(
                _is_nested_base_of_module(inherit["class"])
                for inherit in klass["inherits"]
            )
        ):
            state.unwrapped_classes.add(klass["name"].split("<")[0])
        for method in klass["methods"]["public"] + klass["methods"]["private"]:
            # a deleted copy constructor X(const X&) = delete
            if (
                method["constructor"]
                and method.get("deleted")
                and len(method["parameters"]) == 1
                and method["parameters"][0]["type"].replace("const", "").strip()
                == klass["name"]
            ):
                state.unwrapped_classes.add(klass["name"])
    inheritance_tree_list = build_inheritance_tree(classes_dict)
    for klass in inheritance_tree_list:
        # class name
        class_name = klass["name"]
        # header
        stars = "".join(["*" for i in range(len(class_name) + 9)])
        class_def_str += f"/{stars}\n* class {class_name} *\n{stars}/\n"
        if class_name in exclude_classes:
            # if the class has to be excluded,
            # we go on with the next one to be processed
            continue
        # occt-800: skip class templates without an explicit instantiation,
        # they cannot be wrapped by SWIG and produce invalid C++ casts
        if klass.get("template", ""):
            logger.info("    %s skipped because it is a class template", class_name)
            continue
        # ensure the class returned by CppHeader is defined in this module
        # otherwise we go on with the next class
        if not class_name.startswith(state.current_module):
            continue
        if any(
            _is_nested_base_of_module(inherit["class"]) for inherit in klass["inherits"]
        ):
            # occt-800: e.g. BRepGraph_FacesOfEdge derives from an
            # instantiation of a nested class template, which is not wrapped
            logger.info("    %s skipped, its base class is not wrapped", class_name)
            continue
        if klass.get("_skip"):
            continue
        # we rename the class if the module is the same name
        # for instance TopoDS is both a module and a class
        # then we rename the class with lowercase
        logger.info("Class: %s", class_name)
        # the class type hint
        class_name_for_pyi = class_name.split("<")[0]

        if class_name == state.current_module:
            class_def_str += f"%rename({class_name.lower()}) {class_name};\n"
            class_name_for_pyi = class_name_for_pyi.lower()
        # then process the class itself
        # all constructors explicitly excluded: SWIG generates a default one,
        # which must not be done if the class has no public default constructor
        if not class_can_have_default_constructor(klass) or (
            class_name in exclude_member_functions.get(class_name, [])
            and not has_public_default_constructor(klass)
        ):
            class_def_str += f"%nodefaultctor {class_name};\n"
        if must_ignore_default_destructor(klass):
            # check if the destructor is protected or private
            class_def_str += f"%ignore {class_name}::~{class_name}();\n"
        if class_name in KEEP_CONSTRUCTOR_ARGS:
            # the C++ object stores a non-owning pointer to an argument (e.g.
            # an adaptor), which must not be garbage collected before it
            class_def_str += (
                f"%pythonappend {class_name}::{class_name} %{{\n"
                "    self._constructor_args = args\n%}\n"
            )
        # then defines the wrapper
        class_def_str += f"class {class_name}"
        class_pyi_start = len(class_pyi_str)
        class_pyi_str += f"\nclass {class_name_for_pyi}"  # type hints
        # inheritance process
        inherits_from = klass["inherits"]
        if inherits_from:  # at least 1 ancestor
            inheritance_name = inherits_from[0]["class"]
            check_dependency(inheritance_name)
            inheritance_access = inherits_from[0]["access"]
            class_def_str += f" : {inheritance_access} {inheritance_name}"
            class_pyi_str += "("
            if "::" not in inheritance_name and "<" not in inheritance_name:
                class_pyi_str += f"{inheritance_name}"
            if len(inherits_from) == 2:  ## 2 ancestors
                inheritance_name_2 = inherits_from[1]["class"]
                check_dependency(inheritance_name_2)
                inheritance_access_2 = inherits_from[1]["access"]
                class_def_str += f", {inheritance_access_2} {inheritance_name_2}"
                class_pyi_str += f", {inheritance_name_2}"
            class_pyi_str += ")"
        class_pyi_str += ":\n"
        class_pyi_str += "    pass\n"  # TODO CHANGE
        class_def_str += " {\n"
        # process class typedefs here
        typedef_str = "\tpublic:\n"
        for typedef_value in list(klass["typedefs"]["public"]):
            if ")" in typedef_value:
                continue
            if typedef_value in TYPEDEF_TO_EXCLUDE:
                continue
            # CppHeaderParser exposes the typedef name list publicly via
            # klass["typedefs"]["public"] but only the underscore-prefixed
            # _public_typedefs dict carries the resolved type strings.
            typedef_type = klass._public_typedefs[typedef_value]  # pylint: disable=protected-access
            typedef_str += f"typedef {typedef_type} {typedef_value};\n"
        class_def_str += typedef_str
        # process class enums here
        class_enums_list = klass["enums"]["public"]
        ###### Nested classes
        nested_classes = [] if state.flatten_nested_classes else klass["nested_classes"]
        for n in nested_classes:
            nested_class_name = n["name"]
            # skip anon structs, for instance in AdvApp2Var_SysBase
            # or Graphic3d_TransformPers
            if "anon" in nested_class_name:
                continue
            logger.info("    Wrap nested class %s::%s", class_name, nested_class_name)
            class_def_str += "\t\tclass " + nested_class_name + " {};\n"
        ####### class enums
        if class_enums_list:
            class_enum_def, class_enum_pyi = process_enums(class_enums_list)
            class_def_str += class_enum_def
            # the python proxies of the class enums are written in the class
            # body (e.g. GeomEval_HyperboloidSurface.SheetMode)
            if class_pyi_str.endswith("    pass\n"):
                class_pyi_str = class_pyi_str[: -len("    pass\n")] + "".join(
                    f"    {line}\n" if line else "\n"
                    for line in class_enum_pyi.strip("\n").split("\n")
                )
        # process class properties here
        properties_str = ""
        properties_pyi_str = ""
        # the public fields are filtered by type, except in Graphic3d
        filter_fields = state.flatten_nested_classes or state.wrap_public_fields
        if state.current_module == "Graphic3d" or filter_fields:
            for property_value in list(klass["properties"]["public"]):
                # TODO : cppheaderparser fails at finding private class properties
                if (
                    "NCollection_Vec2" in property_value["type"]
                ):  # issue in Aspect_Touch
                    logger.warning("Wrong type in class property : NCollection_Vec2")
                    continue
                if "using" in property_value["type"]:
                    logger.warning("Wrong type in class property : using")
                    continue
                if "return" in property_value["type"]:
                    logger.warning("Wrong type in class property : return")
                    continue
                if "std::map<" in property_value["type"]:
                    logger.warning("Wrong type in class property std::map")
                    continue
                if (
                    "static" in property_value["type"]
                    or "constexpr" in property_value["type"]
                ):
                    continue  # occt-800: static constexpr constants
                if filter_fields and not _is_wrappable_property_type(
                    property_value["type"], klass
                ):
                    logger.info(
                        "    property %s of type %s skipped",
                        property_value["name"],
                        property_value["type"],
                    )
                    continue
                if (
                    property_value["constant"]
                    or "virtual" in property_value["raw_type"]
                    or "allback" in property_value["raw_type"]
                ):
                    continue
                field_type = fix_type(property_value["type"])
                field_name = property_value["name"]
                if "array_size" in property_value:
                    temp = f"\t\t{field_type} {field_name}[{property_value['array_size']}];\n"
                elif filter_fields and field_type in _STRING_FIELD_TYPES:
                    # a member variable is accessed by pointer, which the str
                    # typemaps of the string classes don't cover: wrapped as a
                    # property whose accessors pass the string by value
                    temp = (
                        "\t\t%extend {\n"
                        f"\t\t\t{field_type} _get_{field_name}() {{ return $self->{field_name}; }}\n"
                        f"\t\t\tvoid _set_{field_name}({field_type} theValue) {{ $self->{field_name} = theValue; }}\n"
                        "\t\t}\n"
                        "\t\t%pythoncode {\n"
                        f"\t\t\t{field_name} = property(_get_{field_name}, _set_{field_name})\n"
                        "\t\t}\n"
                    )
                elif filter_fields and _is_foreign_enum(field_type):
                    # SWIG would wrap an enum it does not know as an opaque
                    # pointer, and importing its module may pull many others
                    # (STEPControl for DESTEP): wrapped as an int
                    temp = (
                        f"\t\t%apply int {{ {field_type} }};\n"
                        f"\t\t{field_type} {field_name};\n"
                    )
                else:
                    temp = f"\t\t{field_type} {field_name};\n"
                    if filter_fields:
                        # SWIG must know the class of the field
                        check_dependency(property_value["type"])
                properties_str += temp
                if not keyword.iskeyword(property_value["name"]):
                    # a C array is an opaque SWIG pointer
                    property_hint = (
                        "Any"
                        if "array_size" in property_value
                        else adapt_type_for_hint(fix_type(property_value["type"]))
                        or "Any"
                    )
                    properties_pyi_str += (
                        f"    {property_value['name']}: {property_hint}\n"
                    )
        # @TODO : wrap class typedefs (for instance BRepGProp_MeshProps)
        class_def_str += properties_str
        if properties_pyi_str:
            class_pyi_str = class_pyi_str.removesuffix("    pass\n")
            class_pyi_str += properties_pyi_str
        # process methods here
        class_public_methods = klass["methods"]["public"]
        # remove, from this list, all functions that
        # are excluded
        try:
            members_functions_to_exclude = exclude_member_functions[class_name]
        except KeyError:
            members_functions_to_exclude = []
        # if ever the header defines DEFINE STANDARD ALLOC
        # then we wrap a copy constructor. Very convenient
        # to create python classes that inherit from OCCT ones!
        if class_name in ["TopoDS_Shape", "TopoDS_Vertex"]:
            class_def_str += '\t\t%feature("autodoc", "1");\n'
            class_def_str += f"\t\t{class_name}(const {class_name} arg0);\n"
        methods_to_process = filter_member_functions(
            class_name,
            class_public_methods,
            members_functions_to_exclude,
            klass["abstract"],
        )
        # amons all methods, we first process constructors, than the others
        constructors, other_methods = methods_to_process
        # first constructors
        constructors_definitions, constructors_type_hints = process_constructors(
            constructors
        )
        class_def_str += constructors_definitions
        class_pyi_str += constructors_type_hints
        # and the other methods
        other_method_definitions, other_method_type_hints = process_methods(
            other_methods
        )
        class_def_str += other_method_definitions
        class_pyi_str += other_method_type_hints
        accessors_def, accessors_pyi = _synthesize_primitive_ref_getter_setters(
            class_name, other_methods
        )
        class_def_str += accessors_def
        class_pyi_str += accessors_pyi

        # after that change, we remove the "pass" if it appears to be unnecessary
        # for example
        # class gp_Ax22d:
        #    pass
        #    def Location
        # should be
        # class gp_Ax22d:
        #    def Location
        class_pyi_str = class_pyi_str.replace("pass\n    @overload", "@overload")
        class_pyi_str = class_pyi_str.replace("pass\n    def", "def")
        class_pyi_str = class_pyi_str.replace(
            "pass\n    @staticmethod", "@staticmethod"
        )

        class_pyi_str = class_pyi_str[:class_pyi_start] + _drop_single_overloads(
            class_pyi_str[class_pyi_start:]
        )
        # an alias of a class enum value (e.g. X = D.X in gp_Dir) is hidden,
        # at runtime, by the method of the same name (gp_Dir.X)
        class_methods = set(
            re.findall(
                r"^    def (\w+)\(", class_pyi_str[class_pyi_start:], re.MULTILINE
            )
        )
        if class_methods:
            class_pyi_str = class_pyi_str[:class_pyi_start] + re.sub(
                r"^    (\w+) = \w+\.\1\n",
                lambda m, methods=class_methods: (
                    "" if m.group(1) in methods else m.group(0)
                ),
                class_pyi_str[class_pyi_start:],
                flags=re.MULTILINE,
            )
        extra_def, extra_pyi = _class_specific_extensions(class_name)
        class_def_str += extra_def
        class_pyi_str += extra_pyi
        if check_has_related_handle(class_name) or class_name == "Standard_Transient":
            # added by %wrap_handle, see OccHandle.i
            class_pyi_str += DOWNCAST_PYI.substitute(ClassName=class_name_for_pyi)
        # then terminate the class definition
        class_def_str += "};\n\n"
        #
        # at last, check if there is a related handle
        # if yes, we integrate it into it's shadow class
        # TODO: check that the following is not restricted
        # to protected destructors !
        class_def_str += "\n"
        if check_has_related_handle(class_name) or class_name == "Standard_Transient":
            # Extend class by GetHandle method
            class_def_str += f"%make_alias({class_name})\n\n"
        if class_name == "Standard_Transient":
            # Extend the class with eq/neq/hash operators
            class_def_str += STANDARD_TRANSIENT_OPERATORS_TEMPLATE
        # hashing TopoDS_Shape . TODO: do it far all other classes that need to be hashed
        if class_name == "TopoDS_Shape":
            class_def_str += HASH_TOPODS_SHAPE_TEMPLATE
        if class_name == "ShapeAnalysis_FreeBounds":
            class_def_str += SHAPE_ANALYSIS_FREE_BOUNDS_TEMPLATE
            class_pyi_str += SHAPE_ANALYSIS_FREE_BOUNDS_TEMPLATE_PYI
        # if shape can be serialized as a Json, both get/set, implement pickling
        if (
            "DumpJson" in class_def_str
            and "InitFromJson" in class_def_str
            and class_name != "TopoDS_Shape"
        ):
            class_def_str += GETSTATE_TEMPLATE.substitute({"CLASSNAME": class_name})
            class_def_str += SETSTATE_TEMPLATE.substitute({"CLASSNAME": class_name})
        # We add pickling for TopoDS_Shapes
        if class_name == "TopoDS_Shape":
            class_def_str += TOPODS_SHAPE_PICKLE_TEMPLATE

        # for each class, overload the __repr__ method to avoid things like:
        # >>> print(box)
        # <OCC.TopoDS.TopoDS_Shape; proxy of <Swig Object of type 'TopoDS_Shape *' at 0x02
        # BCF770> >
        class_def_str += f"%extend {class_name} " + "{\n"
        class_def_str += "\t%" + "pythoncode {\n"
        class_def_str += "\t__repr__ = _dumps_object\n"
        # we process methods that are excluded from the wrapper
        # they used to be skipped, but it's better to explicitly
        # raise a MethodNotWrappedError exception
        for excluded_method_name in members_functions_to_exclude:
            if (
                excluded_method_name != "Handle"
                and "::" not in excluded_method_name
                and "Connect" not in excluded_method_name
                # no python stub for an operator, e.g. operator==
                and excluded_method_name.isidentifier()
            ):
                class_def_str += "\n\t@methodnotwrapped\n"
                class_def_str += f"\tdef {excluded_method_name}(self):\n\t\tpass\n"
        class_def_str += "\t}\n};\n\n"
        #
        # Special extents
        #
        if class_name == "Geom2d_Curve":  # see ticket #1381, numpy support
            class_def_str += "// numpy support for Geom2d_Curve\nCurve2dArrayEvalExtend(Geom2d_Curve)\n\n"
        if class_name == "Geom_Curve":  # see ticket #1381, numpy support
            class_def_str += (
                "// numpy support for Geom_Curve\nCurveArrayEvalExtend(Geom_Curve)\n\n"
            )
        if class_name == "Geom_Surface":  # see ticket #1381, numpy support
            class_def_str += "// numpy support for Geom_Surface\nSurfaceArrayEvalExtend(Geom_Surface)\n\n"
        # increment global number of classes
        state.nb_total_classes += 1
    excluded_def, excluded_pyi = _render_excluded_classes_proxies(exclude_classes)
    class_def_str += excluded_def
    class_pyi_str += excluded_pyi
    return class_def_str, class_pyi_str


def process_deprecated(list_of_classes_methods):
    """takes a list of tuples"""
    if not list_of_classes_methods:  # empty list
        return ""
    str_to_return = "/* deprecated methods */\n%pythoncode {\n"
    for class_name, method_name in list_of_classes_methods:
        str_to_return += "@deprecated\n"
        str_to_return += f"def {class_name}_{method_name}(*args):\n"
        str_to_return += f"\treturn {class_name}.{method_name}(*args)\n\n"
    str_to_return += "}\n"
    return str_to_return


def is_module(module_name):
    """Checks if the name passed as a parameter is
    (or is not) a module that aims at being wrapped.
    'Standard' should return True
    'inj' or whatever should return False
    """
    return any(mod[0] == module_name for mod in OCCT_MODULES)


def parse_module(module_name):
    """A module is defined by a set of headers. For instance AIS,
    gp, BRepAlgoAPI etc. For each module, generate three or more
    SWIG files. This parser returns :
    module_enums, module_typedefs, module_classes
    """
    module_headers = occt_headers(f"{module_name}_*.hxx")
    module_headers += occt_headers(f"{module_name}.hxx")
    module_headers.sort()
    # check if there are some files
    if len(module_headers) == 0:
        logger.warning(
            "No file for module %s. Please check that the module name is part of occt.",
            module_name,
        )

    # filter those headers
    module_headers = filter_header_list(module_headers, HXX_TO_EXCLUDE_FROM_CPPPARSER)
    module_typedefs = {}
    module_enums = []
    module_classes = {}
    module_free_functions = []
    for header_filename in module_headers:
        header = parse_header(header_filename)
        for klass in header.classes.values():
            klass["_header"] = header_filename
        # build the typedef dictionary
        module_typedefs.update(header.typedefs)
        # build the enum list
        module_enums += header.enums
        # build the class dictionary
        module_classes.update(header.classes.items())
        # build the free functions list
        module_free_functions += header.functions
    return module_typedefs, module_enums, module_classes, module_free_functions


class ModuleWrapper:
    def __init__(
        self,
        module_name,
        additional_dependencies,
        exclude_classes,
        exclude_member_functions,
    ):
        # Reinit global variables
        state.current_module = module_name
        state.deprecated_static_functions = []
        state.template_alias_names = set()
        state.flatten_nested_classes = MODULE_OPTIONS.get(module_name, {}).get(
            "flatten_nested_classes", False
        )
        state.include_classes = MODULE_OPTIONS.get(module_name, {}).get(
            "include_classes", []
        )
        state.wrap_public_fields = MODULE_OPTIONS.get(module_name, {}).get(
            "wrap_public_fields", False
        )
        state.flattened_classes = []
        state.nested_template_aliases = {}
        state.unwrapped_classes = set()
        # CURRENT_MODULE_PYI_STATIC_METHODS_ALIASES = ""
        # all modules depend, by default, upon Standard, NCollection and others
        if module_name not in ["Standard", "NCollection"]:
            state.python_module_dependency = ["Standard", "NCollection"]
            reset_header_depency()
        else:
            state.python_module_dependency = []

        logger.info("## Processing module %s", module_name)
        self._module_name = module_name
        self._module_docstring = get_module_docstring(module_name)
        # parse
        typedefs, enums, classes, free_functions = parse_module(module_name)
        # enums
        self._enums_str, self._enums_pyi_str = process_enums(enums)
        # handles
        self._wrap_handle_str = process_handles(classes, exclude_classes)
        # templates and typedefs
        (
            self._typedefs_str,
            self._typedefs_pyi_str,
            self._typedef_aliases_str,
        ) = process_typedefs(typedefs)
        # classes
        self._classes_str, self._classes_pyi_str = process_classes(
            classes, exclude_classes, exclude_member_functions
        )
        # special classes for NCollection_HArray1, NCollection_HArray2 and NCollection_HSequence
        harray1_def_str, harray1_pyi_str = process_harray1()
        self._classes_str += harray1_def_str
        self._classes_pyi_str += harray1_pyi_str

        harray2_def_str, harray2_pyi_str = process_harray2()
        self._classes_str += harray2_def_str
        self._classes_pyi_str += harray2_pyi_str

        hsequence_def_str, hsequence_pyi_str = process_hsequence()
        self._classes_str += hsequence_def_str
        self._classes_pyi_str += hsequence_pyi_str

        # free functions
        self._free_functions_str, self._free_functions_pyi_str = process_methods(
            free_functions
        )
        # the modules of the template arguments must be imported, else SWIG
        # returns the items as opaque pointers until the python module is
        # imported (e.g. the gp_Pnt of TColgp_Array1OfPnt). Checked last to
        # keep the order of the other imports.
        for type_name in state.template_argument_types:
            check_dependency(type_name)
        state.module_dependencies[module_name] = list(state.python_module_dependency)
        # other dependencies
        self._additional_dependencies = (
            additional_dependencies + state.header_dependency
        )

        # deprecated static functions after move to swig-4.1.1
        self._deprecated_swig_static_functions_str = process_deprecated(
            state.deprecated_static_functions
        )

    # Module-specific header injections (matched on module name).
    _MODULE_TEMPLATE_INJECTIONS: ClassVar[dict[str, str]] = {
        "NCollection": NCOLLECTION_HEADER_TEMPLATE,
        "BVH": BVH_HEADER_TEMPLATE,
        "Prs3d": PRS3D_HEADER_TEMPLATE,
        "Graphic3d": GRAPHIC3D_DEFINE_HEADER,
        "BRepAlgoAPI": BREPALGOAPI_HEADER,
        "HelixBRep": TOPODS_SHAPE_TYPES_HEADER,
    }

    _COMMON_INCLUDES = (
        "CommonIncludes",
        "ExceptionCatcher",
        "FunctionTransformers",
        "EnumTemplates",
        "Operators",
        "OccHandle",
        "IOStream",
        "ArrayMacros",
    )

    _NUMPY_MODULES = frozenset(
        {"Geom", "Geom2d", "Poly", "TColStd", "TColgp", "TShort"}
    )

    def generate_SWIG_files(self):
        if GENERATE_SWIG_FILES:
            self._write_module_header_file()
            self._write_swig_interface_file()
        self._write_pyi_stub_file()

    def _write_module_header_file(self):
        """Generate <module>_module.hxx, the C++ aggregate header included by .i."""
        path = HEADERS_OUTPUT_PATH / f"{self._module_name}_module.hxx"
        module_headers = occt_headers(f"{self._module_name}_*.hxx")
        module_headers += occt_headers(f"{self._module_name}.hxx")
        module_headers.sort()
        with path.open("w", encoding="utf8") as f:
            f.write(LICENSE_HEADER)
            f.write(f"#ifndef {self._module_name.upper()}_HXX\n")
            f.write(f"#define {self._module_name.upper()}_HXX\n\n\n")
            if self._module_name == "XCAFDoc":
                f.write("#include<TDF_Label.hxx>\n")
            for module_header in filter_header_list(
                module_headers, HXX_TO_EXCLUDE_FROM_BEING_INCLUDED
            ):
                basename = Path(module_header).name
                if basename not in HXX_TO_EXCLUDE_FROM_BEING_INCLUDED:
                    f.write(f"#include<{basename}>\n")
            f.write(f"\n#endif // {self._module_name.upper()}_HXX\n")

    def _write_swig_interface_file(self):
        """Generate <module>.i, the SWIG interface file."""
        path = SWIG_OUTPUT_PATH / f"{self._module_name}.i"
        with path.open("w", encoding="utf8") as f:
            self._write_swig_preamble(f)
            self._write_swig_cxx_includes(f)
            self._write_swig_python_imports(f)
            self._write_swig_module_specific_templates(f)
            self._write_swig_body(f)
            if self._module_name == "TopoDS":
                f.write(TOPODS_CLASS)

    def _write_swig_preamble(self, f):
        f.write(LICENSE_HEADER)
        # for instance: define GPDOCSTRING
        docstring_macro = f"{self._module_name.upper()}DOCSTRING"
        f.write(f"%define {docstring_macro}\n")
        f.write(f'"{self._module_docstring}"\n')
        f.write("%enddef\n")
        f.write(
            f'%module (package="OCC.Core", docstring={docstring_macro}) {self._module_name}\n\n'
        )
        f.write(WIN_PRAGMAS)
        for include in self._COMMON_INCLUDES:
            f.write(f"%include ../common/{include}.i\n")
        f.write("\n\n")

    def _write_swig_cxx_includes(self, f):
        """Write the %{ ... %} block: C++ includes, dependencies, namespace using."""
        f.write("%{\n")
        if self._module_name == "AdvApp2Var":  # windows compilation issues
            f.write("#if defined(_WIN32)\n#include <windows.h>\n#endif\n")
        # Issue with opencascade TopoDSToStep_Builder.hxx header
        if self._module_name in ["TopoDSToStep", "StepToTopoDS"]:
            f.write("#include<StepData_Factors.hxx>\n")
        if self._module_name == "ShapeProcess":
            f.write("#include <bitset>\nusing namespace std;\n")
        f.write(f"#include<{self._module_name}_module.hxx>\n")
        f.write("\n//Dependencies\n")
        for dep in state.python_module_dependency:
            f.write(f"#include<{dep}_module.hxx>\n")
        for add_dep in self._additional_dependencies:
            f.write(f"#include<{add_dep}_module.hxx>\n")
        # occt-800: BVH inner namespace also exposes free functions
        # (e.g. BVH::EncodeMortonCode) that get wrapped by SWIG
        if state.current_module in ["TopoDS", "BVH"]:
            f.write(f"using namespace {state.current_module};\n")
        if state.flattened_classes:
            f.write("// nested classes wrapped as top level classes\n")
            for qualified, flat in state.flattened_classes:
                f.write(f"typedef {qualified} {flat};\n")
        f.write("%};\n")

    def _write_swig_python_imports(self, f):
        if self._module_name in self._NUMPY_MODULES:
            f.write(NUMPY_INIT_TEMPLATE)
        for dep in state.python_module_dependency:
            if is_module(dep):
                f.write(f"%import {dep}.i\n")
        f.write("\n%pythoncode {\n")
        f.write("from enum import IntEnum\n")
        f.write("from OCC.Core.Exception import *\n")
        f.write("};\n\n")

    _FIXED_WIDTH_INT_RE = re.compile(r"\bu?int(8|16|32|64)_t\b")

    def _write_swig_module_specific_templates(self, f):
        """Inject NCollection / BVH / Prs3d / Graphic3d / BRepAlgoAPI blocks."""
        template = self._MODULE_TEMPLATE_INJECTIONS.get(self._module_name)
        if template is not None:
            f.write(template)
        # occt-800: BRepGraph counts and indices are uint32_t
        if state.flatten_nested_classes and self._FIXED_WIDTH_INT_RE.search(
            self._classes_str + self._typedefs_str + self._free_functions_str
        ):
            f.write("%include <stdint.i>\n")

    def _write_swig_body(self, f):
        f.write(self._enums_str)
        f.write(self._wrap_handle_str)
        f.write(self._typedefs_str)
        f.write(self._classes_str)
        f.write(self._typedef_aliases_str)
        f.write(self._deprecated_swig_static_functions_str)
        f.write(self._free_functions_str)

    def _write_pyi_stub_file(self):
        path = SWIG_OUTPUT_PATH / f"{self._module_name}.pyi"
        with path.open("w", encoding="utf8") as f:
            f.write("from enum import IntEnum\n")
            # typing.Iterator is qualified: the star import of NCollection
            # below brings a placeholder class named Iterator
            f.write("import typing\n")
            stub_body = (
                self._typedefs_pyi_str + self._enums_pyi_str + self._classes_pyi_str
            )
            if "numpy." in stub_body:
                # the numpy members of ArrayMacros.i
                f.write("import numpy\n")
            f.write("from typing import Any, overload, NewType, Optional, Tuple\n\n")
            f.writelines(
                f"from OCC.Core.{dep} import *\n"
                for dep in _stub_module_dependencies(
                    self._module_name, state.python_module_dependency, stub_body
                )
            )
            if self._module_name == "TDF":
                # the type of the attribute FindAttribute takes and returns
                f.write(
                    '\n_TDF_AttributeT = typing.TypeVar("_TDF_AttributeT", bound="TDF_Attribute")\n'
                )
            # NewTypes for typedefs that are plain aliases (e.g. Prs3d_Presentation
            # is just an alias for Graphic3d_Structure):
            #   Prs3d_Presentation = NewType("Prs3d_Presentation", Graphic3d_Structure)
            f.write(
                fix_template_stubs(
                    self._typedefs_pyi_str,
                    self._enums_pyi_str + self._classes_pyi_str,
                    self._typedefs_str,
                )
            )
            f.write(self._enums_pyi_str)
            f.write(self._classes_pyi_str)
            if self._module_name == "TopoDS":
                f.write(TOPODS_CLASS_PYI)


_PYI_CLASS_RE = re.compile(r"^class (\w+)\b", re.MULTILINE)
_PYI_ANNOTATION_NAME_RE = re.compile(r"(?:: |-> |\[|, )([A-Za-z0-9]+)_\w+")


def _stub_module_dependencies(module_name, module_dependencies, stub_body):
    """The modules the stub imports: those of the SWIG module, plus those
    of the types its annotations refer to, which SWIG may not need (e.g.
    TColgp does not %import gp.i)"""
    deps = [dep for dep in module_dependencies if is_module(dep)]
    for prefix in sorted(set(_PYI_ANNOTATION_NAME_RE.findall(stub_body))):
        if prefix != module_name and prefix not in deps and is_module(prefix):
            deps.append(prefix)
    return deps


_PYI_NEWTYPE_RE = re.compile(r"^(\w+) = NewType\(", re.MULTILINE)
_SWIG_TEMPLATE_RE = re.compile(r"^%template\((\w+)\)", re.MULTILINE)


def fix_template_stubs(typedefs_pyi, other_pyi, swig_typedefs):
    """The typedefs of the instantiated templates (e.g. TColgp_HArray1OfPnt,
    TColStd_IndexedDataMapOfStringString) are written as NewTypes, which
    hide the class written later for some of them (mypy keeps the first
    definition), and others have no class at all. Remove the NewTypes of the
    names that have a class, and write a generic class for the names
    instantiated by %template that have none."""
    class_names = set(_PYI_CLASS_RE.findall(typedefs_pyi + other_pyi))
    templates = _SWIG_TEMPLATE_RE.findall(swig_typedefs)
    to_remove = class_names | set(templates)
    lines = typedefs_pyi.split("\n")
    kept = []
    for line in lines:
        match = _PYI_NEWTYPE_RE.match(line)
        if match and match.group(1) in to_remove:
            if kept and kept[-1].startswith(
                "# the following typedef cannot be wrapped"
            ):
                kept.pop()
            continue
        kept.append(line)
    typedefs_pyi = "\n".join(kept)
    for name in templates:
        if name not in class_names:
            class_names.add(name)
            typedefs_pyi += (
                f"\nclass {name}:"
                "\n    def __init__(self, *args: Any, **kwargs: Any) -> None: ..."
                "\n    def __getattr__(self, name: str) -> Any: ...\n"
            )
    return typedefs_pyi


# Nested typedefs of classes that are not wrapped, rewritten to an equivalent
# wrapped type. XSAlgo is not wrapped: it would import Transfer and XSControl,
# which themselves use XSAlgo_ShapeProcessor::ParameterMap.
_NESTED_TYPEDEF_REWRITES = [
    ("XSAlgo_ShapeProcessor::ParameterMap", "Resource_DataMapOfAsciiStringAsciiString"),
]


def scan_typedef_aliases():
    """occt-800: scan a curated subset of OCCT headers for
    `typedef NCollection_X<...> Y;` declarations and populate
    state.harray_typedef_rewrites. The rewrite is applied to parameter and return
    types so SWIG type tags stay consistent across modules - e.g.
    NCollection_IndexedDataMap<TopoDS_Shape, TopTools_ListOfShape, ...>
    is rewritten to TopTools_IndexedDataMapOfShapeListOfShape.

    Also pre-populate state.all_harray1 / state.all_harray2 / state.all_hsequence for every
    `typedef NCollection_HArrayN<X> Y;` so that process_handles emits a
    %wrap_handle and process_harrayN emits the fake-class definition that
    used to be supplied by the (removed) DEFINE_HARRAYN macro.

    We scan only a small set of "leaf" container modules. Scanning every
    header was tried but introduces too many cross-module typedef
    equivalences and causes SWIG to emit cast tables for C++ types
    unavailable in the importing module.
    """
    target_modules = (
        "TopTools_",
        "TColgp_",
        "TColStd_",
        "TColGeom_",
        "TColGeom2d_",
        "TShort_",
        "Quantity_",
        "Poly_",
        "Storage_",
        "Interface_",
        "TDF_",
        "TDataStd_",
    )
    nc_pattern = re.compile(
        r"\btypedef\s+(NCollection_(?:H?Array1|H?Array2|H?Sequence|"
        r"DataMap|IndexedMap|IndexedDataMap|DoubleMap|Map|List|Vector|"
        r"DynamicArray|Buffer|FlatDataMap|OrderedDataMap|PackedMap)"
        r"<[^;]+?>)\s+([A-Za-z_]\w*)\s*;"
    )
    seen = {}
    # sorted: glob order depends on the filesystem, and both the registries
    # order and which alias wins for a given template depend on it
    for header_path in sorted(OCCT_INCLUDE_DIR.glob("*.hxx")):
        basename = header_path.name
        if not any(basename.startswith(prefix) for prefix in target_modules):
            continue
        try:
            content = header_path.read_text(encoding="utf8", errors="replace")
        except OSError:
            continue
        content = content.replace("Handle(", "opencascade::handle<").replace(
            "occ::handle", "opencascade::handle"
        )
        for match in nc_pattern.finditer(content):
            tpl = re.sub(r"\s+", "", match.group(1))
            if tpl.count("<") != tpl.count(">"):
                continue
            name = match.group(2)
            # Skip "local" typedefs that aren't a fully-qualified
            # `Module_Something` alias (e.g. `VectorOfPoint` in
            # BRepBuilderAPI_VertexInspector.hxx) - they aren't visible
            # outside their declaring header.
            if "_" not in name:
                continue
            if tpl not in seen:
                seen[tpl] = name
                seen[tpl.replace(",", ", ")] = name
            # Also register HArrayN typedefs into ALL_HARRAY{1,2} / state.all_hsequence
            # so process_handles / process_harray* generate the right wrapping.
            if tpl.startswith("NCollection_HArray1<"):
                inner = tpl[len("NCollection_HArray1<") : -1]
                if name not in state.all_harray1:
                    state.all_harray1[name] = f"NCollection_Array1<{inner}>"
            elif tpl.startswith("NCollection_HArray2<"):
                inner = tpl[len("NCollection_HArray2<") : -1]
                if name not in state.all_harray2:
                    state.all_harray2[name] = f"NCollection_Array2<{inner}>"
            elif tpl.startswith("NCollection_HSequence<"):
                inner = tpl[len("NCollection_HSequence<") : -1]
                if name not in state.all_hsequence:
                    state.all_hsequence[name] = f"NCollection_Sequence<{inner}>"
    state.harray_typedef_rewrites.extend(
        sorted(seen.items(), key=lambda kv: -len(kv[0]))
    )
    state.harray_typedef_rewrites.extend(_NESTED_TYPEDEF_REWRITES)
    # the first alias of a template wins, as in _apply_typedef_rewrites
    for tpl, name in reversed(state.harray_typedef_rewrites):
        state.typedef_rewrite_names[tpl] = name
    logger.info(
        "Built %d typedef rewrite mappings from OCCT headers",
        len(state.harray_typedef_rewrites),
    )


def write_enum_templates_file():
    """Generate common/EnumTemplates.i, shared by all modules. Must be called
    once every module has been processed, since state.all_byref_enums is
    filled in along the way."""
    path = COMMON_OUTPUT_PATH / "EnumTemplates.i"
    with path.open("w", encoding="utf8") as f:
        f.writelines(
            BYREF_ENUM_TEMPLATE % enum_name for enum_name in state.all_byref_enums
        )


def process_module(module_name, write_files=True):
    """Process a module, then write its files if write_files is True.

    Processing a module always updates the shared state (enums, handles,
    transients, ...) that the modules processed after it rely on."""
    for module in OCCT_MODULES:
        if module[0] == module_name:
            module_additionnal_dependencies = module[1]
            module_exclude_classes = module[2]
            modules_exclude_member_functions = module[3] if len(module) == 4 else {}
            wrapper = ModuleWrapper(
                module_name,
                module_additionnal_dependencies,
                module_exclude_classes,
                modules_exclude_member_functions,
            )
            if write_files:
                wrapper.generate_SWIG_files()
            return
    raise NameError(f"Module {module_name} not defined")


def process_toolkit(toolkit_name, modules_to_write=None):
    """Generate wrappers for modules depending on a toolkit
    For instance : TKernel, TKMath etc.
    If modules_to_write is given, only these modules' files are written.
    """
    modules_list = TOOLKITS[toolkit_name]
    logger.info("Processing toolkit %s ===", toolkit_name)
    for module in sorted(modules_list):
        process_module(module, modules_to_write is None or module in modules_to_write)


def process_all_toolkits(modules_to_write=None):
    """Process every toolkit, in modules.yaml order. If modules_to_write is
    given, all modules are still processed, so that the shared state is the
    same as in a full run, but only these modules' files are written."""
    # don't sort the toolkits, otherwise dependencies maybe skipped
    for toolkit in TOOLKITS:
        process_toolkit(toolkit, modules_to_write)
    # modules declared in modules.yaml but not part of any toolkit are only
    # generated when explicitly requested
    toolkit_modules = {m for modules in TOOLKITS.values() for m in modules}
    for module in modules_to_write or ():
        if module not in toolkit_modules:
            process_module(module)


def main(argv=None):
    parser = argparse.ArgumentParser(
        description="Generate pythonocc-core SWIG interface files and stubs."
    )
    parser.add_argument(
        "modules",
        nargs="*",
        help="OCCT modules to write (default: all toolkits). All modules are "
        "processed anyway, so that the output is the same as in a full run.",
    )
    parser.add_argument(
        "--config",
        default=DEFAULT_CONFIG_PATH,
        help="path to the configuration file (default: %(default)s)",
    )
    args = parser.parse_args(argv)
    unknown_modules = [m for m in args.modules if not is_module(m)]
    if unknown_modules:
        parser.error(f"unknown module(s): {', '.join(unknown_modules)}")
    if args.config != DEFAULT_CONFIG_PATH:
        load_config(args.config)
    check_paths()
    setup_logging()
    # occt-800: pre-pass to map canonical NCollection template forms back
    # to the typedef aliases pythonocc actually wraps. Without this, modules
    # that take a parameter typed as `NCollection_X<...>` cannot be passed a
    # Python object of the corresponding TopTools_/TColgp_/... typedef.
    scan_typedef_aliases()
    logger.info(get_log_header())
    start_time = time.perf_counter()
    process_all_toolkits(set(args.modules) if args.modules else None)
    if GENERATE_SWIG_FILES:
        write_enum_templates_file()
    end_time = time.perf_counter()
    total_time = end_time - start_time
    # footer
    logger.info(get_log_footer(total_time))
    logger.info("Number of classes: %s", state.nb_total_classes)
    logger.info("Number of methods: %s", state.nb_total_methods)


if __name__ == "__main__":
    main()