precis-cli 0.1.3__py3-none-any.whl

app/shared/core/data_source/specs/file_base.py

@@ -0,0 +1,252 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 文件数据源基类模块
+
+功能概述:
+- 提供所有基于文件的数据源的抽象基类
+- 封装文件路径、编码、表头等通用配置
+- 实现路径验证（非空、非法字符检查）
+- 提供相对/绝对路径的连接键生成
+
+架构设计:
+- 继承自 DataSourceSpec，扩展文件相关配置
+- 子类覆盖 type 和 source_type 即可支持新文件格式
+- field_validator 自动校验 path 字段合法性
+- 与文件加载器（ExcelLoader、CSVLoader 等）配对使用
+- FileValidationMixin 提供文件存在性、可读性、大小等通用验证
+
+输入示例:
+    spec = FileSourceSpec(
+        path="data/users.csv",
+        mode="relative",
+        encoding="utf-8",
+        header_enabled=True,
+        header_row=0,
+        skip_rows=0
+    )
+
+输出示例:
+    key = spec.get_connection_key()   # 返回绝对路径字符串
+    display = spec.to_display_dict()  # 返回可展示的字典
+"""
+
+from __future__ import annotations
+
+from abc import ABC
+from pathlib import Path
+from typing import Any, ClassVar, Literal
+
+from pydantic import Field, field_validator
+
+from .base import DataSourceSpec
+
+
+class FileSourceSpec(DataSourceSpec, ABC):
+    """
+    @classdesc 文件数据源基类
+
+    所有基于文件的数据源（Excel、CSV、JSON 等）的基类。
+    提供文件相关的通用配置和验证，子类只需覆盖 type 和 source_type 即可。
+
+    属性:
+        path: 文件路径（相对或绝对）
+        mode: 路径模式，"relative" 表示相对于项目根目录，"absolute" 表示绝对路径
+        encoding: 文件编码（默认 utf-8），常用于 CSV 和 JSON 文件
+        header_enabled: 是否有表头行，True 表示第一行（或 header_row 指定行）是列名
+        header_row: 表头行索引（从0开始），默认第0行
+        skip_rows: 跳过的行数（表头前），用于跳过文件开头的说明行
+        nrows: 读取的最大行数，None 表示读取全部数据
+
+    示例:
+        >>> spec = FileSourceSpec(path="data/users.csv", mode="relative")
+        >>> spec.get_connection_key()  # 返回解析后的绝对路径
+    """
+
+    # 类级别的类型标识
+    source_type: ClassVar[str] = "file"
+
+    # 实例级别的类型字段（必须与 source_type 匹配）
+    type: str = "file"  # 子类应覆盖此值
+
+    # 文件相关配置
+    path: str = Field(..., description="文件路径（相对或绝对）")
+    mode: Literal["relative", "absolute"] = Field("relative", description="路径模式")
+    encoding: str = Field("utf-8", description="文件编码")
+
+    # 表头配置
+    header_enabled: bool = Field(True, description="是否有表头行")
+    header_row: int = Field(0, ge=0, description="表头行索引（从0开始）")
+
+    # 数据范围配置
+    skip_rows: int = Field(0, ge=0, description="跳过的行数（表头前）")
+    nrows: int | None = Field(None, ge=1, description="读取的最大行数")
+
+    @field_validator("path")
+    @classmethod
+    def validate_path(cls, v: str) -> str:
+        """
+        @methoddesc 验证路径非空且不含非法字符
+
+        这是 Pydantic 的字段验证器，在创建实例时自动执行。
+        会去除首尾空白字符，并检查 Windows 非法字符。
+
+        Args:
+            v: 用户输入的路径字符串
+
+        Returns:
+            去除首尾空白后的路径字符串
+
+        Raises:
+            ValueError: 路径为空或包含 Windows 非法字符时抛出
+        """
+        # 检查路径是否为空或仅包含空白字符
+        if not v or not v.strip():
+            raise ValueError("文件路径不能为空")
+
+        normalized_path = v.strip()
+
+        # 检查非法字符。冒号需要单独处理，Windows 绝对路径盘符（如 D:\foo.csv）
+        # 是合法输入，不能被通用非法字符规则误杀。
+        illegal_chars = '<>"|?*'
+        if any(c in normalized_path for c in illegal_chars):
+            raise ValueError(f"文件路径包含非法字符: {illegal_chars}")
+
+        colon_count = normalized_path.count(":")
+        if colon_count:
+            is_windows_absolute_path = (
+                colon_count == 1
+                and len(normalized_path) >= 3
+                and normalized_path[0].isalpha()
+                and normalized_path[1] == ":"
+                and normalized_path[2] in ("\\", "/")
+            )
+            if not is_windows_absolute_path:
+                raise ValueError("文件路径包含非法字符: :")
+
+        # 去除首尾空白，避免因为空格导致文件找不到
+        return normalized_path
+
+    def get_connection_key(self) -> str:
+        """
+        @methoddesc 获取连接标识符
+
+        对于文件数据源，使用绝对路径作为唯一标识。
+        如果 mode 为 "relative"，会解析为绝对路径（基于当前工作目录）。
+
+        Returns:
+            文件的绝对路径字符串
+        """
+        # 如果已经是绝对路径，直接返回
+        if self.mode == "absolute":
+            return self.path
+
+        # 相对路径需要解析为绝对路径
+        # 注意：实际使用时需要基于项目根目录解析
+        # Path.resolve() 会将相对路径转换为绝对路径，并解析 . 和 ..
+        return str(Path(self.path).resolve())
+
+    def get_file_extension(self) -> str:
+        """
+        @methoddesc 获取文件扩展名（小写）
+
+        用于根据扩展名判断文件类型，或验证文件格式是否符合预期。
+
+        Returns:
+            小写的文件扩展名，如 ".csv"、".xlsx"、".json"
+        """
+        return Path(self.path).suffix.lower()
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典
+
+        在基类的基础上增加文件相关的展示字段，方便前端显示文件信息。
+
+        Returns:
+            包含 type、name、path、mode、encoding、extension 等字段的字典
+        """
+        return {
+            **super().to_display_dict(),  # 复用基类的通用字段
+            "path": self.path,
+            "mode": self.mode,
+            "encoding": self.encoding,
+            "extension": self.get_file_extension(),
+        }
+
+
+class FileValidationMixin:
+    """
+    @classdesc 文件验证混入类
+
+    提供文件数据源通用的验证方法，如检查文件是否存在、是否可读、文件大小等。
+    可以通过多重继承混入到具体的 Spec 类中使用。
+    所有方法返回 str | None：如果验证通过返回 None，失败返回错误信息字符串。
+    """
+
+    path: str  # 由混入目标类提供
+
+    def validate_file_exists(self) -> str | None:
+        """
+        @methoddesc 验证文件是否存在
+
+        Returns:
+            如果文件不存在返回错误信息，否则返回 None
+        """
+        path = Path(self.path)
+        if not path.exists():
+            return f"文件不存在: {self.path}"
+        return None
+
+    def validate_file_readable(self) -> str | None:
+        """
+        @methoddesc 验证文件是否可读
+
+        先检查路径是否存在且是文件（而非目录），
+        实际的读取权限测试在数据加载时进行。
+
+        Returns:
+            如果路径不是文件返回错误信息，否则返回 None
+        """
+        path = Path(self.path)
+        # 检查路径存在但不是文件（可能是目录）
+        if path.exists() and not path.is_file():
+            return f"路径不是文件: {self.path}"
+        # 实际读取测试在加载时进行（避免在这里做 I/O 操作影响性能）
+        return None
+
+    def validate_file_size(self, max_size_mb: float = 500) -> str | None:
+        """
+        @methoddesc 验证文件大小
+
+        检查文件是否超过指定大小，用于提前预警大文件可能导致加载缓慢。
+
+        Args:
+            max_size_mb: 最大允许大小（MB），默认 500MB
+
+        Returns:
+            警告信息（如果文件过大），或 None（如果正常或文件不存在）
+        """
+        path = Path(self.path)
+        # 如果文件不存在，跳过大小检查（存在性检查由 validate_file_exists 负责）
+        if not path.exists():
+            return None
+
+        # 计算文件大小（MB），1 MB = 1024 * 1024 字节
+        size_mb = path.stat().st_size / (1024 * 1024)
+        if size_mb > max_size_mb:
+            return f"警告: 文件较大 ({size_mb:.1f}MB)，加载可能较慢"
+        return None

