Documentation Status!--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)

# delte
>>> p.remove()

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

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.

  • sort_by_abspath()
  • sort_by_fname()
  • sort_by_ext()
  • sort_by_size()
  • sort_by_mtime()
  • sort_by_atime()
  • sort_by_ctime()
  • sort_by_md5()

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    I am a lovely Rabbit!

Sanhe Hu is a very active Python Developer Since 2010. Research area includes Machine Learning, Big Data Infrastructure, Business Intelligent, Open Cloud, Distribute System. Love photography, vocal, sports, arts, game, and also the best Python.

API Document