Alaea 2.6.2__tar.gz → 2.6.4__tar.gz

alaea-2.6.4/.VERSION

@@ -0,0 +1 @@
+v2.6.4

{alaea-2.6.2 → alaea-2.6.4}/Alaea/Standard/xr_atmos.py

@@ -10,11 +10,20 @@ import pandas as pd
 import xarray as xr
 
 from .. import Ttime
-from .xr_attrs import add_attrs_lat, add_attrs_lon, add_attrs_precipitation, add_attrs_slp, add_attrs_temperature, add_attrs_time, add_attrs_TIME, add_attrs_wind, compress_scale_offset, fixed_encoding
+from .xr_attrs import add_attrs_lat, add_attrs_lon, add_attrs_precipitation, add_attrs_slp, add_attrs_temperature, add_attrs_time, add_attrs_TIME, add_attrs_wind, calc_dtype, calc_fillvalue, compress_scale_offset, fixed_encoding
 
 __all__ = ['xr_atmos_dataset', 'xr_wind_dataset', 'xr_air_temperature_dataset', 'xr_precipitation_dataset', 'xr_slp_dataset']
 
-_ATMOS_VARIABLES = frozenset({'wind_U10', 'wind_V10', 'air_temperature', 'precipitation', 'slp'})
+_ATMOS_VARIABLE_ATTRS = {
+    'visibility': {'units': 'm', 'long_name': 'Surface horizontal visibility', 'standard_name': 'visibility_in_air'},
+    'total_cloud_cover': {'units': '%', 'long_name': 'Total cloud cover for the entire atmosphere', 'standard_name': 'cloud_area_fraction', 'comment': 'Cloud fraction for the entire atmospheric column; values are percent, not the sum of level cloud fractions'},
+    'sunshine_duration': {'units': 's', 'long_name': 'Hourly sunshine duration', 'standard_name': 'duration_of_sunshine', 'cell_methods': 'time: sum', 'comment': 'Each value is the sunshine duration during its forecast-hour interval'},
+    'relative_humidity': {'units': '%', 'long_name': '2 metre relative humidity', 'standard_name': 'relative_humidity'},
+    'wind_gust': {'units': 'm s-1', 'long_name': 'Surface wind gust', 'standard_name': 'wind_speed_of_gust'},
+    'dew_point_temperature': {'units': 'K', 'long_name': '2 metre dew point temperature', 'standard_name': 'dew_point_temperature'},
+    'apparent_temperature': {'units': 'K', 'long_name': '2 metre apparent temperature', 'comment': 'Perceived temperature supplied by the source model; this is not 2 metre air temperature'},
+}
+_ATMOS_VARIABLES = frozenset({'wind_U10', 'wind_V10', 'air_temperature', 'precipitation', 'slp', *_ATMOS_VARIABLE_ATTRS})
 
 
 def xr_atmos_dataset(_lon: np.ndarray, _lat: np.ndarray, _time: Union[Sequence[Union[str, datetime, np.datetime64, pd.Timestamp]], np.ndarray, pd.DatetimeIndex], _TIME_type: str = 'char', _COMPRESS: bool = True, _ATTRS_GLOBAL: Optional[dict] = None, _ENCODING_GLOBAL: Optional[dict] = None, **kwargs) -> xr.Dataset:
