Object-oriented file system path manipulation

Overview
tests Code style: Black https://readthedocs.org/projects/path/badge/?version=latest https://tidelift.com/badges/package/pypi/path

path (aka path pie, formerly path.py) implements path objects as first-class entities, allowing common operations on files to be invoked on those path objects directly. For example:

from path import Path

d = Path("/home/guido/bin")
for f in d.files("*.py"):
    f.chmod(0o755)

# Globbing
for f in d.files("*.py"):
    f.chmod("u+rwx")

# Changing the working directory:
with Path("somewhere"):
    # cwd in now `somewhere`
    ...

# Concatenate paths with /
foo_txt = Path("bar") / "foo.txt"

Path pie is hosted at Github.

Find the documentation here.

Guides and Testimonials

Yasoob wrote the Python 101 Writing a Cleanup Script based on path.

Advantages

Python 3.4 introduced pathlib, which shares many characteristics with path. In particular, it provides an object encapsulation for representing filesystem paths. One may have imagined pathlib would supersede path.

But the implementation and the usage quickly diverge, and path has several advantages over pathlib:

  • path implements Path objects as a subclass of str, and as a result these Path objects may be passed directly to other APIs that expect simple text representations of paths, whereas with pathlib, one must first cast values to strings before passing them to APIs unaware of pathlib. This shortcoming was addressed by PEP 519, in Python 3.6.
  • path goes beyond exposing basic functionality of a path and exposes commonly-used behaviors on a path, providing methods like rmtree (from shlib) and remove_p (remove a file if it exists).
  • As a PyPI-hosted package, path is free to iterate faster than a stdlib package. Contributions are welcome and encouraged.
  • path provides a uniform abstraction over its Path object, freeing the implementer to subclass it readily. One cannot subclass a pathlib.Path to add functionality, but must subclass Path, PosixPath, and WindowsPath, even if one only wishes to add a __dict__ to the subclass instances. path instead allows the Path.module object to be overridden by subclasses, defaulting to the os.path. Even advanced uses of path.Path that subclass the model do not need to be concerned with OS-specific nuances.

Alternatives

In addition to pathlib, the pylib project implements a LocalPath class, which shares some behaviors and interfaces with path.

Development

To install a development version, use the Github links to clone or download a snapshot of the latest code. Alternatively, if you have git installed, you may be able to use pip to install directly from the repository:

pip install git+https://github.com/jaraco/path.git

Testing

Tests are invoked with tox. After having installed tox, simply invoke tox in a checkout of the repo to invoke the tests.

Tests are also run in continuous integration. See the badges above for links to the CI runs.

Releasing

Tagged releases are automatically published to PyPI by Azure Pipelines, assuming the tests pass.

Origins

The path.py project was initially released in 2003 by Jason Orendorff and has been continuously developed and supported by several maintainers over the years.

For Enterprise

Available as part of the Tidelift Subscription.

This project and the maintainers of thousands of other packages are working with Tidelift to deliver one enterprise subscription that covers all of the open source you use.

Learn more.

Security Contact

To report a security vulnerability, please use the Tidelift security contact. Tidelift will coordinate the fix and disclosure.

