Release v1.3.2 (What’s new?).
Welcome to pathlib_mate
Documentation#
pathlib is an awesome library handling path in different OS. And it’s been added into standard library since Python3.4. pathlib_mate
gives extensive methods and attributes, makes pathlib
more powerful and user-friendly.
Features:
Convenient Attribute Accessor:
>>> p = Path("/Users/username/test.py").
>>> p.abspath
/Users/username/test.py
>>> p.basename
test.py
>>> p.fname
test
>>> p.ext
.py
>>> p.dirname
username
>>> p.dirpath
/Users/username
>>> p.size
1500
>>> p.size_in_text
1.46 KB
>>> p.create_datetime
datetime(2018, 1, 15, 8, 30, 15)
>>> p.md5
415f12f07a7e01486cc82856621e05bf
>>> p.sha256
d51512cb0ac71484c01c475409a73225d0149165024d7aac6d8e655eedf2c025
>>> p.sha512
7882fc375840cafa364eaf29dc424645b72fcdbe61fc3326c5afd98e70f696e4f390e0e3f159eac2cb60cedc0992ef7b5f8744a4481911e914a7c5b979e6de68
Powerful Path Search:
>>> p = Path("/Users/username/Documents")
>>> for path in p.select_file(recursive=True)
...
>>> for path in p.select_file(recursive=False)
...
>>> for path in p.select_dir(recursive=True)
...
>>> for image_file in p.select_by_ext([".jpg", ".png"])
...
>>> for big_file in p.select_by_size(min_size=1000000)
...
>>> for video_file in p.select_video():
...
# You can customize the filter anyway you want
>>> def py_filter(p): return ".py" == p.ext.lower()
>>> for py_file in p.select_file(py_filter):
...
Eazy to use File / Dir Operation:
>>> p = Path("/Users/username/Documents/Readme.txt")
# mutate
>>> p.change(new_ext=".md")
/Users/username/Documents/Readme.md
>>> p.change(new_fname="Tutorial")
/Users/username/Documents/Tutorial.txt
>>> p.change(new_basename="README.rst")
/Users/username/Documents/README.rst
>>> p.change(new_dirname="Downloads")
/Users/username/Downloads/Readme.txt
>>> p.change(new_dirpath="/User/username/Downloads)
/Users/username/Downloads/Readme.txt
>>> p.change(new_abspath="/Users/username/Downloads/Readme.txt")
/Users/username/Downloads/Readme.txt
# copy
>>> p.moveto(new_ext=".md", makedirs=True)
# cut
>>> p.copyto(new_ext=".md", makedirs=True)
# delete
>>> p.remove()
# delete file or directory recursively, ignore if not exists
>>> p.remove_if_exists()
# make dir and required parents recursively, if not exists
>>> p.mkdir_if_not_exists()
Atomic Write Support:
If anything wrong happens during writing big chunk of data into a file. It may leave you an incomplete file. Atomic write can guarantee either 100% done or nothing happens.
Thanks for boltons project. Now pathlib_mate
supports atomic write API:
>>> p = Path("test.dat")
>>> s = "Hello World"
>>> b = s.encode("utf-8)
>>> p.atomic_write_bytes(b, overwrite=True)
>>> p.atomic_write_text(s, overwrite=True)
>>> with p.atomic_open("wb") as f:
... f.write(b) # write large binary data
Powerful Production Tools:
>>> p = Path("/Users/username/Documents/Github/pathlib_mate-project")
>>> p.print_big_dir_and_big_file()
...
>>> p.file_stat()
{"file": 122, "dir": 41, "size": 619682}
# file statistics, include sub folder
>>> p.file_stat_for_all()
# make an zip archive for the directory, auto naming
>>> p.make_zip_archive()
# make an zip archive for the directory, auto naming
>>> p.backup()
Install#
pathlib_mate
is released on PyPI, so all you need is:
$ pip install pathlib_mate
To upgrade to latest version:
$ pip install --upgrade pathlib_mate
Documentation#
For all pathlib_mate
exclusive features, see AttrAccessor
.
Attribute#
First, let’s use a simple file for demonstration C:\Users\admin\readme.txt
:
>>> from pathlib_mate import Path
>>> p = Path(r"C:\Users\admin\readme.txt")
pathlib_mate
provides a set of very straightforward attribute name:
>>> p.abspath # Absolute path.
'C:\Users\admin\readme.txt'
>>> p.dirpath # Parent dir full absolute path.
'C:\Users\admin'
>>> p.dirname # Parent dir name.
'admin'
>>> p.basename # File name with extension, path is not included.
'readme.txt'
>>> p.fname # File name without extension.
'readme'
>>> p.ext # File extension. If it's a dir, then return empty str.
'.txt'
md5()
>>> p.md5 # md5 check sum of this file (if file exists)
>>> p.size # size in bytes
1873
>>> p.size_in_text # human readable string of the file size
'1.83 KB'
>>> p.mtime # Most recent modify time in timestamp. (atime, ctime is similar)
1451624400
>>> p.modify_datetime # Most recent modify time in datetime.
datetime.datetime(2016, 1, 1, 5, 0) # (access_datetime, create_datetime is similar)
>>> p = Path(r"C:\Users\admin")
C:\Users\admin\
>>> p.n_file # count how many file under this directory
1000
>>> p.n_dir # count how many folders under this directory
10
Method#
Rename / Cut a file: moveto()
The default rename()
method is not good enough. pathlib_mate
provide a new utility method Path.moveto(new_abspath=None, new_dirpath=None, new_dirname=None, new_basename=None, new_fname=None, new_ext=None, makedirs=False)
making rename way more easier.
# You can easily update any parts of the path
# Plus a new Path instance will return
>>> p_new = p.moveto(new_dirpath=r"C:\User\guest")
>>> p_new
'C:\User\guest\readme.txt'
>>> p_new = p.moveto(new_fname=r"introduction")
>>> p_new
'C:\User\guest\introduction.txt'
# This will silently overwrite 'C:\User\guest\introduction.txt'
>>> p_new = p.moveto(new_fname=r"introduction", overwrite=True)
Copy a file: copyto()
In addition, Path.copyto(new_abspath=None, new_dirpath=None, new_dirname=None, new_fname=None, new_basename=None, new_ext=None, overwrite=False, makedirs=False)
works same as Path.moveto()
, but it’s a copy operation. By default, it doesn’t allow overwrite.
Remove a file: remove()
And, you can use Path.remove() to remove the file form your disk, if it is a file.
>>> p.remove()
Remove a file or a dir:
And, you can use Path.remove_if_exists() to remove a file or a directory recursively form your disk. If it is not exists, nothing would happen.
>>> p.remove_if_exists()
Selecting specific files from a directory, sorting the result set, are very common needs. But the glob()
and iterdir()
is not convenient enough. Let’s see how easy it’s done with pathlib_mate
, and it’s super powerful.
Select file and dir: select_file()
, select_dir()
>>> path = Path(r"C:\User\admin")
# This select files recursively in a directory
>>> for p in path.select_file():
...
# This select directories recursively in a directory
>>> for p in path.select_dir():
...
If you don’t want to include the subfolders (non-recursively), set recursive=False
.
>>> for p in path.select_file(recursive=False):
...
Filtering:
You can easily customize the rules you use for filtering. You only need to define a filter function like this:
def filter_image_file(p):
"""This filter returns True only if it is a .jpg and .png file.
"""
return p.ext.lower() in [".jpg", ".png"]
# Filter image file
>>> for p in path.select_file(filter_image_file):
...
Plus, pathlib_mate
provides a set of utility methods for selection (They all support the recursive
keyword):
Path.select_by_ext(ext=[".jpg", ".png"])
: Select file path by extension.Path.select_by_pattern_in_fname(pattern="001")
: Select file path by text pattern in file name.Path.select_by_pattern_in_abspath(pattern="admin")
: Select file path by text pattern in absolute path.Path.select_by_size(min_size=0, max_size=999999999)
: Select file path by size.Path.select_by_mtime(min_time=0, max_time=999999999)
: Select file path by modify time.Path.select_by_atime(min_time=0, max_time=999999999)
: Select file path by access time.Path.select_by_ctime(min_time=0, max_time=999999999)
: Select file path by create time.select_image()
: Select image file.select_audio()
: Select audio file.select_video()
: Select video file.select_word()
: Select compressed archive file.select_excel()
: Select Microsoft Excel file.select_archive()
: Select compressed archive file.
Sort result set
Sort set of path is super easy in pathlib_mate
:
result = path.select_file()
# sort file by its size, from largest to smallest
>>> for p in Path.sort_by_size(result, reverse=True):
...
In addition, you have these options for sorting.
Utility Tools#
file_stat()
: return how many file, directory and totalsize of a direcoty.file_stat_for_all()
: return stat for this directory and all subfolders.print_big_dir()
: Display top-n big directory in a directory.print_big_file()
: Display top-n big file in a directory.print_big_dir_and_big_file()
: Display top-n big dir and big file in a directory.make_zip_archive()
(dst=None)
: Use .gitignore file format to select files except those user defined, and make a zip archive for that directory.backup()
(dst=None, ignore=None, ignore_ext=None, ignore_pattern=None, ignore_size_smaller_than=None, ignore_size_larger_than=None, case_sensitive=False)
: Use .gitignore file format to select files except those user defined, and make a zip archive for that directory.execute_pyfile()
: execute all python file as main script. usually for testing.trail_space()
(filters=lambda p: p.ext == ".py")
: trail all tailing empty space for each line for selected files.autopep8()
: auto reformat all python script in pep8 style.