app/shared/core/data_source/specs/json_source.py

@@ -0,0 +1,226 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview JSON 数据源规范模块
+
+功能概述:
+- 定义 JSON 文件的数据源规格类
+- 支持多种 JSON 格式：对象数组、JSON Lines、嵌套对象
+- 提供 JSONPath 提取和自动展平功能
+- 支持流式读取大文件和嵌套深度控制
+
+架构设计:
+- 继承自 FileSourceSpec，复用文件通用配置
+- 通过 @register_source_spec 装饰器自动注册到规格注册表
+- 与 JSONLoader 配对使用，通过 format 字段选择解析策略
+- model_validator 自动校验 json_path 格式和必要性
+
+输入示例:
+    # 对象数组
+    spec = JSONSourceSpec(path="data/users.json", format="array")
+    # 嵌套对象提取
+    spec = JSONSourceSpec(
+        path="data/api.json",
+        format="object",
+        json_path="$.data.items",
+        sep="."
+    )
+    # JSON Lines
+    spec = JSONSourceSpec(path="data/large.jsonl", format="lines")
+
+输出示例:
+    loader_class = spec.get_loader_class()   # 返回 JSONLoader
+    display = spec.to_display_dict()
+    # {"path": "data/api.json", "format": "object", "json_path": "$.data.items", ...}
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING, Any, ClassVar, Literal, Self
+
+if TYPE_CHECKING:
+    from ..loaders.base import DataSourceLoader
+
+from pydantic import Field, model_validator
+
+from .base import register_source_spec
+from .file_base import FileSourceSpec
+
+
+@register_source_spec
+class JSONSourceSpec(FileSourceSpec):
+    """
+    @classdesc JSON 数据源配置
+
+    支持多种 JSON 格式：对象数组、JSON Lines、嵌套对象。
+    提供 JSONPath 提取和自动展平功能，适应不同结构的 JSON 数据。
+
+    特有配置:
+        format: JSON 格式类型
+            - auto: 自动检测格式
+            - array: 对象数组（如 [{"id": 1}, {"id": 2}]）
+            - lines: JSON Lines（每行一个 JSON 对象）
+            - object: 嵌套对象（需要通过 json_path 提取数据）
+        json_path: JSONPath 提取路径（如 "$.data.users"），用于从嵌套结构中提取数据
+        record_path: 要展平的路径，用于将嵌套数组展开为行
+        meta_prefix: 元数据字段前缀，用于区分展平时的元数据字段
+        sep: 嵌套对象展平时的分隔符（如 "." 表示 "user.name"）
+        dtype: 列类型指定，如 {"id": "str", "count": "int"}
+        flatten: 是否自动扁平化嵌套结构（将嵌套对象展开为平面表格）
+        max_depth: 扁平化时的最大递归深度，防止无限递归
+        streaming_threshold_mb: 启用流式读取的阈值（MB），超过则分块读取
+        chunk_size: 流式读取时的块大小（行数）
+
+    示例:
+        # 对象数组
+        ```yaml
+        source:
+          type: json
+          path: data/users.json
+          format: array
+        ```
+
+        # 嵌套对象提取
+        ```yaml
+        source:
+          type: json
+          path: data/api_response.json
+          format: object
+          json_path: "$.data.items"
+          sep: "."
+        ```
+
+        # JSON Lines
+        ```yaml
+        source:
+          type: json
+          path: data/large_file.jsonl
+          format: lines
+        ```
+    """
+
+    source_type: ClassVar[str] = "json"
+    type: str = "json"
+
+    # JSON 格式类型(D8: auto 已废弃,必须显式指定 array/lines/object)
+    format: Literal["array", "lines", "object"] = Field(
+        ..., description="JSON 格式类型(必填):array-顶层数组, lines-JSON Lines, object-嵌套对象(需 json_path)"
+    )
+
+    # 数据提取路径
+    json_path: str | None = Field(None, description="JSONPath 提取路径，如 '$.data.items'（当 format=object 时必需）")
+
+    # 展平配置
+    record_path: str | None = Field(None, description="要展平的路径，如 'items'（用于数组字段展开为行）")
+    meta_prefix: str = Field("meta.", description="元数据字段前缀（展平时用于区分原始字段和元数据字段）")
+    sep: str = Field(".", description="嵌套对象展平时的分隔符（如 'user.name'）")
+
+    # 类型推断
+    dtype: dict[str, str] | None = Field(None, description="列类型指定，如 {'id': 'str', 'count': 'int'}")
+
+    # 展平配置
+    flatten: bool = Field(False, description="是否自动扁平化嵌套结构（将多层嵌套转为单层表格）")
+    max_depth: int | None = Field(None, description="扁平化时的最大递归深度（None 表示不限制）")
+
+    # 大文件处理
+    streaming_threshold_mb: float = Field(50.0, ge=1.0, description="启用流式读取的阈值（MB），超过此大小将分块读取")
+    chunk_size: int = Field(10000, ge=100, description="流式读取时的块大小（每次读取的行数）")
+
+    @model_validator(mode="before")
+    @classmethod
+    def validate_format_not_auto(cls, data: Any) -> Any:
+        """D8: 拦截已废弃的 format='auto',给出可操作的迁移引导。
+
+        auto 会猜测主数据数组(取最长/取第一个),与精确列定义的设计矛盾,已废弃。
+        存量配置里 format: auto 在此被捕获,抛出明确错误引导用户改成显式 format,
+        而非让 Pydantic Literal 报含糊的"unexpected value"。
+        """
+        if isinstance(data, dict):
+            fmt = data.get("format")
+            if fmt == "auto":
+                raise ValueError(
+                    "format='auto' 已废弃(自动检测会猜测主数据数组,可能导致校验跑错对象)。"
+                    "请显式改为:array(顶层数组 [{...}])、lines(JSON Lines)、"
+                    "或 object(嵌套对象,需配合 json_path 如 $.data)。"
+                )
+        return data
+
+    @model_validator(mode="after")
+    def validate_json_path(self) -> Self:
+        """
+        @methoddesc 当 format=object 时，json_path 是必需的
+
+        object 格式表示 JSON 是一个嵌套对象，需要通过 json_path 定位到数据数组。
+        如果没有 json_path，加载器不知道从哪里提取数据。
+
+        Raises:
+            ValueError: 当 format="object" 但 json_path 为空时抛出
+
+        Returns:
+            验证通过后的实例自身
+        """
+        if self.format == "object" and not self.json_path:
+            raise ValueError("当 format='object' 时，必须指定 json_path")
+        return self
+
+    @model_validator(mode="after")
+    def validate_json_path_format(self) -> Self:
+        """
+        @methoddesc 验证 json_path 格式
+
+        JSONPath 必须以 "$.") 开头，这是 JSONPath 标准的根元素标识。
+        例如 "$.data.items" 表示从根对象开始，访问 data 属性下的 items 属性。
+
+        Raises:
+            ValueError: 当 json_path 不以 "$." 开头时抛出
+
+        Returns:
+            验证通过后的实例自身
+        """
+        if self.json_path and not self.json_path.startswith("$."):
+            raise ValueError(f"json_path 必须以 '$.') 开头，当前值: '{self.json_path}'")
+        return self
+
+    def get_loader_class(self) -> builtins.type[DataSourceLoader]:
+        """
+        @methoddesc 获取 JSON 数据加载器类
+
+        延迟导入 JSONLoader，避免循环依赖。
+        JSONLoader 根据 format 字段选择不同的解析策略。
+
+        Returns:
+            JSONLoader 类
+        """
+        from ..loaders.json_loader import JSONLoader
+
+        return JSONLoader
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典
+
+        在基类的基础上增加 JSON 特有的展示字段。
+
+        Returns:
+            包含 format、json_path、sep 等 JSON 特有字段的字典
+        """
+        return {
+            **super().to_display_dict(),
+            "format": self.format,
+            "json_path": self.json_path,
+            "sep": self.sep,
+        }

app/shared/core/data_source/specs/sql_source.py

@@ -0,0 +1,161 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview SQL 数据源规格模块
+
+功能概述:
+- 定义 SQL 数据库连接的数据源规格类
+- 支持连接字符串、表名或查询语句配置
+- 提供查询参数和批量读取大小配置
+- 连接信息展示时自动隐藏密码等敏感信息
+
+架构设计:
+- 直接继承自 DataSourceSpec（非文件类数据源）
+- 通过 @register_source_spec 装饰器自动注册到规格注册表
+- 与 SQLLoader 配对使用，实现数据库数据加载
+- 连接键由 connection_string 和 table_or_query 组合生成
+
+输入示例:
+    spec = SQLSourceSpec(
+        connection_string="postgresql://user:pass@localhost/db",
+        table_or_query="SELECT * FROM users WHERE age > 18",
+        params={"min_age": 18},
+        batch_size=1000
+    )
+
+输出示例:
+    key = spec.get_connection_key()
+    # "postgresql://user:pass@localhost/db:SELECT * FROM users WHERE age > 18"
+    display = spec.to_display_dict()
+    # {"connection": "postgresql://user:***@localhost/db", "table_or_query": "...", ...}
+"""
+
+from __future__ import annotations
+
+import builtins
+from typing import TYPE_CHECKING, Any, ClassVar
+from urllib.parse import urlparse, urlunparse
+
+from pydantic import Field
+
+from .base import DataSourceSpec, register_source_spec
+
+if TYPE_CHECKING:
+    from ..loaders.base import DataSourceLoader
+
+
+@register_source_spec
+class SQLSourceSpec(DataSourceSpec):
+    """
+    @classdesc SQL 数据库数据源规格
+
+    用于从 SQL 数据库（PostgreSQL、MySQL、SQLite 等）加载数据。
+    支持通过完整查询语句或表名指定要读取的数据。
+
+    属性:
+        connection_string: 数据库连接字符串（包含协议、用户名、密码、主机、数据库名）
+        table_or_query: 表名或 SQL 查询语句
+        params: 查询参数（用于参数化查询，防止 SQL 注入）
+        batch_size: 批量读取大小（每次从数据库读取的行数）
+
+    示例:
+        ```yaml
+        source:
+          type: sql
+          connection_string: "postgresql://user:pass@localhost/mydb"
+          table_or_query: "SELECT * FROM users WHERE status = %(status)s"
+          params:
+            status: "active"
+        ```
+    """
+
+    source_type: ClassVar[str] = "sql"
+    type: str = "sql"
+
+    # 连接配置
+    connection_string: str = Field(..., description="数据库连接字符串（如 postgresql://user:pass@localhost/db）")
+    table_or_query: str = Field(..., description="表名（如 'users'）或 SQL 查询语句（如 'SELECT * FROM users'）")
+    params: dict[str, Any] | None = Field(None, description="查询参数（用于参数化查询，如 {'min_age': 18}）")
+
+    # 性能配置
+    batch_size: int = Field(1000, ge=1, description="批量读取大小（每次从数据库读取的行数，用于控制内存使用）")
+
+    def get_connection_key(self) -> str:
+        """
+        @methoddesc 获取连接标识符
+
+        SQL 数据源的连接键由连接字符串和查询语句组合而成，
+        确保同一个数据库的不同查询被视为不同的数据源。
+
+        Returns:
+            "连接字符串:查询语句" 格式的字符串
+        """
+        return f"{self.connection_string}:{self.table_or_query}"
+
+    def get_loader_class(self) -> builtins.type[DataSourceLoader]:
+        """
+        @methoddesc 获取 SQL 数据加载器类
+
+        延迟导入避免循环依赖。
+        SQLLoader 负责使用 SQLAlchemy 建立连接并执行查询。
+
+        Returns:
+            SQLLoader 类
+        """
+        # 延迟导入避免循环依赖（SQLLoader 可能会引用 SQLSourceSpec）
+        from ..loaders import SQLLoader
+
+        return SQLLoader
+
+    def to_display_dict(self) -> dict[str, Any]:
+        """
+        @methoddesc 转换为显示用的字典（隐藏敏感信息）
+
+        在展示连接信息时，自动将密码替换为 ***，避免敏感信息泄露。
+        解析逻辑：将 connection_string 按 @ 分割，再提取用户名部分，将密码替换。
+
+        Returns:
+            包含脱敏后的 connection、table_or_query 等字段的字典
+        """
+        base = super().to_display_dict()  # 获取基类的通用字段
+
+        # 隐藏连接字符串中的密码
+        conn = self.connection_string
+        try:
+            parsed = urlparse(conn)
+            if parsed.password:
+                netloc_parts = []
+                if parsed.username:
+                    netloc_parts.append(parsed.username)
+                    netloc_parts.append(":***")
+                if parsed.hostname:
+                    if netloc_parts:
+                        netloc_parts.append("@")
+                    netloc_parts.append(parsed.hostname)
+                if parsed.port:
+                    netloc_parts.append(f":{parsed.port}")
+                new_netloc = "".join(netloc_parts)
+                conn = urlunparse(
+                    (parsed.scheme, new_netloc, parsed.path, parsed.params, parsed.query, parsed.fragment)
+                )
+        except Exception:
+            pass
+
+        return {
+            **base,
+            "connection": conn,  # 脱敏后的连接字符串
+            "table_or_query": self.table_or_query,
+        }

app/shared/core/encoding.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""@fileoverview 控制台 UTF-8 输出编码助手（CLI 与 scripts 共用）
+
+Windows 中文终端默认编码为 GBK (cp936)，直接 print 中文/符号
+（✓ ✗ ⚠ 等）会抛 UnicodeEncodeError。在入口处调用本函数将
+stdout/stderr 重配为 UTF-8（errors=replace 兜底）。
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def setup_utf8_console() -> None:
+    """将 stdout/stderr 重配置为 UTF-8 编码（仅 Windows 需要，其他平台无害）。"""
+    if sys.platform == "win32":
+        for stream in (sys.stdout, sys.stderr):
+            if stream and hasattr(stream, "reconfigure"):
+                try:
+                    stream.reconfigure(encoding="utf-8", errors="replace")
+                except (AttributeError, OSError):
+                    pass