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

Documentation Status https://github.com/MacHu-GWU/pathlib_mate-project/workflows/CI/badge.svg https://codecov.io/gh/MacHu-GWU/pathlib_mate-project/branch/master/graph/badge.svg https://img.shields.io/pypi/v/pathlib_mate.svg https://img.shields.io/pypi/l/pathlib_mate.svg https://img.shields.io/pypi/pyversions/pathlib_mate.svg https://img.shields.io/pypi/dm/pathlib_mate.svg https://img.shields.io/badge/Release_History!--None.svg?style=social https://img.shields.io/badge/STAR_Me_on_GitHub!--None.svg?style=social
https://img.shields.io/badge/Link-Document-blue.svg https://img.shields.io/badge/Link-API-blue.svg https://img.shields.io/badge/Link-Source_Code-blue.svg https://img.shields.io/badge/Link-Install-blue.svg https://img.shields.io/badge/Link-GitHub-blue.svg https://img.shields.io/badge/Link-Submit_Issue-blue.svg https://img.shields.io/badge/Link-Request_Feature-blue.svg https://img.shields.io/badge/Link-Download-blue.svg

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:

abspath()

>>> p.abspath # Absolute path.
'C:\Users\admin\readme.txt'

dirpath()

>>> p.dirpath # Parent dir full absolute path.
'C:\Users\admin'

dirname()

>>> p.dirname # Parent dir name.
'admin'

basename()

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

fname()

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

ext()

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

size()

>>> p.size # size in bytes
1873

size_in_text()

>>> p.size_in_text # human readable string of the file size
'1.83 KB'

mtime()

>>> p.mtime # Most recent modify time in timestamp. (atime, ctime is similar)
1451624400

modify_datetime()

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

n_file()

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

n_dir()

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

About the Author#

(\ (\
( -.-)o
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#