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.

Issues
  • 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
  • Migrate project to 'path'

    Migrate project to 'path'

    After some time, I've managed to get the name 'path' on PyPI (pypa/warehouse#4123). I'd like to publish this package there (and deprecate this one).

    opened by jaraco 18
  • 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
  • Autogenerated documentation mis-represents

    Autogenerated documentation mis-represents "mode" argument defaults

    In the code, the mode default is 0o777. This is the number 511 in decimal. Here is what the mode default shows in the documentation:

    image

    It just so happens that 511 (in octal) would be a valid (but odd) mode.

    Since the displayed default does not have the 0o prefix, a user unfamiliar with the requirement that the mode be given with the octal prefix to match what they would supply to the chmod tool might get confused and give (for example) makedir(mode=750) which would not do what they expect. (Source: I had a colleague do exactly that based on the representation of the default mode in the documentation).

    I realize this might be more effort than it is worth, but if there was a way to force the documentation to render this in octal it might be clearer, like the Python docs to here:

    image

    enhancement help wanted 
    opened by SethMMorton 2
Releases(v16.3.0)
Owner
Jason R. Coombs
Jason R. Coombs
Search for files under the specified directory. Extract the file name and file path and import them as data.

Search for files under the specified directory. Extract the file name and file path and import them as data. Based on that, search for the file, select it and open it.

G-jon FujiYama 2 Jan 10, 2022
Import Python modules from any file system path

pathimp Import Python modules from any file system path. Installation pip3 install pathimp Usage import pathimp

Danijar Hafner 2 Nov 29, 2021
An object-oriented approach to Python file/directory operations.

Unipath An object-oriented approach to file/directory operations Version: 1.1 Home page: https://github.com/mikeorr/Unipath Docs: https://github.com/m

Mike Orr 499 Dec 22, 2021
gitfs is a FUSE file system that fully integrates with git - Version controlled file system

gitfs is a FUSE file system that fully integrates with git. You can mount a remote repository's branch locally, and any subsequent changes made to the files will be automatically committed to the remote.

Presslabs 2.2k Jan 15, 2022
Swiss army knife for Apple's .tbd file manipulation

Description Inspired by tbdswizzler, this simple python tool for manipulating Apple's .tbd format. Installation python3 -m pip install --user -U pytbd

null 4 Dec 26, 2021
Extract an archive file (zip file or tar file) stored on AWS S3

S3 Extract Extract an archive file (zip file or tar file) stored on AWS S3. Details Downloads archive from S3 into memory, then extract and re-upload

Evan 1 Dec 14, 2021
A python script to convert an ucompressed Gnucash XML file to a text file for Ledger and hledger.

README 1 gnucash2ledger gnucash2ledger is a Python script based on the Github Gist by nonducor (nonducor/gcash2ledger.py). This Python script will tak

Thomas Freeman 1 Dec 29, 2021
This is a file deletion program that asks you for an extension of a file (.mp3, .pdf, .docx, etc.) to delete all of the files in a dir that have that extension.

FileBulk This is a file deletion program that asks you for an extension of a file (.mp3, .pdf, .docx, etc.) to delete all of the files in a dir that h

Enoc Mena 1 Nov 8, 2021
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
Small-File-Explorer - I coded a small file explorer with several options

Petit explorateur de fichier / Small file explorer Pour la première option (création de répertoire) / For the first option (creation of a directory) e

Xerox 1 Jan 3, 2022
Pti-file-format - Reverse engineering the Polyend Tracker instrument file format

pti-file-format Reverse engineering the Polyend Tracker instrument file format.

Jaap Roes 4 Jan 12, 2022
Generates a clean .txt file of contents of a 3 lined csv file

Generates a clean .txt file of contents of a 3 lined csv file. File contents is the .gml file of some function which stores the contents of the csv as a map.

Alex Eckardt 1 Jan 9, 2022
OnedataFS is a PyFilesystem interface to Onedata virtual file system

OnedataFS OnedataFS is a PyFilesystem interface to Onedata virtual file system. As a PyFilesystem concrete class, OnedataFS allows you to work with On

onedata 0 Jan 10, 2022
File support for asyncio

aiofiles: file support for asyncio aiofiles is an Apache2 licensed library, written in Python, for handling local disk files in asyncio applications.

Tin Tvrtković 1.8k Jan 12, 2022
A platform independent file lock for Python

py-filelock This package contains a single module, which implements a platform independent file lock in Python, which provides a simple way of inter-p

Benedikt Schmitt 384 Jan 19, 2022
Simple Python File Manager

This script lets you automatically relocate files based on their extensions. Very useful from the downloads folder !

Aimé Risson 20 Dec 7, 2021
Python function to stream unzip all the files in a ZIP archive: without loading the entire ZIP file or any of its files into memory at once

Python function to stream unzip all the files in a ZIP archive: without loading the entire ZIP file or any of its files into memory at once

Department for International Trade 171 Jan 11, 2022
This is a junk file creator tool which creates junk files in Internal Storage

This is a junk file creator tool which creates junk files in Internal Storage

KiLL3R_xRO 3 Jun 20, 2021
Instant Fuzzy File Search for Alfred

List all the files inside a folder using fd, and instantly fuzzy-search through all of them using fzf, all from inside Alfred with a single keyword: fzf.

Mr. Pennyworth 22 Dec 30, 2021