hutool.core.io.path

路径工具模块

Module Contents

Classes

PathUtil

路径工具类

API

class hutool.core.io.path.PathUtil

路径工具类

static get_path_separator() → str

获取当前操作系统的路径分隔符

返回:

路径分隔符字符串（Windows 为 ‘'，Linux/macOS 为 ‘/’）

static normalize(path: Union[str, pathlib.Path]) → str

标准化路径

解析符号链接、去除冗余分隔符和上级引用（..），返回绝对路径。

参数:

path – 原始路径

返回:

标准化后的路径字符串

static get_parent(path: Union[str, pathlib.Path]) → str

获取父目录路径

参数:

path – 文件或目录路径

返回:

父目录的路径字符串

static get_name(path: Union[str, pathlib.Path]) → str

获取路径中的文件名或最后一级目录名

参数:

path – 文件或目录路径

返回:

文件名或目录名

static sub_path(path: Union[str, pathlib.Path], from_index: int, to_index: int) → str

获取路径的子段

按路径层级截取子路径。索引从 0 开始。

参数:

  • path – 原始路径

  • from_index – 起始索引（含）

  • to_index – 结束索引（不含）

返回:

子路径字符串

抛出:

ValueError – 索引越界时抛出

static is_absolute(path: Union[str, pathlib.Path]) → bool

判断路径是否为绝对路径

参数:

path – 文件路径

返回:

是绝对路径返回 True

static exists(path: Union[str, pathlib.Path]) → bool

判断路径是否存在

参数:

path – 文件或目录路径

返回:

存在返回 True

static mkdir(path: Union[str, pathlib.Path]) → pathlib.Path

创建目录（包括所有必要的父目录）

如果目录已存在则不做任何操作。

参数:

path – 目录路径

返回:

创建的目录 Path 对象

static mk_parent_dirs(path: Union[str, pathlib.Path]) → pathlib.Path

创建文件的父目录

参数:

path – 文件路径

返回:

父目录的 Path 对象

static loop_files(path: Union[str, pathlib.Path], file_filter: Optional[Callable[[pathlib.Path], bool]] = None) → List[pathlib.Path]

递归遍历目录下的所有文件

参数:

  • path – 目录路径

  • file_filter – 可选的过滤函数，接受 Path 参数，返回 True 表示保留

返回:

文件 Path 列表

抛出:

FileNotFoundError – 路径不存在时抛出

