rucio-clients 37.7.1__py3-none-any.whl → 38.0.0rc1__py3-none-any.whl

rucio/client/subscriptionclient.py

@@ -180,6 +180,36 @@ class SubscriptionClient(BaseClient):
             exc_cls, exc_msg = self._get_exception(headers=result.headers, status_code=result.status_code, data=result.content)
             raise exc_cls(exc_msg)
 
+    def deactivate_subscription(
+            self,
+            name: str,
+            account: Optional[str] = None
+    ) -> Literal[True]:
+        """
+        Mark a subscription as inactive
+
+        Parameters
+        ----------
+        name : Name of the subscription
+        account : Account identifier
+
+        Raises
+        ------
+        NotFound
+            If subscription is not found
+        """
+        if not account:
+            account = self.account
+        path = self.SUB_BASEURL + '/' + account + '/' + name  # type: ignore
+        url = build_url(choice(self.list_hosts), path=path)
+        data = dumps({'options': {'state': 'I'}})
+        result = self._send_request(url, type_='PUT', data=data)
+        if result.status_code == codes.created:   # pylint: disable=no-member
+            return True
+        else:
+            exc_cls, exc_msg = self._get_exception(headers=result.headers, status_code=result.status_code, data=result.content)
+            raise exc_cls(exc_msg)
+
     def list_subscription_rules(
             self,
             account: str,

rucio/client/uploadclient.py

@@ -21,7 +21,8 @@ import os.path
 import random
 import socket
 import time
-from typing import TYPE_CHECKING, Any, Final, Optional, cast
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Final, Optional, Union, cast
 
 from rucio import version
 from rucio.client.client import Client
@@ -126,7 +127,7 @@ class UploadClient:
     def upload(
             self,
             items: "Iterable[FileToUploadDict]",
-            summary_file_path: Optional[str] = None,
+            summary_file_path: Optional[Union[str, os.PathLike[str]]] = None,
             traces_copy_out: Optional[list["TraceBaseDict"]] = None,
             ignore_availability: bool = False,
             activity: Optional[str] = None
@@ -418,7 +419,7 @@ class UploadClient:
             rse_attributes = {}
             try:
                 rse_attributes = self.client.list_rse_attributes(rse)
-            except:
+            except Exception:
                 logger(logging.WARNING, 'Attributes of the RSE: %s not available.' % rse)
             if self.client_location and 'lan' in rse_settings['domain'] and RseAttr.SITE in rse_attributes:
                 if self.client_location['site'] == rse_attributes[RseAttr.SITE]:
@@ -612,7 +613,8 @@ class UploadClient:
                     if checksum_name in file:
                         final_summary[file_did_str][checksum_name] = file[checksum_name]
 
-            with open(summary_file_path, 'w') as summary_file:
+            summary_path = Path(summary_file_path)
+            with summary_path.open('w') as summary_file:
                 json.dump(final_summary, summary_file, sort_keys=True, indent=1)
 
         if num_succeeded == 0:
@@ -865,7 +867,7 @@ class UploadClient:
         This method iterates over the provided items, each describing a local path and
         associated upload parameters, checks that each item has a valid path and RSE, and
         computes basic file details such as size and checksums. If the item is a directory
-        and `recursive` is set, the method calls `_recursive` to traverse subdirectories,
+        and `recursive` is set, the method calls `_collect_files_recursive` to traverse subdirectories,
         creating or attaching them as Rucio datasets or containers.
 
         Parameters
@@ -933,7 +935,7 @@ class UploadClient:
                     logger(logging.WARNING,
                            'Skipping %s because it has no files in it. Subdirectories are not supported.' % dname)
             elif os.path.isdir(path) and recursive:
-                files.extend(cast("list[FileToUploadWithCollectedInfoDict]", self._recursive(item)))
+                files.extend(cast("list[FileToUploadWithCollectedInfoDict]", self._collect_files_recursive(item)))
             elif os.path.isfile(path) and not recursive:
                 file = self._collect_file_info(path, item)
                 files.append(file)
@@ -1322,10 +1324,7 @@ class UploadClient:
         if self.tracing:
             send_trace(trace, self.client.trace_host, self.client.user_agent)
 
-    def _recursive(
-            self,
-            item: "FileToUploadDict"
-    ) -> list["FileToUploadWithCollectedAndDatasetInfoDict"]:
+    def _collect_files_recursive(self, item: "FileToUploadDict") -> list["FileToUploadWithCollectedAndDatasetInfoDict"]:
         """
         Recursively inspects a folder and creates corresponding Rucio datasets or containers.
 
@@ -1380,10 +1379,9 @@ class UploadClient:
         if path and isinstance(path, str):
             if path[-1] == '/':
                 path = path[0:-1]
-            i = 0
             path = os.path.abspath(path)
             for root, dirs, fnames in os.walk(path):
-                if len(dirs) > 0 and len(fnames) > 0 and i == 0:
+                if len(dirs) > 0 and len(fnames) > 0:
                     self.logger(logging.ERROR, 'A container can only have either collections or files, not both')
                     raise InputValidationError('Invalid input folder structure')
                 if len(fnames) > 0:
@@ -1404,7 +1402,6 @@ class UploadClient:
                 elif len(dirs) == 0 and len(fnames) == 0:
                     self.logger(logging.WARNING, 'The folder %s is empty, skipping' % root)
                     continue
-                i += 1
         # if everything went ok, replicate the folder structure in Rucio storage
         for dataset in datasets:
             try:

rucio/common/constants.py

@@ -215,4 +215,7 @@ RSE_ATTRS_BOOL = Literal[
 ]
 
 SUPPORTED_SIGN_URL_SERVICES_LITERAL = Literal['gcs', 's3', 'swift']
-SUPPORTED_SIGN_URL_SERVICES = list(get_args(SUPPORTED_SIGN_URL_SERVICES_LITERAL))
+SUPPORTED_SIGN_URL_SERVICES = list(get_args(SUPPORTED_SIGN_URL_SERVICES_LITERAL))
+
+OPENDATA_DID_STATE_LITERAL = Literal['draft', 'public', 'suspended']
+OPENDATA_DID_STATE_LITERAL_LIST = list(get_args(OPENDATA_DID_STATE_LITERAL))

rucio/common/exception.py

@@ -1206,3 +1206,58 @@ class ConnectionParameterNotFound(RucioException):
         super(ConnectionParameterNotFound, self).__init__(*args)
         self._message = f"Required connection parameter '{param}' is not provided."
         self.error_code = 114
+
+
+class OpenDataError(RucioException):
+    """
+    Error related to open data.
+    """
+
+    def __init__(self, *args):
+        super(OpenDataError, self).__init__(*args)
+        self._message = f"Error related to open data."
+        self.error_code = 115
+
+
+class OpenDataDataIdentifierNotFound(OpenDataError):
+    """
+    Throws when the data identifier is not in the open data catalog.
+    """
+
+    def __init__(self, *args):
+        super(OpenDataDataIdentifierNotFound, self).__init__(*args)
+        self._message = f"Data identifier not found in the open data catalog."
+        self.error_code = 116
+
+
+class OpenDataDataIdentifierAlreadyExists(OpenDataError):
+    """
+    Throws when the data identifier already exists in the open data catalog.
+    """
+
+    def __init__(self, *args):
+        super(OpenDataDataIdentifierAlreadyExists, self).__init__(*args)
+        self._message = f"Data identifier already exists in the open data catalog."
+        self.error_code = 117
+
+
+class OpenDataInvalidState(OpenDataError):
+    """
+    Throws when the open data entry is in an invalid state.
+    """
+
+    def __init__(self, *args):
+        super(OpenDataInvalidState, self).__init__(*args)
+        self._message = f"Open data entry is in an invalid state."
+        self.error_code = 118
+
+
+class OpenDataInvalidStateUpdate(OpenDataError):
+    """
+    Throws when a forbidden state update is attempted (e.g. from public to draft).
+    """
+
+    def __init__(self, *args):
+        super(OpenDataInvalidStateUpdate, self).__init__(*args)
+        self._message = f"Invalid state update attempted on open data entry."
+        self.error_code = 119

rucio/common/plugins.py

@@ -16,12 +16,13 @@ import importlib
 import logging
 import os
 from configparser import NoOptionError, NoSectionError
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Optional, TypeVar
 
 from packaging.specifiers import SpecifierSet
 
 from rucio.common import config
 from rucio.common.client import get_client_vo
+from rucio.common.constants import DEFAULT_VO
 from rucio.common.exception import InvalidAlgorithmName, PolicyPackageIsNotVersioned, PolicyPackageVersionError
 from rucio.version import current_version
 
@@ -31,6 +32,8 @@ if TYPE_CHECKING:
 
     from rucio.common.types import LoggerFunction
 
+LOGGER = logging.getLogger('policy')
+
 PolicyPackageAlgorithmsT = TypeVar('PolicyPackageAlgorithmsT', bound='PolicyPackageAlgorithms')
 
 
@@ -74,12 +77,44 @@ class PolicyPackageAlgorithms:
     """
     _ALGORITHMS: dict[str, dict[str, 'Callable[..., Any]']] = {}
     _loaded_policy_modules = False
+    _default_algorithms: dict[str, 'Callable[..., Any]'] = {}
 
     def __init__(self) -> None:
         if not self._loaded_policy_modules:
             self._register_all_policy_package_algorithms()
             self._loaded_policy_modules = True
 
+    @classmethod
+    def _get_default_algorithm(cls: type[PolicyPackageAlgorithmsT], algorithm_type: str, vo: str = "") -> Optional['Callable[..., Any]']:
+        """
+        Gets the default algorithm of this type, if present in the policy package.
+        The default algorithm is the function named algorithm_type within the module named algorithm_type.
+        Returns None if no default algorithm present.
+        """
+        # check if default algorithm for this VO is already cached
+        type_for_vo = vo + "_" + algorithm_type
+        if type_for_vo in cls._default_algorithms:
+            return cls._default_algorithms[type_for_vo]
+
+        default_algorithm = None
+        try:
+            if vo == DEFAULT_VO:
+                vo = ''
+            package = cls._get_policy_package_name(vo)
+        except (NoOptionError, NoSectionError):
+            return default_algorithm
+
+        module_name = package + "." + algorithm_type
+        try:
+            module = importlib.import_module(module_name)
+
+            if hasattr(module, algorithm_type):
+                default_algorithm = getattr(module, algorithm_type)
+                cls._default_algorithms[type_for_vo] = default_algorithm
+        except ImportError:
+            LOGGER.info('Policy algorithm module %s could not be loaded' % module_name)
+        return default_algorithm
+
     @classmethod
     def _get_one_algorithm(cls: type[PolicyPackageAlgorithmsT], algorithm_type: str, name: str) -> 'Callable[..., Any]':
         """
@@ -143,16 +178,18 @@ class PolicyPackageAlgorithms:
                 for vo in vos:
                     cls._try_importing_policy(vo['vo'])
 
+    @classmethod
+    def _get_policy_package_name(cls: type[PolicyPackageAlgorithmsT], vo: str = "") -> str:
+        env_name = 'RUCIO_POLICY_PACKAGE' + ('' if not vo else '_' + vo.upper())
+        package = os.getenv(env_name, "")
+        if not package:
+            package = str(config.config_get('policy', 'package' + ('' if not vo else '-' + vo)))
+        return package
+
     @classmethod
     def _try_importing_policy(cls: type[PolicyPackageAlgorithmsT], vo: str = "") -> None:
         try:
-            # import from utils here to avoid circular import
-
-            env_name = 'RUCIO_POLICY_PACKAGE' + ('' if not vo else '_' + vo.upper())
-            package = os.getenv(env_name, "")
-            if not package:
-                package = str(config.config_get('policy', 'package' + ('' if not vo else '-' + vo)))
-
+            package = cls._get_policy_package_name(vo)
             module = importlib.import_module(package)
             check_policy_module_version(module)
 

rucio/common/schema/generic.py

@@ -56,7 +56,7 @@ NAME_LENGTH = 250
 NAME = {"description": "Data Identifier name",
         "type": "string",
         "maxLength": NAME_LENGTH,
-        "pattern": "^[A-Za-z0-9][A-Za-z0-9\\.\\-\\_]*$"}
+        "pattern": r"^[/A-Za-z0-9][/A-Za-z0-9\.\-_]*$"}
 
 R_NAME = {"description": "Data Identifier name",
           "type": "string",
@@ -94,7 +94,9 @@ DEFAULT_RSE_ATTRIBUTE = {"description": "Default RSE attribute",
 
 REPLICA_STATE = {"description": "Replica state",
                  "type": "string",
-                 "enum": ["AVAILABLE", "UNAVAILABLE", "COPYING", "BEING_DELETED", "BAD", "SOURCE", "A", "U", "C", "B", "D", "S"]}
+                 "enum": [
+                     "AVAILABLE", "UNAVAILABLE", "COPYING", "BEING_DELETED", "BAD", "SOURCE", "TEMPORARY_UNAVAILABLE",
+                     "A", "U", "C", "B", "D", "S", "T"]}
 
 DATE = {"description": "Date",
         "type": "string",
@@ -367,7 +369,7 @@ ACCOUNT_ATTRIBUTE = {"description": "Account attribute",
                      "type": "string",
                      "pattern": r'^[a-zA-Z0-9-_\\/\\.]{1,30}$'}
 
-SCOPE_NAME_REGEXP = '/(.*)/(.*)'
+SCOPE_NAME_REGEXP = r"/([^/]+)/(.*)"
 
 DISTANCE = {"description": "RSE distance",
             "type": "object",

rucio/common/schema/generic_multi_vo.py

@@ -57,7 +57,7 @@ NAME_LENGTH = 250
 NAME = {"description": "Data Identifier name",
         "type": "string",
         "maxLength": NAME_LENGTH,
-        "pattern": "^[A-Za-z0-9][A-Za-z0-9\\.\\-\\_]*$"}
+        "pattern": r"^[/A-Za-z0-9][/A-Za-z0-9\.\-_]*$"}
 
 R_NAME = {"description": "Data Identifier name",
           "type": "string",
@@ -95,7 +95,9 @@ DEFAULT_RSE_ATTRIBUTE = {"description": "Default RSE attribute",
 
 REPLICA_STATE = {"description": "Replica state",
                  "type": "string",
-                 "enum": ["AVAILABLE", "UNAVAILABLE", "COPYING", "BEING_DELETED", "BAD", "SOURCE", "A", "U", "C", "B", "D", "S"]}
+                 "enum": [
+                     "AVAILABLE", "UNAVAILABLE", "COPYING", "BEING_DELETED", "BAD", "SOURCE", "TEMPORARY_UNAVAILABLE",
+                     "A", "U", "C", "B", "D", "S", "T"]}
 
 DATE = {"description": "Date",
         "type": "string",

rucio/common/types.py

@@ -19,10 +19,10 @@ from os import PathLike
 from rucio.common.constants import DEFAULT_VO
 
 if sys.version_info < (3, 11):  # pragma: no cover
-    from typing_extensions import TYPE_CHECKING, Any, Literal, NotRequired, Optional, TypedDict, TypeGuard, Union  # noqa: UP035
+    from typing_extensions import TYPE_CHECKING, Any, Literal, NotRequired, Optional, Required, TypedDict, TypeGuard, Union  # noqa: UP035
     PathTypeAlias = Union[PathLike, str]
 else:
-    from typing import TYPE_CHECKING, Any, Literal, NotRequired, Optional, TypedDict, TypeGuard, Union
+    from typing import TYPE_CHECKING, Any, Literal, NotRequired, Optional, Required, TypedDict, TypeGuard, Union
     PathTypeAlias = PathLike
 
 
@@ -391,8 +391,8 @@ class TraceSchemaDict(TypedDict):
 class FileToUploadDict(TypedDict):
     path: PathTypeAlias
     rse: str
-    did_scope: str
-    did_name: str
+    did_scope: NotRequired[str]
+    did_name: NotRequired[str]
     dataset_scope: NotRequired[str]
     dataset_name: NotRequired[str]
     dataset_meta: NotRequired[str]
@@ -408,6 +408,8 @@ class FileToUploadDict(TypedDict):
 
 
 class FileToUploadWithCollectedInfoDict(FileToUploadDict):
+    did_name: Required[str]
+    did_scope: Required[str]
     basename: str
     adler32: str
     md5: str
@@ -417,12 +419,11 @@ class FileToUploadWithCollectedInfoDict(FileToUploadDict):
     dirname: str
     upload_result: dict
     bytes: int
-    basename: str
 
 
 class FileToUploadWithCollectedAndDatasetInfoDict(FileToUploadWithCollectedInfoDict):
-    dataset_scope: str
-    dataset_name: str
+    dataset_scope: Required[str]
+    dataset_name: Required[str]
 
 
 class RequestGatewayDict(TypedDict):

rucio/common/utils.py

@@ -14,6 +14,7 @@
 
 import argparse
 import base64
+import copy
 import datetime
 import errno
 import getpass
@@ -30,20 +31,22 @@ import subprocess
 import tempfile
 import threading
 import time
+import types
 from collections import OrderedDict
 from enum import Enum
-from functools import cache, wraps
+from functools import cache, update_wrapper, wraps
 from io import StringIO
 from itertools import zip_longest
-from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, cast
 from urllib.parse import parse_qsl, quote, urlencode, urlparse, urlunparse
 from uuid import uuid4 as uuid
 from xml.etree import ElementTree
 
 import requests
+from typing_extensions import ParamSpec
 
 from rucio.common.config import config_get, config_get_bool
-from rucio.common.constants import BASE_SCHEME_MAP
+from rucio.common.constants import BASE_SCHEME_MAP, DEFAULT_VO
 from rucio.common.exception import DIDFilterSyntaxError, DuplicateCriteriaInDIDFilter, InputValidationError, InvalidType, MetalinkJsonParsingError, MissingModuleException, RucioException
 from rucio.common.extra import import_extras
 from rucio.common.plugins import PolicyPackageAlgorithms
@@ -59,6 +62,7 @@ if EXTRA_MODULES['paramiko']:
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterable, Iterator, Mapping, Sequence
+
     T = TypeVar('T')
     HashableKT = TypeVar('HashableKT')
     HashableVT = TypeVar('HashableVT')
@@ -390,17 +394,24 @@ class NonDeterministicPFNAlgorithms(PolicyPackageAlgorithms):
 
     _algorithm_type = 'non_deterministic_pfn'
 
-    def __init__(self) -> None:
+    def __init__(self, vo: str = DEFAULT_VO) -> None:
         """
         Initialises a non-deterministic PFN construction object
         """
         super().__init__()
+        
+        self.vo = vo
 
     def construct_non_deterministic_pfn(self, dsn: str, scope: Optional[str], filename: str, naming_convention: str) -> str:
         """
         Calls the correct algorithm to generate a non-deterministic PFN
         """
-        return self.get_algorithm(naming_convention)(dsn, scope, filename)
+        fn = None
+        if naming_convention == 'def':
+            fn = super()._get_default_algorithm(NonDeterministicPFNAlgorithms._algorithm_type, self.vo)
+        if fn is None:
+            fn = self.get_algorithm(naming_convention)
+        return fn(dsn, scope, filename)
 
     @classmethod
     def supports(cls: type[NonDeterministicPFNAlgorithmsT], naming_convention: str) -> bool:
@@ -510,7 +521,7 @@ class NonDeterministicPFNAlgorithms(PolicyPackageAlgorithms):
 NonDeterministicPFNAlgorithms._module_init_()
 
 
-def construct_non_deterministic_pfn(dsn: str, scope: Optional[str], filename: str, naming_convention: Optional[str] = None) -> str:
+def construct_non_deterministic_pfn(dsn: str, scope: Optional[str], filename: str, naming_convention: Optional[str] = None, vo: str = DEFAULT_VO) -> str:
     """
     Applies non-deterministic PFN convention to the given replica.
     use the naming_convention to call the actual function which will do the job.
@@ -518,7 +529,7 @@ def construct_non_deterministic_pfn(dsn: str, scope: Optional[str], filename: st
     which are not implemented inside this main rucio repository, so changing the
     argument list must be done with caution.
     """
-    pfn_algorithms = NonDeterministicPFNAlgorithms()
+    pfn_algorithms = NonDeterministicPFNAlgorithms(vo)
     if naming_convention is None or not NonDeterministicPFNAlgorithms.supports(naming_convention):
         naming_convention = 'def'
     return pfn_algorithms.construct_non_deterministic_pfn(dsn, scope, filename, naming_convention)
@@ -551,17 +562,24 @@ class ScopeExtractionAlgorithms(PolicyPackageAlgorithms):
 
     _algorithm_type = 'scope'
 
-    def __init__(self) -> None:
+    def __init__(self, vo: str = DEFAULT_VO) -> None:
         """
         Initialises scope extraction algorithms object
         """
         super().__init__()
 
+        self.vo = vo
+
     def extract_scope(self, did: str, scopes: Optional['Sequence[str]'], extract_scope_convention: str) -> 'Sequence[str]':
         """
         Calls the correct algorithm for scope extraction
         """
-        return self.get_algorithm(extract_scope_convention)(did, scopes)
+        fn = None
+        if extract_scope_convention == 'def':
+            fn = super()._get_default_algorithm(ScopeExtractionAlgorithms._algorithm_type, self.vo)
+        if fn is None:
+            fn = self.get_algorithm(extract_scope_convention)
+        return fn(did, scopes)
 
     @classmethod
     def supports(cls: type[ScopeExtractionAlgorithmsT], extract_scope_convention: str) -> bool:
@@ -642,9 +660,10 @@ ScopeExtractionAlgorithms._module_init_()
 def extract_scope(
         did: str,
         scopes: Optional['Sequence[str]'] = None,
-        default_extract: str = 'def'
+        default_extract: str = 'def',
+        vo: str = DEFAULT_VO
 ) -> 'Sequence[str]':
-    scope_extraction_algorithms = ScopeExtractionAlgorithms()
+    scope_extraction_algorithms = ScopeExtractionAlgorithms(vo)
     extract_scope_convention = config_get('common', 'extract_scope', False, None) or config_get('policy', 'extract_scope', False, None)
     if extract_scope_convention is None or not ScopeExtractionAlgorithms.supports(extract_scope_convention):
         extract_scope_convention = default_extract
@@ -1706,3 +1725,149 @@ def get_transfer_schemas() -> dict[str, list[str]]:
         scheme_map['davs'].append('srm')
 
     return scheme_map
+
+
+def wlcg_token_discovery() -> Optional[str]:
+    """
+    Discovers a WLCG bearer token from the environment, following the specified precedence.
+    Specs: https://zenodo.org/records/3937438
+
+    :returns: The discovered token (string), or None if no valid token is found.
+    """
+    user_id = os.geteuid()
+    token = None
+
+    # 1. Check BEARER_TOKEN environment variable
+    token = os.environ.get('BEARER_TOKEN')
+    if token is not None:
+        token = token.strip()
+        if token:
+            return token
+
+    # 2. Check BEARER_TOKEN_FILE environment variable
+    token_file = os.environ.get('BEARER_TOKEN_FILE')
+    if token_file:
+        try:
+            with open(token_file, 'r') as f:
+                token = f.read().strip()
+            if token:
+                return token
+        except FileNotFoundError:
+            pass
+        except Exception:
+            return None
+
+    # 3. Check $XDG_RUNTIME_DIR/bt_u$ID
+    xdg_runtime_dir = os.environ.get('XDG_RUNTIME_DIR')
+    if xdg_runtime_dir:
+        token_path = os.path.join(xdg_runtime_dir, f'bt_u{user_id}')
+        try:
+            with open(token_path, 'r') as f:
+                token = f.read().strip()
+            if token:
+                return token
+        except FileNotFoundError:
+            pass
+        except Exception:
+            return None
+
+    # 4. Check /tmp/bt_u$ID
+    token_path = f'/tmp/bt_u{user_id}'
+    try:
+        with open(token_path, 'r') as f:
+            token = f.read().strip()
+        if token:
+            return token
+    except FileNotFoundError:
+        pass
+    except Exception:
+        return None
+
+    # No valid token found
+    return None
+
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+
+def clone_function(
+        func: 'Callable[P, R]',
+        *,
+        keep_wrapped: bool = False
+) -> 'Callable[P, R]':
+    """
+    Create and return an **independent** copy of *func*.
+
+    The copy shares the original code object and global namespace but has
+    its **own** identity, making it safe to mutate attributes such as
+    ``__doc__``, ``__name__`` or custom flags without affecting the source
+    function.  Closure cells, default arguments and keyword‑only defaults
+    are preserved.
+
+    Parameters
+    ----------
+    func
+        The function to duplicate.
+    keep_wrapped
+        If *True* retains the ``__wrapped__`` pointer that ``update_wrapper`` adds
+        (useful when we *do* want wrapper semantics).  The default *False* removes
+        it so that introspection treats the clone as a stand‑alone function.
+
+    Returns
+    -------
+    Callable[P, R]
+        A new callable that behaves exactly like *func*.  At runtime the
+        object is a concrete ``types.FunctionType`` instance, but its static
+        type mirrors the original callable’s *parameter list* and *return type*.
+
+    Examples
+    --------
+    >>> def greet(name: str) -> str:
+    ...     \"\"\"Return a greeting.\"\"\"
+    ...     return f"Hello {name}"
+    ...
+    >>> new_greet = clone_function(greet)
+    >>> new_greet.__doc__ = "An altered docstring."
+    >>> greet.__doc__
+    'Return a greeting.'
+    >>> new_greet("world")
+    'Hello world'
+    """
+    orig = cast('types.FunctionType', func)
+
+    # 1. Re‑create the bare function object.
+    new = types.FunctionType(
+        orig.__code__,
+        orig.__globals__,
+        name=orig.__name__,
+        argdefs=orig.__defaults__,
+        closure=orig.__closure__,
+    )
+
+    # 2. Copy metadata such as ``__name__``, ``__qualname__``, ``__module__`` and ``__doc__``.
+    update_wrapper(
+        new,
+        orig,
+        assigned=(
+            "__module__",
+            "__name__",
+            "__qualname__",
+            "__doc__",
+            "__annotations__",
+        ),
+        updated=(),
+    )
+
+    # 3. Shallow‑copy the attribute dict so later mutations are independent.
+    new.__dict__.update(copy.copy(orig.__dict__))
+
+    # 4. Copy the (kw‑only) default values if present.
+    if orig.__kwdefaults__:
+        new.__kwdefaults__ = orig.__kwdefaults__.copy()
+
+    # 5. Detach from the original wrapper chain unless explicitly requested.
+    if not keep_wrapped and hasattr(new, "__wrapped__"):
+        delattr(new, "__wrapped__")
+
+    return cast('Callable[P, R]', new)