Release v1.3.2 (What’s new?).

Documentation Status!--None.svg?style=social!--None.svg?style=social

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.


Convenient Attribute Accessor:

>>> p = Path("/Users/username/").

>>> p.abspath

>>> p.basename

>>> p.fname

>>> p.ext

>>> p.dirname

>>> p.dirpath

>>> p.size

>>> p.size_in_text
1.46 KB

>>> p.create_datetime
datetime(2018, 1, 15, 8, 30, 15)

>>> p.md5

>>> p.sha256

>>> p.sha512

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")

>>> p.change(new_fname="Tutorial")

>>> p.change(new_basename="README.rst")

>>> p.change(new_dirname="Downloads")

>>> p.change(new_dirpath="/User/username/Downloads)

>>> p.change(new_abspath="/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()


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


For all pathlib_mate exclusive features, see AttrAccessor.


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.


>>> p.dirpath # Parent dir full absolute path.


>>> p.dirname # Parent dir name.


>>> p.basename # File name with extension, path is not included.


>>> p.fname # File name without extension.


>>> p.ext # File extension. If it's a dir, then return empty str.


>>> p.md5 # md5 check sum of this file (if file exists)


>>> p.size # size in bytes


>>> 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)


>>> 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")


>>> p.n_file # count how many file under this directory


>>> p.n_dir # count how many folders under this directory


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

>>> p_new = p.moveto(new_fname=r"introduction")
>>> p_new

# 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):


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.

About the Author#

(\ (\
( -.-)o

Sanhe Hu is a seasoned software engineer with a deep passion for Python development since 2010. As an author and maintainer of 20+ open-source projects, I bring a wealth of experience to the table. As a Senior Solution Architect and Subject Matter Expert in Amazon Web Services, Cloud Engineering, DevOps, Big Data, and Machine Learning, I thrive on helping clients with platform design, enterprise architecture, and strategic roadmaps.

Talk is cheap, show me the code:

API Document#