static copy(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path

复制文件或目录

参数:

  • src – 源路径

  • dest – 目标路径

  • is_override – 是否覆盖已存在的目标，默认 True

返回:

目标路径的 Path 对象

抛出:

  • FileExistsError – 目标已存在且 is_override 为 False 时抛出

  • FileNotFoundError – 源路径不存在时抛出

static move(src: Union[str, pathlib.Path], dest: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path

移动文件或目录

参数:

  • src – 源路径

  • dest – 目标路径

  • is_override – 是否覆盖已存在的目标，默认 True

返回:

目标路径的 Path 对象

抛出:

  • FileExistsError – 目标已存在且 is_override 为 False 时抛出

  • FileNotFoundError – 源路径不存在时抛出

static del_path(path: Union[str, pathlib.Path]) → bool

删除文件或目录

目录将递归删除。如果路径不存在则返回 False。

参数:

path – 文件或目录路径

返回:

删除成功返回 True，路径不存在返回 False

static equals(path1: Union[str, pathlib.Path], path2: Union[str, pathlib.Path]) → bool

比较两个路径是否指向同一位置

通过解析后的绝对路径进行比较。

参数:

  • path1 – 第一个路径

  • path2 – 第二个路径

返回:

相等返回 True

static starts_with(path: Union[str, pathlib.Path], prefix: str) → bool

判断路径是否以指定前缀开头

参数:

  • path – 文件路径

  • prefix – 路径前缀

返回:

匹配返回 True

static ends_with(path: Union[str, pathlib.Path], suffix: str) → bool

判断路径是否以指定后缀结尾

参数:

  • path – 文件路径

  • suffix – 路径后缀

返回:

匹配返回 True

static copy_content(src_path: Union[str, pathlib.Path], dest_path: Union[str, pathlib.Path], is_override: bool = True) → pathlib.Path

复制路径内容

本方法是 copy() 的别名。

参数:

  • src_path – 源路径

  • dest_path – 目标路径

  • is_override – 是否覆盖已存在的目标，默认 True

返回:

目标路径的 Path 对象

抛出:

  • FileExistsError – 目标已存在且 is_override 为 False 时抛出

  • FileNotFoundError – 源路径不存在时抛出

static copy_file(src_path: Union[str, pathlib.Path], dest_path: Union[str, pathlib.Path]) → pathlib.Path

复制文件

仅用于复制文件，若源路径为目录则抛出异常。

参数:

  • src_path – 源文件路径

  • dest_path – 目标文件路径

返回:

目标路径的 Path 对象

抛出:

  • FileNotFoundError – 源文件不存在时抛出

  • IsADirectoryError – 源路径为目录时抛出

static create_temp_file(prefix: str = 'hutool', suffix: str = '.tmp', dir_path: Optional[Union[str, pathlib.Path]] = None) → pathlib.Path

创建临时文件

参数:

  • prefix – 文件名前缀，默认 ‘hutool’

  • suffix – 文件名后缀，默认 ‘.tmp’

  • dir_path – 临时文件所在目录，None 表示使用系统临时目录

返回:

创建的临时文件 Path 对象

static get_last_path_ele(path: Union[str, pathlib.Path]) → str

获取路径的最后一个元素

本方法是 get_name() 的别名。

参数:

path – 文件或目录路径

返回:

路径最后一级的名称

static get_path_ele(path: Union[str, pathlib.Path], index: int) → str

按索引获取路径元素

索引从 0 开始，支持负数索引（-1 表示最后一个元素）。

参数:

  • path – 文件或目录路径

  • index – 元素索引，支持负数

返回:

指定索引处的路径元素

抛出:

IndexError – 索引越界时抛出

static get_mime_type(path: Union[str, pathlib.Path]) → Optional[str]

获取文件的 MIME 类型

根据文件扩展名猜测 MIME 类型。

参数:

path – 文件路径

返回:

MIME 类型字符串，无法识别时返回 None

static is_dir_empty(dir_path: Union[str, pathlib.Path]) → bool

判断目录是否为空

参数:

dir_path – 目录路径

返回:

目录为空或不存在返回 True

static is_directory(path: Union[str, pathlib.Path]) → bool

判断路径是否为目录

本方法是 Path.is_dir() 的别名。

参数:

path – 文件或目录路径

返回:

是目录返回 True

static is_exists_and_not_directory(path: Union[str, pathlib.Path]) → bool

判断路径是否存在且不是目录

参数:

path – 文件路径

返回:

路径存在且不是目录返回 True

static is_file(path: Union[str, pathlib.Path]) → bool

判断路径是否为文件

本方法是 Path.is_file() 的别名。

参数:

path – 文件路径

返回:

是文件返回 True

static is_sub(parent: Union[str, pathlib.Path], child: Union[str, pathlib.Path]) → bool

判断 child 是否为 parent 的子路径

参数:

  • parent – 父路径

  • child – 子路径

返回:

child 是 parent 的子路径返回 True

判断路径是否为符号链接

参数:

path – 文件或目录路径

返回:

是符号链接返回 True

static move_content(src_path: Union[str, pathlib.Path], dest_path: Union[str, pathlib.Path]) → pathlib.Path

移动路径内容

本方法是 move() 的别名，使用默认参数（覆盖已存在的目标）。

参数:

  • src_path – 源路径

  • dest_path – 目标路径

返回:

目标路径的 Path 对象

抛出:

FileNotFoundError – 源路径不存在时抛出

static rename_path(path: Union[str, pathlib.Path], new_name: str) → pathlib.Path

重命名路径的最后一级名称

参数:

  • path – 原始路径

  • new_name – 新名称（仅最后一级）

返回:

重命名后的 Path 对象

抛出:

FileNotFoundError – 路径不存在时抛出

static to_abs_normal(path: Union[str, pathlib.Path]) → str

将路径转换为绝对路径并标准化

先转为绝对路径，再去除冗余分隔符和上级引用。

参数:

path – 原始路径

返回:

绝对标准化路径字符串

static walk_files(dir_path: Union[str, pathlib.Path], func: Optional[Callable[[pathlib.Path], None]] = None) → Generator[pathlib.Path, None, None]

遍历目录下的所有文件

返回一个生成器，逐个产出目录中的文件。若提供回调函数，则对每个文件执行回调。

参数:

  • dir_path – 目录路径

  • func – 可选的回调函数，接受 Path 参数

返回:

文件 Path 生成器

抛出:

FileNotFoundError – 路径不存在时抛出