Comments
  • Fully support surrogate escaping with python 2

    Fully support surrogate escaping with python 2

    Currently there is partial support for the python 3 surrogate escaping when reading names from the file.system which were not encoded in the declared filesystem encoding in python 2. The problem with this support is that it is unable to encode the file names back to the original bytes in order to take any action on said files/directories. This pull aims to fix that, and allow the same support for these 'invalid' file names on python 2 as we currently have for python 3.

    • Bytes round trip from FS -> Path -> FS properly on PY2
    • ~~Path objects instantiated with bytes works~~
    • Add fs_path property to get path compatible with os methods, use internally when calling os functions
    • ~~Add __bytes__ (__str__ on PY2) method to convert to FS bytes (fix #73, although I don't know if there are any cases surrogateescape doesn't handle that will still warn)~~
    opened by gazpachoking 22
  • Add

    Add "config_dir" class method.

    I'd like to add a classmethod, "config_dir":

    @classmethod
    def config_dir(cls, app_name):
        """
        Return a path object referencing a suitable config
        directory for the relevant platform. Honors the
        `XDG Base Directory Specification
        <http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html>`_
        on Unix and App Data conventions on Windows.
        Ensures that directory exists.
        """
    

    Thoughts?

    enhancement 
    opened by jaraco 19
  • Pylint gets confused: No name 'path' in module 'path'

    Pylint gets confused: No name 'path' in module 'path'

    Pylint doesn't understand that path.py defines the name "path". It does so with the @alias decorator, which is only used once in the file. So there are six extra lines of code to define a decorator which only serves to confuse pylint.

    Would you mind getting rid of the decorator and replacing it with path = Path? Then pylint will understand.

    opened by nedbat 18
  • Crash on walk with errors set to warn

    Crash on walk with errors set to warn

    Seems there can be an issue creating the warning text when using the walk method in warn mode. I suspect this might only happen on python 2.

      File "/usr/lib64/python2.7/site-packages/flexget/plugins/filter/exists.py", line 44, in on_task_filter
        for p in folder.walk(errors='warn'):
      File "/usr/lib64/python2.7/site-packages/path.py", line 576, in walk
        TreeWalkWarning)
      File "/usr/lib64/python2.7/warnings.py", line 29, in _show_warning
        file.write(formatwarning(message, category, filename, lineno, line))
      File "/usr/lib64/python2.7/warnings.py", line 38, in formatwarning
        s =  "%s:%s: %s: %s\n" % (filename, lineno, category.__name__, message)
    UnicodeEncodeError: 'ascii' codec can't encode characters in position 46-60: ordinal not in range(128)
    
    wontfix 
    opened by gazpachoking 17
  • Why is not `Path(

    Why is not `Path("test.txt").parent.parent` a valid path?

    Hello.

    I love the concept of path.py, but this is the first time I use it and I am a bit disappointed.

    While working with relative paths, I was wondering why Path("test.txt").parent.parent and Path("test.txt").parent return both "" instead of "../somefolder/" and ".".

    My use case is very simple. The user gives me some string path where I need to create a file. So, I first need to create the folder where the file will be located.

    Path("test.txt").parent.makedirs_p()
    

    This raises a FileNotFoundError because path Path('') does not exist.

    By extension, I notice that parent.parent will unfortunately not return a relative path starting with ...

    I have the feeling that we miss the opportunity for a very useful feature here.

    Do you think this would make sense to implement this?

    opened by Delgan 16
  • Cannot walk path on Linux/Python 2 made of non-unicode/non-fs-decodable bytes

    Cannot walk path on Linux/Python 2 made of non-unicode/non-fs-decodable bytes

    On Linux/Python 2/path.py 10.3.1 I am trying to walkfiles() a path that contains a file name which is raw bytes. The specific of this path is that it is not in the fs.encoding (which is UTF-8) and therefore cannot be decoded to unicode as-is, unless I guess surrogate escape are used or something else.

    With os.walk it works when the top is bytes, but fails if the top is unicode.

    With path.py it fails both when using a bytes or unicode top input. You can see the tests here: https://github.com/nexB/scancode-toolkit/pull/723/files#diff-ada144052a705a1e2fc3c96a033cc425R552

    And the test failures are visible here:

    • https://travis-ci.org/nexB/scancode-toolkit/jobs/264691364#L1786
    • https://travis-ci.org/nexB/scancode-toolkit/jobs/264691364#L1907
    opened by pombredanne 13
  • New maintainer needed

    New maintainer needed

    The time has come for me to step back and limit my involvement in this project. In order to avoid it being abandoned, I'd like to identify a successor to take over maintenance. I'm happy to mentor a new maintainer and contribute incidentally, but a volunteer is needed to maintain the project. I would like to transfer the repository and assign ownership to the path.py project in PyPI. Please express your interest here (preferred) or message me privately if appropriate.

    opened by jaraco 10
  • add ifiles and idirs for case insensitive fnmatching.

    add ifiles and idirs for case insensitive fnmatching.

    first compile regex for fnmatch then apply the match using the case insensitive re flag.

    Honestly.. this may just be a crazy corner case.. I work with satellite imagery and it's nice to be able to match .TIF and .tif and .TiF

    opened by whardier 10
  • path.walkdirs() unicode problem

    path.walkdirs() unicode problem

    Traceback (most recent call last):
      File "./cleanup.py", line 104, in <module>
        for subdir in reversed(list(path(dir).walkdirs())):
      File "/usr/local/lib/python2.7/dist-packages/path.py", line 535, in walkdirs
        dirs = self.dirs()
      File "/usr/local/lib/python2.7/dist-packages/path.py", line 450, in dirs
        return [p for p in self.listdir(pattern) if p.isdir()]
      File "/usr/local/lib/python2.7/dist-packages/path.py", line 437, in listdir
        return [self / child for child in names]
      File "/usr/local/lib/python2.7/dist-packages/path.py", line 201, in __div__
        return self._next_class(self.module.join(self, rel))
      File "/usr/lib/python2.7/posixpath.py", line 69, in join
        path +=  b
      File "/usr/local/lib/python2.7/dist-packages/path.py", line 185, in __add__
        return self._next_class(super(path, self).__add__(more))
    UnicodeDecodeError: 'ascii' codec can't decode byte 0xb0 in position 11: ordinal not in range(128)
    
    opened by franciscolourenco 10
  • pip install fails to find a version to install

    pip install fails to find a version to install

    Py version should not be specified as it's available for py2&3. It causes below pip install error:

    $ pip install path.py
    Collecting path.py
      Could not find a version that satisfies the requirement path.py (from versions: )
    No matching distribution found for path.py
    

    pathpy_bug

    opened by lixxu 9
  • question: why isn't `self` used as `src` for shutil-functions?

    question: why isn't `self` used as `src` for shutil-functions?

    ciao,

    i'm thinking about using the path.py-module in a project.

    but i found it counter-intuitive and less effective in terms of simplifying my code when i stumpled over the fact that an instance isn't used as src-argument for the functions from shutil like copy etc. i wonder if this is intentional.

    if it is not, i would work on patches to achieve that behaviour.

    would you be interested in methods that allow merging filetrees from / to another?

    opened by funkyfuture 9
  • Add method to see the setted permissions

    Add method to see the setted permissions

    With path you can set file permissions with the chmod method, but you can't "get it back" without using the os module.

    Example usage:

    from path import Path
    p = Path('example_file')
    p.chmod(0o777)
    
    do_stuff()
    ...
    
    # how to get the permissions from file p?
    import os
    permission = os.stat(p).st_mode & 0o777 # permissions = 438
    print(f"permissions = {oct(permission)}") # permissions = '0o666'
    
    # possible implementation
    permission = p.st_mode() # permissions = 438
    permission_oct = p.st_mode(oct_str = True) # permission_oct = '0o666'
    

    I think this would be a nice addition to the project.

    opened by Sclafus 1
  • Add stacklevel=2 in deprecation warning

    Add stacklevel=2 in deprecation warning

    Hi,

    Could you add a stacklevel of as least 2 in

    https://github.com/jaraco/path/blob/6debbcecd357c30b080ea19bf2cfa0e2ab0fcd50/path/init.py#L682

    So that the user can know which code call the function. Without a stacklevel of as least 2, it will only show the deprecation warning originating from path/__init__.py.

    opened by char101 0
Releases(v16.6.0)
Owner
Jason R. Coombs
Jason R. Coombs
Find potentially sensitive files

find_files Find potentially sensitive files This script searchs for potentially sensitive files based off of file name or string contained in the file

4 Aug 20, 2022
Simple archive format designed for quickly reading some files without extracting the entire archive

Simple archive format designed for quickly reading some files without extracting the entire archive

Jarred Sumner 336 Dec 30, 2022
A simple library for temporary storage of small files

TemporaryStorage An simple library for temporary storage of small files. Navigation Install Usage In Python console As a standalone application List o

2 Apr 17, 2022
An universal file format tool kit. At present will handle the ico format problem.

An universal file format tool kit. At present will handle the ico format problem.

Sadam·Sadik 1 Dec 26, 2021
🧹 Create symlinks for .m2ts files and classify them into directories in yyyy-mm format.

🧹 Create symlinks for .m2ts files and classify them into directories in yyyy-mm format.

Nep 2 Feb 07, 2022
Extract the windows major and minor build numbers from an ISO file, and automatically sort the iso files.

WindowsBuildFromISO Extract the windows major and minor build numbers from an ISO file, and automatically sort the iso files. Features Parse multiple

Podalirius 9 Nov 09, 2022
Python library for reading and writing tabular data via streams.

tabulator-py A library for reading and writing tabular data (csv/xls/json/etc). [Important Notice] We have released Frictionless Framework. This frame

Frictionless Data 231 Dec 09, 2022
Here is some Python code that allows you to read in SVG files and approximate their paths using a Fourier series.

Here is some Python code that allows you to read in SVG files and approximate their paths using a Fourier series. The Fourier series can be animated and visualized, the function can be output as a tw

Alexander 12 Jan 01, 2023
Python package to read and display segregated file names present in a directory based on type of the file

tpyfilestructure Python package to read and display segregated file names present in a directory based on type of the file. Installation You can insta

Tharun Kumar T 2 Nov 28, 2021
A Python script to backup your favorite Discord gifs

About the project Discord recently felt like it would be a good idea to limit the favorites to 250, which made me lose most of my gifs... Luckily for

4 Aug 03, 2022
Python function to construct a ZIP archive with on the fly - without having to store the entire ZIP in memory or disk

Python function to construct a ZIP archive with on the fly - without having to store the entire ZIP in memory or disk

Department for International Trade 34 Jan 05, 2023
Quick and dirty FAT12 filesystem to ZIP file converter

Quick and Dirty FAT12 Filesystem Converter This is a really crappy Python script I wrote to convert a semi-compatible FAT12 filesystem from my HP150's

Tube Time 2 Feb 12, 2022
A tiny Configuration File Parser for Python Projects

A tiny Configuration File Parser for Python Projects. Currently working on JSON Config Files only.

Tanmoy Sen Gupta 1 Feb 12, 2022
BREP : Binary Search in plaintext and gzip files

BREP : Binary Search in plaintext and gzip files Search large files in O(log n) time using binary search. We support plaintext and Gzipped files. Benc

Arnaud de Saint Meloir 5 Dec 24, 2021
Python Sreamlit Duplicate Records Finder Remover

Python-Sreamlit-Duplicate-Records-Finder-Remover Streamlit is an open-source Python library that makes it easy to create and share beautiful, custom w

RONALD KANYEPI 1 Jan 21, 2022
BOOTH宛先印刷用CSVから色々な便利なリストを作成してCSVで出力するプログラムです。

BOOTH注文リスト作成スクリプト このPythonスクリプトは、BOOTHの「宛名印刷用CSV」から、 未発送の注文 今月の注文 特定期間の注文 を抽出した上で、各注文を商品毎に一覧化したCSVとして出力するスクリプトです。 簡単な使い方 ダウンロード 通常は、Relaseから、booth_ord

hinananoha 1 Nov 28, 2021
Uncompress DEFLATE streams in pure Python

stream-inflate Uncompress DEFLATE streams in pure Python. Installation pip install stream-inflate Usage from stream_inflate import stream_inflate impo

Michal Charemza 7 Oct 13, 2022
Python interface for reading and appending tar files

Python interface for reading and appending tar files, while keeping a fast index for finding and reading files in the archive. This interface has been

Lawrence Livermore National Laboratory 1 Nov 12, 2021
Singer is an open source standard for moving data between databases, web APIs, files, queues, and just about anything else you can think of.

Singer is an open source standard for moving data between databases, web APIs, files, queues, and just about anything else you can think of. Th

Singer 1.1k Jan 05, 2023
Dragon Age: Origins toolset to extract/build .erf files, patch language-specific .dlg files, and view the contents of files in the ERF or GFF format

DAOTools This is a set of tools for Dragon Age: Origins modding. It can patch the text lines of .dlg files, extract and build an .erf file, and view t

8 Dec 06, 2022