From e92408c543425cbdc14a137c596fb777589501be Mon Sep 17 00:00:00 2001 From: ChenXin Date: Fri, 16 Aug 2019 16:53:02 +0800 Subject: [PATCH] update docs of io.file_utils --- fastNLP/io/file_utils.py | 28 +++++++++++++++++++--------- 1 file changed, 19 insertions(+), 9 deletions(-) diff --git a/fastNLP/io/file_utils.py b/fastNLP/io/file_utils.py index 8b2d1c79..9febfe4a 100644 --- a/fastNLP/io/file_utils.py +++ b/fastNLP/io/file_utils.py @@ -89,14 +89,16 @@ FASTNLP_EXTEND_EMBEDDING_URL = {'elmo': 'fastnlp_elmo_url.txt', def cached_path(url_or_filename: str, cache_dir: str = None, name=None) -> Path: """ 给定一个url，尝试通过url中的解析出来的文件名字filename到{cache_dir}/{name}/{filename}下寻找这个文件， - (1)如果cache_dir=None, 则cache_dir=~/.fastNLP/; 否则cache_dir=cache_dir - (2)如果name=None, 则没有中间的{name}这一层结构；否者中间结构就为{name} + + 1. 如果cache_dir=None, 则cache_dir=~/.fastNLP/; 否则cache_dir=cache_dir + 2. 如果name=None, 则没有中间的{name}这一层结构；否者中间结构就为{name} 如果有该文件，就直接返回路径 + 如果没有该文件，则尝试用传入的url下载 或者文件名(可以是具体的文件名，也可以是文件夹)，先在cache_dir下寻找该文件是否存在，如果不存在则去下载, 并 - 将文件放入到cache_dir中. + 将文件放入到cache_dir中. :param str url_or_filename: 文件的下载url或者文件名称。 :param str cache_dir: 文件的缓存文件夹。如果为None，将使用"~/.fastNLP"这个默认路径 @@ -132,10 +134,13 @@ def cached_path(url_or_filename: str, cache_dir: str = None, name=None) -> Path: def get_filepath(filepath): """ 如果filepath为文件夹， + 如果内含多个文件, 返回filepath + 如果只有一个文件, 返回filepath + filename 如果filepath为文件 + 返回filepath :param str filepath: 路径 @@ -155,9 +160,9 @@ def get_filepath(filepath): def get_cache_path(): """ - 获取默认的fastNLP存放路径, 如果将FASTNLP_CACHE_PATH设置在了环境变量中，将使用环境变量的值，使得不用每个用户都去下载。 + 获取fastNLP默认cache的存放路径, 如果将FASTNLP_CACHE_PATH设置在了环境变量中，将使用环境变量的值，使得不用每个用户都去下载。 - :return: str + :return str: 存放路径 """ if 'FASTNLP_CACHE_DIR' in os.environ: fastnlp_cache_dir = os.environ.get('FASTNLP_CACHE_DIR') @@ -262,8 +267,9 @@ def _get_dataset_url(name): def split_filename_suffix(filepath): """ - 给定filepath返回对应的name和suffix. 如果后缀是多个点，仅支持.tar.gz类型 - :param filepath: + 给定filepath 返回对应的name和suffix. 如果后缀是多个点，仅支持.tar.gz类型 + + :param filepath: 文件路径 :return: filename, suffix """ filename = os.path.basename(filepath) @@ -278,6 +284,10 @@ def get_from_cache(url: str, cache_dir: Path = None) -> Path: 文件解压，将解压后的文件全部放在cache_dir文件夹中。 如果从url中下载的资源解压后有多个文件，则返回目录的路径; 如果只有一个资源文件，则返回具体的路径。 + + :param url: 资源的 url + :param cache_dir: cache 目录 + :return: 路径 """ cache_dir.mkdir(parents=True, exist_ok=True) @@ -394,12 +404,12 @@ def untar_gz_file(file: Path, to: Path): def match_file(dir_name: str, cache_dir: Path) -> str: """ - 匹配的原则是，在cache_dir下的文件: (1) 与dir_name完全一致; (2) 除了后缀以外和dir_name完全一致。 + 匹配的原则是: 在cache_dir下的文件与dir_name完全一致, 或除了后缀以外和dir_name完全一致。 如果找到了两个匹配的结果将报错. 如果找到了则返回匹配的文件的名称; 没有找到返回空字符串 :param dir_name: 需要匹配的名称 :param cache_dir: 在该目录下找匹配dir_name是否存在 - :return: str + :return str: 做为匹配结果的字符串 """ files = os.listdir(cache_dir) matched_filenames = []