Welcome to jaraco.path documentation!

Tools for working with files and file systems

class jaraco.path.DirectoryStack(iterable=(), /)

Bases: list

…

DirectoryStack includes a context manager function that can be used to easily perform an operation in a separate directory.

>>> orig_dir = os.getcwd()
>>> stack = DirectoryStack()
>>> with stack.context('/'): context_dir = os.getcwd()
>>> orig_dir == os.getcwd()
True
>>> orig_dir == context_dir
False
>>> len(stack)
0
>>> stack.pushd('/')
>>> len(stack)
1
>>> os.getcwd() == os.path.abspath('/')
True
>>> last_dir = stack.popd()
>>> last_dir == context_dir
True
>>> os.getcwd() == orig_dir
True
context(new_dir)
popd()
pushd(new_dir)
jaraco.path.ExtensionReplacer(new_ext)

A reusable function to replace a file’s extension with another

>>> repl = ExtensionReplacer('.pdf')
>>> repl('myfile.doc')
'myfile.pdf'
>>> repl('myfile.txt')
'myfile.pdf'
>>> repl('myfile')
'myfile.pdf'
class jaraco.path.Recording(loc=pathlib.PurePosixPath(), record=None)

Bases: object

A TreeMaker object that records everything that would be written.

>>> r = Recording()
>>> build({'foo': {'foo1.txt': 'yes'}, 'bar.txt': 'abc'}, r)
>>> r.record
['foo/foo1.txt', 'bar.txt']
mkdir(**kwargs)
write_bytes(content, **kwargs)
write_text(content, **kwargs)

Bases: str

A string indicating the target of a symlink.

class jaraco.path.TreeMaker(*args, **kwargs)

Bases: Protocol

mkdir(*, exist_ok) → object
write_bytes(content, /) → object
write_text(content, /, *, encoding) → object
jaraco.path.build(spec: Mapping[str, str | bytes | Symlink | FilesSpec], prefix: str | TreeMaker = pathlib.Path())

Build a set of files/directories, as described by the spec.

Each key represents a pathname, and the value represents the content. Content may be a nested directory.

>>> spec = {
...     'README.txt': "A README file",
...     "foo": {
...         "__init__.py": "",
...         "bar": {
...             "__init__.py": "",
...         },
...         "baz.py": "# Some code",
...         "bar.py": Symlink("baz.py"),
...     },
...     "bing": Symlink("foo"),
... }
>>> target = getfixture('tmp_path')
>>> build(spec, target)
>>> target.joinpath('foo/baz.py').read_text(encoding='utf-8')
'# Some code'
>>> target.joinpath('bing/bar.py').read_text(encoding='utf-8')
'# Some code'
jaraco.path.create(content: str | bytes | Mapping[str, str | bytes | Symlink | Mapping[str, str | bytes | Symlink | FilesSpec]], path: TreeMaker) → None
jaraco.path.create(content: bytes, path: TreeMaker) → None
jaraco.path.create(content: str, path: TreeMaker) → None
jaraco.path.create(content: Symlink, path: TreeMaker) → None
jaraco.path.encode(name, system='NTFS')

Encode the name for a suitable name in the given filesystem >>> encode(‘Test :1’) ‘Test _1’

jaraco.path.ensure_dir_exists(func)

wrap a function that returns a dir, making sure it exists

jaraco.path.get_time(filename)

Get the modified time for a file as a datetime instance

jaraco.path.get_unique_pathname(path, root='')

Return a pathname possibly with a number appended to it so that it is unique in the directory.

jaraco.path.insert_before_extension(filename, content)

Given a filename and some content, insert the content just before the extension.

>>> insert_before_extension('pages.pdf', '-old')
'pages-old.pdf'
jaraco.path.is_hidden(path) → bool

Check whether a file is presumed hidden, either because the pathname starts with dot or because the platform indicates such.

>>> is_hidden('.')
False
jaraco.path.is_hidden_Darwin(path)
jaraco.path.is_hidden_Windows(path)
jaraco.path.read_chunks(file, chunk_size=2048, update_func=lambda x: ...)

Read file in chunks of size chunk_size (or smaller). If update_func is specified, call it on every chunk with the amount read.

jaraco.path.recursive_glob(root, spec)

Like iglob, but recurse directories

>>> any('path.py' in result for result in recursive_glob('.', '*.py'))
True

>>> all(result.startswith('.') for result in recursive_glob('.', '*.py'))
True

>>> len(list(recursive_glob('.', '*.foo')))
0
jaraco.path.replace_extension(new_ext, filename)
>>> replace_extension('.pdf', 'myfile.doc')
'myfile.pdf'
class jaraco.path.save_to_file(content)

Bases: object

A context manager for saving some content to a file, and then cleaning up the file afterward.

>>> with save_to_file(b'foo') as filename:
...     assert 'foo' == pathlib.Path(filename).read_text(encoding='utf-8')
jaraco.path.set_time(filename, mod_time)

Set the modified time of a file

jaraco.path.splitext_files_only(filepath)

Custom version of splitext that doesn’t perform splitext on directories

jaraco.path.tempfile_context(*args, **kwargs)

A wrapper around tempfile.mkstemp to create the file in a context and delete it after.

Indices and tables