@@ -27,7 +36,7 @@ def xr_atmos_dataset(_lon: np.ndarray, _lat: np.ndarray, _time: Union[Sequence[U
     :param _COMPRESS: 是否为数值业务变量配置整数 scale/offset packing。
     :param _ATTRS_GLOBAL: 可选的全局属性。
     :param _ENCODING_GLOBAL: 可选的 Dataset 编码设置。
-    :param kwargs: 可选的 wind_U10、wind_V10、air_temperature、precipitation 和 slp 三维数组。
+    :param kwargs: 可选的风、气温、降水、海平面气压、能见度、整层总云量、逐小时日照时长、2 米相对湿度、阵风、2 米露点和 2 米体感温度三维数组。
     :return: 时间、坐标、属性和编码已标准化的 xarray.Dataset。
     :raises ValueError: TIME 类型非法、没有业务变量或传入未知变量。
     """
@@ -57,6 +66,11 @@ def xr_atmos_dataset(_lon: np.ndarray, _lat: np.ndarray, _time: Union[Sequence[U
         dataset = add_attrs_precipitation(dataset, prec_name='precipitation')
     if 'slp' in variables:
         dataset = add_attrs_slp(dataset, slp_name='slp')
+    for name, attrs in _ATMOS_VARIABLE_ATTRS.items():
+        if name in variables:
+            dataset[name].attrs.update(attrs)
+            dtype = calc_dtype(dataset[name].data)
+            dataset[name].encoding = {'_FillValue': calc_fillvalue(dtype), 'dtype': dtype, 'zlib': True}
     if _ATTRS_GLOBAL is not None:
         dataset.attrs.update(_ATTRS_GLOBAL)
     dataset = fixed_encoding(dataset, **(_ENCODING_GLOBAL or {}))

{alaea-2.6.2 → alaea-2.6.4}/Alaea/Standard/xr_netcdf.py

@@ -142,6 +142,8 @@ def _write_zstd(_ds: xr.Dataset, path: Path, complevel: int, shuffle: bool) -> N
                     dtype = np.dtype(encoded.dtype)
                     fill_value = encoded.attrs.get('_FillValue')
                     create_arguments = {} if fill_value is None else {'fill_value': fill_value}
+                    if encoding.get('chunksizes') is not None:
+                        create_arguments['chunksizes'] = tuple(int(size) for size in encoding['chunksizes'])
                     target = output.createVariable(name, dtype, source.dims, **create_arguments)
                     if source.dims and np.issubdtype(dtype, np.number) and complevel > 0:
                         _apply_zstd_pipeline(target, complevel, shuffle)

{alaea-2.6.2 → alaea-2.6.4}/Alaea/__init__.py

@@ -14,6 +14,7 @@ from importlib.metadata import PackageNotFoundError, version
 from .Blogging import *
 from .commonCode import *
 from .cprintfs import *
+from .netcdf_input import *
 # from .pFVCOM import *
 from .Pyshell import *
 from .read_conf import *

alaea-2.6.4/Alaea/netcdf_input.py

@@ -0,0 +1,669 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""为 NetCDF 输入选择直接、本地 SSD 或内存读取方式。"""
+
+import ctypes
+import errno
+import os
+import secrets
+import shutil
+import tempfile
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import ExitStack, contextmanager
+from functools import lru_cache
+
+import xarray as xr
+from netCDF4 import Dataset
+from xarray.backends import NetCDF4DataStore
+
+from .storage import run_storage_fallback
+
+INPUT_COPY_BUFFER_BYTES = 32 * 1024 * 1024  # NFS 到本地 SSD 使用 32 MiB 顺序缓冲，减少大文件复制系统调用。
+STAGED_INPUT_FILE_PREFIX = 'alaea-netcdf-input-'
+SUPPORTED_INPUT_METHODS = {'FD_PATH', 'MEMORY', 'NAMED_FILE', 'O_TMPFILE'}
+SUPPORTED_BATCH_INPUT_METHODS = {'LOCAL', 'NAMED_FILE', 'O_TMPFILE'}
+DEFAULT_INPUT_AUTO_METHODS = ('O_TMPFILE', 'NAMED_FILE', 'MEMORY', 'FD_PATH')
+DEFAULT_BATCH_INPUT_AUTO_METHODS = ('O_TMPFILE', 'NAMED_FILE', 'LOCAL')
+DEFAULT_MEMORY_MAX_BYTES = 4 * 1024 * 1024 * 1024
+AT_FDCWD = -100
+AT_EMPTY_PATH = 0x1000
+AT_SYMLINK_FOLLOW = 0x400
+
+__all__ = ['DEFAULT_BATCH_INPUT_AUTO_METHODS', 'DEFAULT_INPUT_AUTO_METHODS', 'DEFAULT_MEMORY_MAX_BYTES', 'INPUT_METHOD_OPENERS', 'OpenedNetCDFInput', 'STAGED_INPUT_FILE_PREFIX', 'cleanup_orphaned_input_files', 'open_netcdf_input', 'stage_netcdf_inputs']
+
+
+class OpenedNetCDFInput:
+    """保存一个已打开的 xarray/NetCDF4 共享读取器及其内存缓冲。
+
+    :param dataset: 供制瓦业务读取变量的 xarray 数据集。
+    :type dataset: xarray.Dataset
+    :param netcdf: 供现有时间坐标逻辑读取的 NetCDF4 数据集；与 ``dataset`` 共用同一底层句柄。
+    :type netcdf: netCDF4.Dataset
+    :param method: 实际成功使用的输入读取方式。
+    :type method: str
+    :param memory_buffer: MEMORY 模式必须保持存活的完整 NC 字节缓冲；其他模式为 ``None``。
+    :type memory_buffer: bytearray | None
+    """
+
+    def __init__(self, dataset, netcdf, method, memory_buffer=None):
+        """建立一个统一生命周期的制瓦输入读取器。
+
+        :param dataset: 供制瓦业务读取变量的 xarray 数据集。
+        :type dataset: xarray.Dataset
+        :param netcdf: 与 xarray 共用底层句柄的 NetCDF4 数据集。
+        :type netcdf: netCDF4.Dataset
+        :param method: 实际成功使用的输入读取方式。
+        :type method: str
+        :param memory_buffer: MEMORY 模式需保持存活的完整 NC 缓冲。
+        :type memory_buffer: bytearray | None
+        :return: 无返回值；初始化当前对象。
+        :rtype: None
+        """
+        self.dataset = dataset
+        self.netcdf = netcdf
+        self.method = method
+        self.memory_buffer = memory_buffer
+
+    def close(self):
+        """关闭共享 HDF5 读取器并释放可能存在的内存缓冲。
+
+        :return: 无返回值；重复调用安全。
+        :rtype: None
+        """
+        dataset = self.dataset
+        self.dataset = None
+        try:
+            if dataset is not None:
+                dataset.close()
+        finally:
+            self.netcdf = None
+            self.memory_buffer = None
+
+
+def cleanup_orphaned_input_files(local_directory, logger=None, prefixes=None):
+    """删除 Linux 上已退出进程遗留的受控 NetCDF 具名输入副本。
+
+    :param local_directory: 制瓦输入副本所在的本地 SSD 目录。
+    :type local_directory: str | os.PathLike
+    :param logger: 可选标准 Logger，用于记录清理失败。
+    :type logger: logging.Logger | None
+    :param prefixes: 允许清理的文件名前缀；为空时仅使用 Alaea 当前前缀。
+    :type prefixes: collections.abc.Iterable[str] | None
+    :return: 删除的孤儿文件数，类型为 int。
+    :rtype: int
+    :raises ValueError: 前缀为空、重复或包含路径分隔符。
+    """
+    active_prefixes = tuple(prefixes or (STAGED_INPUT_FILE_PREFIX,))
+    if not active_prefixes or len(set(active_prefixes)) != len(active_prefixes) or any(not prefix or os.path.basename(prefix) != prefix for prefix in active_prefixes):
+        raise ValueError('prefixes 必须是不重复且不含路径的非空前缀')
+    if not os.path.isdir('/proc') or not os.path.isdir(local_directory):
+        return 0
+    removed = 0
+    for entry in os.scandir(local_directory):
+        matched_prefix = next((prefix for prefix in active_prefixes if entry.name.startswith(prefix)), None)
+        if matched_prefix is None or not entry.name.endswith('.nc') or not entry.is_file(follow_symlinks=False):
+            continue
+        pid_text = entry.name[len(matched_prefix):].split('-', 1)[0]
+        if not pid_text.isdigit() or os.path.exists(f'/proc/{pid_text}'):
+            continue
+        try:
+            os.unlink(entry.path)
+            removed += 1
+        except FileNotFoundError:
+            pass
+        except OSError as error:
+            if logger is not None:
+                logger.warning('清理已退出进程的本地 SSD 输入副本失败：path=%s, error=%s', entry.path, error)
+    return removed
+
+
+def _ensure_local_directory(local_directory, logger=None):
+    """创建本地 SSD 暂存目录并清理可确认的孤儿文件。
+
+    :param local_directory: 本地 SSD 暂存目录。
+    :type local_directory: str | os.PathLike
+    :param logger: 可选标准 Logger，用于记录孤儿文件清理失败。
+    :type logger: logging.Logger | None
+    :return: 可传给文件 API 的目录字符串。
+    :rtype: str
+    :raises OSError: 目录无法创建或访问。
+    """
+    active_local_directory = os.fspath(local_directory)
+    os.makedirs(active_local_directory, mode=0o700, exist_ok=True)
+    cleanup_orphaned_input_files(active_local_directory, logger=logger)
+    return active_local_directory
+
+
+def _source_signature(file_stat):
+    """提取足以发现复制期间替换或修改的源文件签名。
+
+    :param file_stat: ``os.stat`` 或 ``os.fstat`` 返回值。
+    :type file_stat: os.stat_result
+    :return: 设备、inode、字节数和纳秒修改时间组成的元组。
+    :rtype: tuple[int, int, int, int]
+    """
+    return file_stat.st_dev, file_stat.st_ino, file_stat.st_size, file_stat.st_mtime_ns
+
+
+def _copy_stable_source(source_path, copy_stream):
+    """打开源文件、执行一次顺序读取并确认复制期间源内容未变化。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param copy_stream: 接收 ``(源文件流, 源字节数)`` 并返回复制结果的函数。
+    :type copy_stream: collections.abc.Callable
+    :return: ``copy_stream`` 的返回值和源文件字节数。
+    :rtype: tuple[typing.Any, int]
+    :raises OSError: 源文件读取失败或复制字节数不完整。
+    :raises RuntimeError: 复制开始前或期间源文件被替换、截断或修改。
+    """
+    source_stat = os.stat(source_path)
+    source_signature = _source_signature(source_stat)
+    with open(source_path, 'rb', buffering=0) as source_stream:
+        if _source_signature(os.fstat(source_stream.fileno())) != source_signature:
+            raise RuntimeError(f'NFS 输入在复制开始前已变化：{source_path}')
+        result = copy_stream(source_stream, source_stat.st_size)
+        completed_signature = _source_signature(os.fstat(source_stream.fileno()))
+    if completed_signature != source_signature or _source_signature(os.stat(source_path)) != source_signature:
+        raise RuntimeError(f'NFS 输入在复制期间已变化：{source_path}')
+    return result, source_stat.st_size
+
+
+def _copy_source_to_file(source_path, staged_file):
+    """把稳定源文件顺序复制到已打开的本地文件。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param staged_file: 已打开且可写入的本地二进制文件。
+    :type staged_file: typing.BinaryIO
+    :return: 源文件字节数。
+    :rtype: int
+    :raises OSError: 复制失败或字节数不一致。
+    :raises RuntimeError: 复制期间源文件变化。
+    """
+    def copy_stream(source_stream, source_size):
+        """把当前源文件流复制到外层已打开的本地文件。
+
+        :param source_stream: 已校验身份的正式输入文件流。
+        :type source_stream: typing.BinaryIO
+        :param source_size: 正式输入的预期字节数。
+        :type source_size: int
+        :return: 实际写入本地文件的字节数。
+        :rtype: int
+        """
+        shutil.copyfileobj(source_stream, staged_file, length=INPUT_COPY_BUFFER_BYTES)
+        return staged_file.tell()
+
+    copied_bytes, source_size = _copy_stable_source(source_path, copy_stream)
+    if copied_bytes != source_size:
+        raise OSError(f'NFS 输入复制字节数不一致：{source_path}')
+    staged_file.flush()
+    staged_file.seek(0)
+    return source_size
+
+
+def _read_source_into_memory(source_path, maximum_bytes):
+    """把稳定源文件顺序读取到一个预分配内存缓冲。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param maximum_bytes: 允许进入内存模式的最大 NC 字节数。
+    :type maximum_bytes: int
+    :return: 完整 NC 字节缓冲。
+    :rtype: bytearray
+    :raises MemoryError: 文件超过配置上限或内存分配失败。
+    :raises OSError: 源文件读取不完整。
+    :raises RuntimeError: 读取期间源文件变化。
+    """
+    def copy_stream(source_stream, source_size):
+        """把当前源文件流写入预分配 RAM 缓冲。
+
+        :param source_stream: 已校验身份的正式输入文件流。
+        :type source_stream: typing.BinaryIO
+        :param source_size: 正式输入的预期字节数。
+        :type source_size: int
+        :return: 已完整填充的 NC 字节缓冲。
+        :rtype: bytearray
+        """
+        if source_size > maximum_bytes:
+            raise MemoryError(f'NC 文件 {source_size} 字节超过内存读取上限 {maximum_bytes} 字节')
+        memory_buffer = bytearray(source_size)
+        memory_view = memoryview(memory_buffer)
+        offset = 0
+        try:
+            while offset < source_size:
+                read_size = source_stream.readinto(memory_view[offset:min(offset + INPUT_COPY_BUFFER_BYTES, source_size)])
+                if not read_size:
+                    break
+                offset += read_size
+        finally:
+            memory_view.release()
+        if offset != source_size:
+            raise OSError(f'NFS 输入读取字节数不一致：{source_path}')
+        return memory_buffer
+
+    memory_buffer, _source_size = _copy_stable_source(source_path, copy_stream)
+    return memory_buffer
+
+
+def _wrap_netcdf_dataset(netcdf, method, memory_buffer=None):
+    """让 xarray 与既有时间坐标逻辑共享同一个 NetCDF4 句柄。
+
+    :param netcdf: 已成功打开的 NetCDF4 数据集。
+    :type netcdf: netCDF4.Dataset
+    :param method: 实际输入读取方式。
+    :type method: str
+    :param memory_buffer: MEMORY 模式的完整 NC 缓冲。
+    :type memory_buffer: bytearray | None
+    :return: 可统一关闭的 NetCDF 输入读取器。
+    :rtype: OpenedNetCDFInput
+    """
+    try:
+        dataset = xr.open_dataset(NetCDF4DataStore(netcdf))
+    except BaseException:
+        netcdf.close()
+        raise
+    return OpenedNetCDFInput(dataset, netcdf, method, memory_buffer)
+
+
+def _open_using_local_path(source_path, _local_directory, _memory_max_bytes):
+    """直接打开本地正式 NC，不复制数据。
+
+    :param source_path: 本地正式输入路径。
+    :type source_path: str
+    :param _local_directory: 未使用的统一方法参数。
+    :type _local_directory: str | os.PathLike
+    :param _memory_max_bytes: 未使用的统一方法参数。
+    :type _memory_max_bytes: int
+    :return: 已打开的 NetCDF 输入。
+    :rtype: OpenedNetCDFInput
+    """
+    return _wrap_netcdf_dataset(Dataset(source_path), 'LOCAL')
+
+
+def _open_using_fd_path(source_path, local_directory, _memory_max_bytes):
+    """复制到匿名临时文件，并通过当前平台的文件描述符路径打开 HDF5。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param local_directory: 本地 SSD 暂存目录。
+    :type local_directory: str | os.PathLike
+    :param _memory_max_bytes: 未使用的统一方法参数。
+    :type _memory_max_bytes: int
+    :return: 已打开的 NetCDF 输入。
+    :rtype: OpenedNetCDFInput
+    :raises RuntimeError: 当前平台没有可用的文件描述符路径。
+    """
+    active_local_directory = _ensure_local_directory(local_directory)
+    with tempfile.TemporaryFile(mode='w+b', suffix='.nc', dir=active_local_directory) as staged_file:
+        _copy_source_to_file(source_path, staged_file)
+        descriptor_paths = (f'/dev/fd/{staged_file.fileno()}', f'/proc/self/fd/{staged_file.fileno()}')
+        staged_path = next((path for path in descriptor_paths if os.path.exists(path)), None)
+        if staged_path is None:
+            raise RuntimeError('当前系统没有可供 NetCDF/HDF5 打开的文件描述符路径')
+        return _wrap_netcdf_dataset(Dataset(staged_path), 'FD_PATH')
+
+
+def _open_using_memory(source_path, _local_directory, memory_max_bytes):
+    """把完整 NC 顺序读入 RAM，再通过 NetCDF-C 内存接口打开。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param _local_directory: 未使用的统一方法参数。
+    :type _local_directory: str | os.PathLike
+    :param memory_max_bytes: 允许进入内存模式的最大 NC 字节数。
+    :type memory_max_bytes: int
+    :return: 已打开的 NetCDF 输入。
+    :rtype: OpenedNetCDFInput
+    """
+    memory_buffer = _read_source_into_memory(source_path, memory_max_bytes)
+    try:
+        netcdf = Dataset(os.path.basename(source_path), memory=memory_buffer)
+    except BaseException:
+        memory_buffer = None
+        raise
+    return _wrap_netcdf_dataset(netcdf, 'MEMORY', memory_buffer)
+
+
+def _temporary_link_path(local_directory):
+    """生成只供 O_TMPFILE 短暂建立目录项的进程独占路径。
+
+    :param local_directory: 本地 SSD 暂存目录。
+    :type local_directory: str
+    :return: 尚不存在的临时链接路径。
+    :rtype: str
+    """
+    return os.path.join(local_directory, f'{STAGED_INPUT_FILE_PREFIX}{os.getpid()}-{secrets.token_hex(8)}.nc')
+
+
+def _link_anonymous_file(file_descriptor, target_path):
+    """使用 Linux ``linkat(AT_EMPTY_PATH)`` 给 O_TMPFILE 临时建立目录项。
+
+    :param file_descriptor: 由 ``O_TMPFILE`` 创建的匿名文件描述符。
+    :type file_descriptor: int
+    :param target_path: 待建立的同文件系统具名路径。
+    :type target_path: str
+    :return: 无返回值。
+    :rtype: None
+    :raises OSError: 当前 libc、内核、权限或文件系统不支持该操作。
+    """
+    libc = ctypes.CDLL(None, use_errno=True)
+    linkat = getattr(libc, 'linkat', None)
+    if linkat is None:
+        raise OSError(errno.ENOSYS, '当前 libc 不提供 linkat')
+    linkat.argtypes = (ctypes.c_int, ctypes.c_char_p, ctypes.c_int, ctypes.c_char_p, ctypes.c_int)
+    linkat.restype = ctypes.c_int
+    encoded_target_path = os.fsencode(target_path)
+    if linkat(file_descriptor, b'', AT_FDCWD, encoded_target_path, AT_EMPTY_PATH) == 0:
+        return
+    # 普通服务用户通常没有 AT_EMPTY_PATH 所需的 CAP_DAC_READ_SEARCH；Linux 官方兼容路径
+    # 通过 /proc/self/fd 和 AT_SYMLINK_FOLLOW 链接同一 O_TMPFILE inode。
+    descriptor_path = os.fsencode(f'/proc/self/fd/{file_descriptor}')
+    if linkat(AT_FDCWD, descriptor_path, AT_FDCWD, encoded_target_path, AT_SYMLINK_FOLLOW) == 0:
+        return
+    error_number = ctypes.get_errno()
+    raise OSError(error_number, os.strerror(error_number), target_path)
+
+
+@lru_cache(maxsize=None)
+def _require_otmpfile_link_support(local_directory):
+    """用空文件探测并缓存指定文件系统的 O_TMPFILE/linkat 能力。
+
+    先探测可避免权限或文件系统不支持时完整复制大型 NC 后才失败。
+
+    :param local_directory: 已创建的本地 SSD 暂存目录。
+    :type local_directory: str
+    :return: 无返回值；成功结果按目录缓存。
+    :rtype: None
+    :raises OSError: 当前 Python、libc、内核、权限或文件系统不支持该组合。
+    """
+    if not hasattr(os, 'O_TMPFILE'):
+        raise OSError(errno.ENOTSUP, '当前 Python/操作系统不提供 O_TMPFILE')
+    probe_path = _temporary_link_path(local_directory)
+    probe_descriptor = os.open(local_directory, os.O_RDWR | os.O_TMPFILE | getattr(os, 'O_CLOEXEC', 0), 0o600)
+    try:
+        _link_anonymous_file(probe_descriptor, probe_path)
+    finally:
+        try:
+            os.unlink(probe_path)
+        except FileNotFoundError:
+            pass
+        os.close(probe_descriptor)
+
+
+def _open_using_named_file(source_path, local_directory, _memory_max_bytes):
+    """复制到具名 SSD 文件，HDF5 打开后立即删除文件名。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param local_directory: 本地 SSD 暂存目录。
+    :type local_directory: str | os.PathLike
+    :param _memory_max_bytes: 未使用的统一方法参数。
+    :type _memory_max_bytes: int
+    :return: 已打开的 NetCDF 输入。
+    :rtype: OpenedNetCDFInput
+    """
+    active_local_directory = _ensure_local_directory(local_directory)
+    staged_file = tempfile.NamedTemporaryFile(mode='w+b', prefix=f'{STAGED_INPUT_FILE_PREFIX}{os.getpid()}-', suffix='.nc', dir=active_local_directory, delete=False)
+    staged_path = staged_file.name
+    try:
+        _copy_source_to_file(source_path, staged_file)
+        return _wrap_netcdf_dataset(Dataset(staged_path), 'NAMED_FILE')
+    finally:
+        try:
+            os.unlink(staged_path)
+        except FileNotFoundError:
+            pass
+        staged_file.close()
+
+
+def _open_using_otmpfile(source_path, local_directory, _memory_max_bytes):
+    """使用 Linux O_TMPFILE 复制，短暂 linkat 后让 HDF5 打开并立即解除路径。
+
+    :param source_path: 正式输入文件路径。
+    :type source_path: str
+    :param local_directory: 本地 SSD 暂存目录。
+    :type local_directory: str | os.PathLike
+    :param _memory_max_bytes: 未使用的统一方法参数。
+    :type _memory_max_bytes: int
+    :return: 已打开的 NetCDF 输入。
+    :rtype: OpenedNetCDFInput
+    :raises OSError: Python、libc、内核、权限或文件系统不支持 O_TMPFILE/linkat。
+    """
+    active_local_directory = _ensure_local_directory(local_directory)
+    _require_otmpfile_link_support(active_local_directory)
+    open_flags = os.O_RDWR | os.O_TMPFILE | getattr(os, 'O_CLOEXEC', 0)
+    staged_file = os.fdopen(os.open(active_local_directory, open_flags, 0o600), 'w+b')
+    linked_path = _temporary_link_path(active_local_directory)
+    try:
+        _copy_source_to_file(source_path, staged_file)
+        _link_anonymous_file(staged_file.fileno(), linked_path)
+        return _wrap_netcdf_dataset(Dataset(linked_path), 'O_TMPFILE')
+    finally:
+        try:
+            os.unlink(linked_path)
+        except FileNotFoundError:
+            pass
+        staged_file.close()
+
+
+INPUT_METHOD_OPENERS = {
+    'FD_PATH': _open_using_fd_path,
+    'MEMORY': _open_using_memory,
+    'NAMED_FILE': _open_using_named_file,
+    'O_TMPFILE': _open_using_otmpfile,
+}
+
+
+def open_netcdf_input(input_file, storage_mode='AUTO', auto_methods=DEFAULT_INPUT_AUTO_METHODS, local_directory=None, memory_max_bytes=DEFAULT_MEMORY_MAX_BYTES, logger=None, context='netcdf-input'):
+    """直接或通过 SSD/内存暂存打开单个 NetCDF 输入。
+
+    :param input_file: 已存在的 NetCDF 输入路径。
+    :type input_file: str | os.PathLike
+    :param storage_mode: ``LOCAL``、``AUTO``、``O_TMPFILE``、``NAMED_FILE``、``MEMORY`` 或 ``FD_PATH``。
+    :type storage_mode: str
+    :param auto_methods: AUTO 模式的有序方法列表。
+    :type auto_methods: collections.abc.Iterable[str]
+    :param local_directory: SSD 暂存目录；使用文件暂存方式时不能为 None。
+    :type local_directory: str | os.PathLike | None
+    :param memory_max_bytes: MEMORY 模式允许的最大字节数。
+    :type memory_max_bytes: int
+    :param logger: 可选标准 Logger。
+    :type logger: logging.Logger | None
+    :param context: 不含敏感值的日志上下文。
+    :type context: str
+    :return: 已打开且必须由调用方关闭的 ``OpenedNetCDFInput``。
+    :raises ValueError: 模式、AUTO 顺序或内存上限非法。
+    :raises OSError: 所选方式无法读取输入。
+    :raises RuntimeError: 复制期间源文件变化或 AUTO 全部方式失败。
+    """
+    source_path = os.fspath(input_file)
+    active_storage_mode = str(storage_mode).strip().upper()
+    active_auto_methods = tuple(str(method).strip().upper() for method in auto_methods)
+    requested_methods = active_auto_methods if active_storage_mode == 'AUTO' else (active_storage_mode,)
+    if 'MEMORY' in requested_methods and (not isinstance(memory_max_bytes, int) or memory_max_bytes <= 0):
+        raise ValueError('memory_max_bytes 必须是正整数')
+    if any(method in {'FD_PATH', 'NAMED_FILE', 'O_TMPFILE'} for method in requested_methods) and local_directory is None:
+        raise ValueError('文件暂存方式必须提供 local_directory')
+    source_bytes = os.stat(source_path).st_size
+    operations = {'LOCAL': lambda: _open_using_local_path(source_path, local_directory, memory_max_bytes)} | {method: (lambda active_method=method: INPUT_METHOD_OPENERS[active_method](source_path, local_directory, memory_max_bytes)) for method in SUPPORTED_INPUT_METHODS}
+    return run_storage_fallback(active_storage_mode, active_auto_methods, operations, logger=logger, context=f'{context} source={source_path}, bytes={source_bytes}')
+
+
+def _stage_named_source(source_path, local_directory):
+    """把单个稳定 NetCDF 源文件复制为具名 SSD 候选。
+
+    :param source_path: 源 NetCDF 路径。
+    :type source_path: str | os.PathLike
+    :param local_directory: 已创建的 SSD 目录。
+    :type local_directory: str | os.PathLike
+    :return: 完整复制的候选路径，类型为 str。
+    :raises OSError: 候选创建、复制或刷盘失败。
+    :raises RuntimeError: 复制期间源文件变化。
+    """
+    descriptor, staged_path = tempfile.mkstemp(prefix=f'{STAGED_INPUT_FILE_PREFIX}{os.getpid()}-', suffix='.nc', dir=local_directory)
+    try:
+        with os.fdopen(descriptor, 'w+b') as staged_file:
+            _copy_source_to_file(source_path, staged_file)
+        return staged_path
+    except BaseException:
+        try:
+            os.unlink(staged_path)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _stage_otmp_source(source_path, local_directory):
+    """把单个稳定 NetCDF 源文件复制到 O_TMPFILE 并建立临时路径。
+
+    :param source_path: 源 NetCDF 路径。
+    :type source_path: str | os.PathLike
+    :param local_directory: 已验证 O_TMPFILE/linkat 的 SSD 目录。
+    :type local_directory: str | os.PathLike
+    :return: 必须由调用方关闭的文件对象和临时路径元组。
+    :raises OSError: 匿名文件、复制或链接创建失败。
+    :raises RuntimeError: 复制期间源文件变化。
+    """
+    staged_file = os.fdopen(os.open(local_directory, os.O_RDWR | os.O_TMPFILE | getattr(os, 'O_CLOEXEC', 0), 0o600), 'w+b')
+    staged_path = _temporary_link_path(local_directory)
+    try:
+        _copy_source_to_file(source_path, staged_file)
+        _link_anonymous_file(staged_file.fileno(), staged_path)
+        return staged_file, staged_path
+    except BaseException:
+        staged_file.close()
+        try:
+            os.unlink(staged_path)
+        except FileNotFoundError:
+            pass
+        raise
+
+
+def _remove_staged_path(staged_path):
+    """删除本模块创建的具名暂存路径，路径已不存在时保持幂等。
+
+    :param staged_path: 本模块创建的具名暂存文件路径。
+    :type staged_path: str | os.PathLike
+    :return: 无返回值。
+    :rtype: None
+    :raises OSError: 删除存在的暂存文件失败。
+    """
+    try:
+        os.unlink(staged_path)
+    except FileNotFoundError:
+        pass
+
+
+def _cleanup_otmp_result(result):
+    """删除 O_TMPFILE 临时链接并始终关闭对应文件句柄。
+
+    :param result: ``(文件对象, 临时链接路径)`` 元组。
+    :type result: tuple[typing.BinaryIO, str]
+    :return: 无返回值。
+    :rtype: None
+    :raises OSError: 临时链接存在但删除失败。
+    """
+    staged_file, staged_path = result
+    try:
+        _remove_staged_path(staged_path)
+    finally:
+        staged_file.close()
+
+
+def _stage_sources(source_paths, worker, workers, cleanup):
+    """有界并发执行多文件暂存，失败时清理已完成候选。
+
+    :param source_paths: 保持输入顺序的源路径元组。
+    :type source_paths: tuple[str, ...]
+    :param worker: 接收单个源路径并返回暂存结果的可调用对象。
+    :type worker: collections.abc.Callable
+    :param workers: 同时复制的最大文件数。
+    :type workers: int
+    :param cleanup: 接收单个暂存结果的清理回调。
+    :type cleanup: collections.abc.Callable
+    :return: 与源路径同顺序的暂存结果列表。
+    :raises BaseException: 任一暂存任务失败时清理后保留首个异常。
+    """
+    results = [None] * len(source_paths)
+    errors = []
+    with ThreadPoolExecutor(max_workers=min(workers, len(source_paths)), thread_name_prefix='netcdf-stage') as executor:
+        futures = [executor.submit(worker, source_path) for source_path in source_paths]
+        for index, future in enumerate(futures):
+            try:
+                results[index] = future.result()
+            except BaseException as error:
+                errors.append(error)
+    if errors:
+        for result in results:
+            if result is not None:
+                cleanup(result)
+        raise errors[0]
+    return results
+
+
+@contextmanager
+def stage_netcdf_inputs(input_files, storage_mode='AUTO', auto_methods=DEFAULT_BATCH_INPUT_AUTO_METHODS, local_directory=None, workers=1, logger=None, context='netcdf-input-batch'):
+    """在上下文内把多个 NetCDF 输入保留为可供 xarray 懒读取的路径。
+
+    :param input_files: 按业务顺序排列的 NetCDF 路径序列。
+    :type input_files: collections.abc.Iterable[str | os.PathLike]
+    :param storage_mode: ``AUTO``、``LOCAL``、``O_TMPFILE`` 或 ``NAMED_FILE``。
+    :type storage_mode: str
+    :param auto_methods: AUTO 模式的有序方法列表。
+    :type auto_methods: collections.abc.Iterable[str]
+    :param local_directory: O_TMPFILE/NAMED_FILE 使用的 SSD 目录。
+    :type local_directory: str | os.PathLike | None
+    :param workers: 同时复制的最大文件数。
+    :type workers: int
+    :param logger: 可选标准 Logger。
+    :type logger: logging.Logger | None
+    :param context: 不含敏感值的日志上下文。
+    :type context: str
+    :return: 上下文期间有效的路径元组；退出时自动清理 SSD 候选。
+    :rtype: contextlib.AbstractContextManager[tuple[str, ...]]
+    :raises ValueError: 输入、并发数或方法非法。
+    :raises OSError: 暂存无法完成。
+    :raises RuntimeError: 源文件变化或 AUTO 全部方式失败。
+    """
+    source_paths = tuple(os.fspath(path) for path in input_files)
+    if not source_paths:
+        raise ValueError('input_files 不能为空')
+    if not isinstance(workers, int) or isinstance(workers, bool) or workers < 1:
+        raise ValueError('workers 必须是正整数')
+    active_storage_mode = str(storage_mode).strip().upper()
+    active_auto_methods = tuple(str(method).strip().upper() for method in auto_methods)
+    requested_methods = active_auto_methods if active_storage_mode == 'AUTO' else (active_storage_mode,)
+    if any(method not in SUPPORTED_BATCH_INPUT_METHODS for method in requested_methods):
+        raise ValueError(f'批量路径暂存只支持 {sorted(SUPPORTED_BATCH_INPUT_METHODS)}')
+    if any(method != 'LOCAL' for method in requested_methods) and local_directory is None:
+        raise ValueError('批量 SSD 暂存必须提供 local_directory')
+    stack = ExitStack()
+
+    def local_operation():
+        """校验并返回原路径。"""
+        [os.stat(path) for path in source_paths]
+        return source_paths
+
+    def named_operation():
+        """并发生成具名 SSD 候选并登记退出清理。"""
+        active_directory = _ensure_local_directory(local_directory, logger=logger)
+        staged_paths = _stage_sources(source_paths, lambda path: _stage_named_source(path, active_directory), workers, _remove_staged_path)
+        [stack.callback(_remove_staged_path, path) for path in staged_paths]
+        return tuple(staged_paths)
+
+    def otmp_operation():
+        """并发生成 O_TMPFILE 候选并保持句柄到上下文退出。"""
+        active_directory = _ensure_local_directory(local_directory, logger=logger)
+        _require_otmpfile_link_support(active_directory)
+        staged_results = _stage_sources(source_paths, lambda path: _stage_otmp_source(path, active_directory), workers, _cleanup_otmp_result)
+        for staged_file, staged_path in staged_results:
+            stack.callback(_cleanup_otmp_result, (staged_file, staged_path))
+        return tuple(staged_path for _staged_file, staged_path in staged_results)
+
+    operations = {'LOCAL': local_operation, 'NAMED_FILE': named_operation, 'O_TMPFILE': otmp_operation}
+    try:
+        staged_paths = run_storage_fallback(active_storage_mode, active_auto_methods, operations, logger=logger, context=f'{context} files={len(source_paths)}')
+        yield staged_paths
+    finally:
+        stack.close()

{alaea-2.6.2 → alaea-2.6.4}/Alaea.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Alaea
-Version: 2.6.2
+Version: 2.6.4
 Summary: Some simple tools by Christmas
 Author: Christmas
 Author-email: 273519355@qq.com
@@ -66,7 +66,10 @@ continues uploading the remaining archives.
 ## Standard atmosphere datasets
 
 `xr_atmos_dataset` builds any supported combination of wind, 2 metre air
-temperature, per-period precipitation, and mean sea-level pressure. The
+temperature, per-period precipitation, mean sea-level pressure, visibility,
+entire-atmosphere total cloud cover, hourly sunshine duration, 2 metre
+relative humidity, surface wind gust, 2 metre dew point temperature, and
+2 metre apparent temperature. The
 single-element `xr_wind_dataset`, `xr_air_temperature_dataset`,
 `xr_precipitation_dataset`, and `xr_slp_dataset` interfaces use the same
 metadata and encoding path. Integer packing is enabled by default and can be
@@ -82,6 +85,11 @@ plugin is unavailable.
 error boundary, so input staging and output publication can share fallback
 policy without sharing incompatible lifecycle code.
 
+`open_netcdf_input` adds a shared single-file NetCDF reader for direct, local
+SSD, memory, named-file, and Linux `O_TMPFILE` modes. For `xarray.open_mfdataset`,
+`stage_netcdf_inputs` preserves input order while copying through a bounded
+worker pool and removes only its own staged files when the context exits.
+
 ## Unified spatial interpolation
 
 `s2s`, `g2s`, `s2g`, and `g2g` use the same argument order. `s` means

{alaea-2.6.2 → alaea-2.6.4}/Alaea.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ Alaea/S_DateTime.py
 Alaea/__init__.py
 Alaea/commonCode.py
 Alaea/cprintfs.py
+Alaea/netcdf_input.py
 Alaea/processBar.py
 Alaea/read_conf.py
 Alaea/server_info.py

{alaea-2.6.2 → alaea-2.6.4}/ChangeLog.md

@@ -1,5 +1,14 @@
 # Change Log
 
+## v2.6.4
+
+- `write_netcdf` 的 Zstd 分支现将每个数值变量指定的 `chunksizes` 传递给 NetCDF4/HDF5，避免全球时序数据被自动分为跨多个时次的大块；需要单时次访问的调用方可稳定保留 `time chunk=1`，压缩 filter 与数据内容不变。
+
+## v2.6.3
+
+- `xr_atmos_dataset` 新增能见度、整层大气总云量、逐小时日照持续时间、2 米相对湿度、地表阵风、2 米露点温度和 2 米体感温度，并统一写入物理属性与编码；可与原有五个大气字段任意组合，不再要求调用方补字段或伪造占位变量。
+- 新增公共 NetCDF 输入暂存模块：单文件支持直接、具名 SSD、内存、文件描述符及 Linux `O_TMPFILE` 读取；多文件支持按原顺序有限并发暂存到 SSD，供 `xarray.open_mfdataset` 使用，并在成功、失败及上下文退出时清理本模块候选文件。孤儿清理可接收受控旧前缀用于应用迁移，但不会扫描其他 NC；MakeTiles 与下载程序可共用同一实现，不再分别维护复制、降级和孤儿文件清理逻辑。
+
 ## v2.6.2
 
 - `run_storage_fallback` 的成功线路明细由 INFO 调整为 DEBUG，减少 `Storage method succeeded` 高频常规日志；实际失败并降级仍保持 WARNING。

{alaea-2.6.2 → alaea-2.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: Alaea
-Version: 2.6.2
+Version: 2.6.4
 Summary: Some simple tools by Christmas
 Author: Christmas
 Author-email: 273519355@qq.com
@@ -66,7 +66,10 @@ continues uploading the remaining archives.
 ## Standard atmosphere datasets
 
 `xr_atmos_dataset` builds any supported combination of wind, 2 metre air
-temperature, per-period precipitation, and mean sea-level pressure. The
+temperature, per-period precipitation, mean sea-level pressure, visibility,
+entire-atmosphere total cloud cover, hourly sunshine duration, 2 metre
+relative humidity, surface wind gust, 2 metre dew point temperature, and
+2 metre apparent temperature. The
 single-element `xr_wind_dataset`, `xr_air_temperature_dataset`,
 `xr_precipitation_dataset`, and `xr_slp_dataset` interfaces use the same
 metadata and encoding path. Integer packing is enabled by default and can be
@@ -82,6 +85,11 @@ plugin is unavailable.
 error boundary, so input staging and output publication can share fallback
 policy without sharing incompatible lifecycle code.
 
+`open_netcdf_input` adds a shared single-file NetCDF reader for direct, local
+SSD, memory, named-file, and Linux `O_TMPFILE` modes. For `xarray.open_mfdataset`,
+`stage_netcdf_inputs` preserves input order while copying through a bounded
+worker pool and removes only its own staged files when the context exits.
+
 ## Unified spatial interpolation
 
 `s2s`, `g2s`, `s2g`, and `g2g` use the same argument order. `s` means

{alaea-2.6.2 → alaea-2.6.4}/README.md

@@ -29,7 +29,10 @@ continues uploading the remaining archives.
 ## Standard atmosphere datasets
 
 `xr_atmos_dataset` builds any supported combination of wind, 2 metre air
-temperature, per-period precipitation, and mean sea-level pressure. The
+temperature, per-period precipitation, mean sea-level pressure, visibility,
+entire-atmosphere total cloud cover, hourly sunshine duration, 2 metre
+relative humidity, surface wind gust, 2 metre dew point temperature, and
+2 metre apparent temperature. The
 single-element `xr_wind_dataset`, `xr_air_temperature_dataset`,
 `xr_precipitation_dataset`, and `xr_slp_dataset` interfaces use the same
 metadata and encoding path. Integer packing is enabled by default and can be
@@ -45,6 +48,11 @@ plugin is unavailable.
 error boundary, so input staging and output publication can share fallback
 policy without sharing incompatible lifecycle code.
 
+`open_netcdf_input` adds a shared single-file NetCDF reader for direct, local
+SSD, memory, named-file, and Linux `O_TMPFILE` modes. For `xarray.open_mfdataset`,
+`stage_netcdf_inputs` preserves input order while copying through a bounded
+worker pool and removes only its own staged files when the context exits.
+
 ## Unified spatial interpolation
 
 `s2s`, `g2s`, `s2g`, and `g2g` use the same argument order. `s` means

{alaea-2.6.2 → alaea-2.6.4}/setup.py

@@ -8,7 +8,7 @@ with open("README.md", "r") as fh:
 
 setuptools.setup(
     name="Alaea",
-    version="2.6.2",
+    version="2.6.4",
     author="Christmas",
     author_email="273519355@qq.com",
     description="Some simple tools by Christmas",

{alaea-2.6.2 → alaea-2.6.4}/tests/test_core.py

@@ -28,6 +28,7 @@ import Alaea.cprintfs as CPRINT
 import Alaea.pFVCOM.writeFile as FVCOM_WRITE
 import Alaea.processBar as PROCESS_BAR
 from Alaea.Standard import calc_dtype, calc_scale_offset, compress_scale_offset, write_netcdf, xr_air_temperature_dataset, xr_atmos_dataset, xr_precipitation_dataset, xr_slp_dataset, xr_wave_dateset, xr_wind_dataset, xr_wind_dateset
+from Alaea.netcdf_input import INPUT_METHOD_OPENERS, STAGED_INPUT_FILE_PREFIX, cleanup_orphaned_input_files, open_netcdf_input, stage_netcdf_inputs
 from Alaea.storage import run_storage_fallback
 
 
@@ -257,7 +258,8 @@ class UtilityRegressionTest(unittest.TestCase):
         times = pd.date_range('2026-01-01', periods=2, freq='h', tz='UTC')
         coordinates = np.asarray([0.0], dtype=np.float32)
         values = xr.DataArray(np.ones((2, 1, 1), dtype=np.float32), dims=('time', 'latitude', 'longitude'))
-        atmosphere = xr_atmos_dataset(coordinates, coordinates, times, _COMPRESS=False, wind_U10=values, wind_V10=values, air_temperature=values, precipitation=values, slp=values)
+        added_variables = {'visibility', 'total_cloud_cover', 'sunshine_duration', 'relative_humidity', 'wind_gust', 'dew_point_temperature', 'apparent_temperature'}
+        atmosphere = xr_atmos_dataset(coordinates, coordinates, times, _COMPRESS=False, wind_U10=values, wind_V10=values, air_temperature=values, precipitation=values, slp=values, **{name: values for name in added_variables})
         datasets = (
             xr_wind_dataset(coordinates, coordinates, times, wind_U10=values, _COMPRESS=False),
             xr_air_temperature_dataset(coordinates, coordinates, times, values, _COMPRESS=False),
@@ -265,7 +267,7 @@ class UtilityRegressionTest(unittest.TestCase):
             xr_slp_dataset(coordinates, coordinates, times, values, _COMPRESS=False),
         )
 
-        self.assertEqual(set(atmosphere.data_vars), {'TIME', 'wind_U10', 'wind_V10', 'air_temperature', 'precipitation', 'slp'})
+        self.assertEqual(set(atmosphere.data_vars), {'TIME', 'wind_U10', 'wind_V10', 'air_temperature', 'precipitation', 'slp', *added_variables})
         self.assertEqual([set(dataset.data_vars) - {'TIME'} for dataset in datasets], [{'wind_U10'}, {'air_temperature'}, {'precipitation'}, {'slp'}])
         self.assertEqual(atmosphere.time.attrs['standard_name'], 'time')
         self.assertEqual(atmosphere.time.attrs['units'], 'seconds since 1970-01-01 00:00:00')
@@ -276,6 +278,13 @@ class UtilityRegressionTest(unittest.TestCase):
         self.assertEqual(atmosphere.air_temperature.attrs['standard_name'], 'air_temperature')
         self.assertEqual(atmosphere.precipitation.attrs['standard_name'], 'lwe_thickness_of_precipitation_amount')
         self.assertEqual(atmosphere.slp.attrs['standard_name'], 'air_pressure_at_mean_sea_level')
+        self.assertEqual(atmosphere.visibility.attrs['standard_name'], 'visibility_in_air')
+        self.assertEqual(atmosphere.total_cloud_cover.attrs['standard_name'], 'cloud_area_fraction')
+        self.assertEqual(atmosphere.sunshine_duration.attrs['cell_methods'], 'time: sum')
+        self.assertEqual(atmosphere.relative_humidity.attrs['long_name'], '2 metre relative humidity')
+        self.assertEqual(atmosphere.wind_gust.attrs['units'], 'm s-1')
+        self.assertEqual(atmosphere.dew_point_temperature.attrs['standard_name'], 'dew_point_temperature')
+        self.assertNotIn('standard_name', atmosphere.apparent_temperature.attrs)
         with tempfile.TemporaryDirectory() as directory:
             output = Path(directory) / 'atmos.nc'
             atmosphere.to_netcdf(output, engine='h5netcdf')
@@ -303,6 +312,7 @@ class UtilityRegressionTest(unittest.TestCase):
         coordinates = np.asarray([0.5], dtype=np.float32)
         values = np.asarray([[[1.0]], [[3.0]]], dtype=np.float32)
         dataset = xr_atmos_dataset(coordinates, coordinates, times, _TIME_type='str', wind_U10=values)
+        dataset['wind_U10'].encoding['chunksizes'] = (1, 1, 1)
         with tempfile.TemporaryDirectory() as directory:
             output = Path(directory) / 'zstd.nc'
             write_netcdf(dataset, output, compression='zstd', complevel=1)
@@ -312,6 +322,7 @@ class UtilityRegressionTest(unittest.TestCase):
                 self.assertTrue(filters['zstd'])
                 self.assertFalse(filters['zlib'])
                 self.assertEqual(filters['complevel'], 1)
+                self.assertEqual(netcdf.variables['wind_U10'].chunking(), [1, 1, 1])
                 self.assertEqual(netcdf.alaea_hdf5_filter_pipeline, 'shuffle(2)->zstd(32015,level=1)')
                 np.testing.assert_allclose(netcdf.variables['wind_U10'][:].reshape(-1), [1.0, 3.0], atol=float(netcdf.variables['wind_U10'].scale_factor))
 
@@ -353,6 +364,87 @@ class UtilityRegressionTest(unittest.TestCase):
         with self.assertRaisesRegex(OSError, 'cache unavailable'):
             run_storage_fallback('CACHE', ('CACHE', 'NFS'), operations)
 
+    def test_netcdf_input_single_and_batch_staging_preserve_data_and_cleanup(self):
+        """单文件和批量暂存必须保持数据、顺序及自动清理契约。"""
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            cache = root / 'cache'
+            sources = []
+            for index in range(2):
+                source = root / f'source-{index}.nc'
+                xr.Dataset({'value': ('sample', np.asarray([index], dtype=np.float32))}).to_netcdf(source)
+                sources.append(source)
+            for storage_mode in ('LOCAL', 'NAMED_FILE', 'MEMORY', 'FD_PATH'):
+                opened = open_netcdf_input(sources[0], storage_mode=storage_mode, local_directory=cache)
+                try:
+                    self.assertEqual(opened.method, storage_mode)
+                    np.testing.assert_array_equal(opened.dataset.value.values, [0.0])
+                    np.testing.assert_array_equal(opened.netcdf.variables['value'][:], [0.0])
+                finally:
+                    opened.close()
+                if cache.exists():
+                    self.assertEqual(list(cache.iterdir()), [])
+            for storage_mode in ('LOCAL', 'NAMED_FILE'):
+                with stage_netcdf_inputs(sources, storage_mode=storage_mode, local_directory=cache, workers=2) as staged_paths:
+                    self.assertEqual(len(staged_paths), 2)
+                    values = []
+                    for path in staged_paths:
+                        with xr.open_dataset(path) as dataset:
+                            values.append(float(dataset.value.values[0]))
+                    self.assertEqual(values, [0.0, 1.0])
+                    if storage_mode == 'NAMED_FILE':
+                        self.assertTrue(all(Path(path).parent == cache for path in staged_paths))
+                if cache.exists():
+                    self.assertEqual(list(cache.iterdir()), [])
+
+    def test_netcdf_input_auto_order_orphan_cleanup_and_failed_batch_cleanup(self):
+        """AUTO 依序降级，孤儿识别和批量失败均只清理本模块候选。"""
+        import Alaea.netcdf_input as netcdf_input
+
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            source = root / 'source.nc'
+            cache = root / 'cache'
+            cache.mkdir()
+            xr.Dataset({'value': ('sample', np.asarray([1.0], dtype=np.float32))}).to_netcdf(source)
+            sentinel = mock.Mock()
+            first = mock.Mock(side_effect=OSError('unsupported'))
+            second = mock.Mock(return_value=sentinel)
+            with mock.patch.dict(INPUT_METHOD_OPENERS, {'O_TMPFILE': first, 'NAMED_FILE': second}, clear=False):
+                self.assertIs(open_netcdf_input(source, storage_mode='AUTO', auto_methods=('O_TMPFILE', 'NAMED_FILE'), local_directory=cache), sentinel)
+            first.assert_called_once()
+            second.assert_called_once()
+
+            orphan = cache / f'{STAGED_INPUT_FILE_PREFIX}99999999-orphan.nc'
+            legacy_orphan = cache / 'legacy-netcdf-input-99999999-orphan.nc'
+            unrelated = cache / 'unrelated.nc'
+            orphan.write_bytes(b'orphan')
+            legacy_orphan.write_bytes(b'orphan')
+            unrelated.write_bytes(b'keep')
+            real_exists = os.path.exists
+            with mock.patch('Alaea.netcdf_input.os.path.isdir', return_value=True), mock.patch('Alaea.netcdf_input.os.path.exists', side_effect=lambda path: False if path == '/proc/99999999' else real_exists(path)):
+                self.assertEqual(cleanup_orphaned_input_files(cache, prefixes=(STAGED_INPUT_FILE_PREFIX, 'legacy-netcdf-input-')), 2)
+            self.assertFalse(orphan.exists())
+            self.assertFalse(legacy_orphan.exists())
+            self.assertEqual(unrelated.read_bytes(), b'keep')
+
+            calls = 0
+            original_stage = netcdf_input._stage_named_source
+
+            def fail_second(path, local_directory):
+                """首个候选成功后模拟第二个源在复制期间失败。"""
+                nonlocal calls
+                calls += 1
+                if calls == 2:
+                    raise RuntimeError('source changed')
+                return original_stage(path, local_directory)
+
+            with mock.patch('Alaea.netcdf_input._stage_named_source', side_effect=fail_second):
+                with self.assertRaisesRegex(RuntimeError, 'source changed'):
+                    with stage_netcdf_inputs((source, source), storage_mode='NAMED_FILE', local_directory=cache, workers=1):
+                        pass
+            self.assertEqual([path.name for path in cache.iterdir()], ['unrelated.nc'])
+
     @unittest.skipUnless(DASK_AVAILABLE, 'dask is optional')
     def test_standard_encoding_helpers_keep_dask_dtype_lazy_and_reduce_for_packing(self):
         """Dask dtype 推断不应读取数据，packing 只需得到正确范围。"""

alaea-2.6.2/.VERSION

@@ -1 +0,0 @@
-v2.6.2