fs

file-system utils

Modules:

• promises –

  shellfish.fs.promises

Classes:

• Stdio –

  Standard-io enum object; values are the standard file descriptors

Functions:

• dir_exists_async –

  Return True if the directory exists; False otherwise

• file_exists_async –

  Return True if the file exists; False otherwise

• filesize_async –

  Return the size of the file at the given fspath

• is_dir_async –

  Return True if the given path is a file; False otherwise

• is_file_async –

  Return True if the given path is a file; False otherwise

• is_link_async –

  Return True if the given path is a link; False otherwise

• isdir_async –

  Return True if the given path is a file; False otherwise

• isfile_async –

  Return True if the given path is a file; False otherwise

• islink_async –

  Return True if the given path is a link; False otherwise

• listdir_async –

  Async version of os.listdir

• lstat_async –

  Async version of os.lstat

• read_bytes_async –

  (ASYNC) Load/Read bytes from a fspath

• read_bytes_gen_async –

  Yield (asynchronously) bytes from a given fspath

• read_json_async –

  Load/Read-&-parse json data given a fspath

• read_str_async –

  (ASYNC) Load/Read a string given a fspath

• stat_async –

  Async version of os.stat

• write_bytes_async –

  (ASYNC) Write/Save bytes to a fspath

• write_bytes_gen_async –

  Write/save bytes to a filepath from an (async)iterable/iterator of bytes

• write_json_async –

  Save/Write json-serial-ize-able data to a fspath

• write_str_async –

  (ASYNC) Save/Write a string to fspath

• fspath –

  Alias for os._fspath; returns fspath string for any type of path

• isfile –

  Return True if the given path is a file; False otherwise

• isdir –

  Return True if the given path is a directory; False otherwise

• islink –

  Return True if the given path is a link; False otherwise

• exists –

  Return True if the given path exists; False otherwise

• file_exists –

  Return True if the given path exists; False otherwise; alias for isfile

• dir_exists –

  Return True if the given path exists; False otherwise; alias for isdir

• is_dir –

  Return True if the given path is a directory; alias for isdir

• is_file –

  Return True if the given path is a file; alias for isfile

• is_link –

  Return True if the given path is a link; alias for islink

• safepath –

  Check if a file/dir path is save/unused; returns an unused path.

• filesize –

  Return the size of the given file(path) in bytes

• scandir –

  Typed version of os.scandir

• scandir_list –

  Return a list of os.DirEntry objects

• scandir_gen –

  Return an iterator of os.DirEntry objects

• listdir_gen –

  Return an iterator of strings from DirEntries

• filepath_mtimedelta_sec –

  Return the seconds since the file(path) was last modified

• touch –

  Create an empty file given a fspath

• files_gen –

  Yield file-paths beneath a given dirpath (defaults to os.getcwd())

• dirs_gen –

  Yield directory-paths beneath a dirpath (defaults to os.getcwd())

• files_dirs_gen –

  Return a files_gen() and a dirs_gen() in one swell-foop

• walk_gen –

  Yield all paths beneath a given dirpath (defaults to os.getcwd())

• filepath_gen –

  Yield all filepaths as pathlib.Path objects beneath a dirpath

• dirpath_gen –

  Yield all dirpaths as pathlib.Path objects beneath a dirpath

• path_gen –

  Yield all filepaths as pathlib.Path objects beneath a dirpath

• write_bytes –

  Write/Save bytes to a fspath

• read_bytes –

  Read bytes from a fspath

• file_lines_gen –

  Yield lines from a given fspath

• read_bytes_gen –

  Yield bytes from a given fspath

• write_bytes_gen –

  Write/Save bytes to a fspath

• read_str –

  Load/Read a string given a fspath

• write_str –

  Save/Write a string to fspath

• write_json –

  Save/Write json-serial-ize-able data to a fspath

• read_json –

  Load/Read-&-parse json data given a fspath

• extension –

  Return the extension for a fspath

• sep_split –

  Split a string on the current platform os.path.sep value

• sep_join –

  Join iterable of strings on the current platform os.path.sep value

• sep_strip –

  Strip a string of the current platform's os.path.sep value

• sep_lstrip –

  Left-strip a string of the current platform's os.path.sep value

• sep_rstrip –

  Right-strip a string of the current platform's os.path.sep value

• filecmp –

  Compare 2 files for equality given their filepaths

• shebang –

  Get the shebang string given a fspath; Returns None if no shebang

• chmod –

  Change the access permissions of a file

• mkdir –

  Make directory at given fspath

• mkdirp –

  Make directory and parents

• glob –

  Return an iterator of fspaths matching the given glob pattern

• move –

  Move file(s) like on the command line

• rmfile –

  Remove a file at given fspath

• rmdir –

  Remove directory at given fspath

• rm_gen –

  Remove files & directories in the style of the shell

• rm –

  Remove files & directories in the style of the shell

• stat –

  Return the os.stat_result object for a given fspath

• copy_file –

  Copy a file given a source-path and a destination-path

• cp –

  Copy the directory/file src to the directory/file dest

Stdio

Bases: IntEnum

Standard-io enum object; values are the standard file descriptors

Examples:

>>> from shellfish.stdio import Stdio
>>> Stdio.stdout
<Stdio.stdout: 1>
>>> int(Stdio.stderr)
2

Attributes:

• stdin –

  Standard input (fd 0)

• stdout –

  Standard output (fd 1)

• stderr –

  Standard error (fd 2)

stdin class-attribute instance-attribute

stdin = 0

Standard input (fd 0)

stdout class-attribute instance-attribute

stdout = 1

Standard output (fd 1)

stderr class-attribute instance-attribute

stderr = 2

Standard error (fd 2)

dir_exists_async async

dir_exists_async(fspath: FsPath) -> bool

Return True if the directory exists; False otherwise

file_exists_async async

file_exists_async(fspath: FsPath) -> bool

Return True if the file exists; False otherwise

filesize_async async

filesize_async(fspath: FsPath) -> int

Return the size of the file at the given fspath

Examples:

>>> from asyncio import run as aiorun
>>> from pathlib import Path
>>> from tempfile import TemporaryDirectory
>>> with TemporaryDirectory() as tmpdir:
...     tmpdir = Path(tmpdir)
...     fpath = tmpdir / "test.txt"
...     written = fpath.write_text("hello world")
...     aiorun(filesize_async(fpath))
11

is_dir_async async

is_dir_async(fspath: FsPath) -> bool

Return True if the given path is a file; False otherwise

is_file_async async

is_file_async(fspath: FsPath) -> bool

Return True if the given path is a file; False otherwise

is_link_async async

is_link_async(fspath: FsPath) -> bool

Return True if the given path is a link; False otherwise

isdir_async async

isdir_async(fspath: FsPath) -> bool

Return True if the given path is a file; False otherwise

isfile_async async

isfile_async(fspath: FsPath) -> bool

Return True if the given path is a file; False otherwise

islink_async async

islink_async(fspath: FsPath) -> bool

Return True if the given path is a link; False otherwise

listdir_async async

listdir_async(fspath: FsPath) -> list[str]

Async version of os.listdir

lstat_async async

lstat_async(fspath: FsPath) -> stat_result

Async version of os.lstat

read_bytes_async async

read_bytes_async(filepath: FsPath) -> bytes

(ASYNC) Load/Read bytes from a fspath

Parameters:

• filepath

  (FsPath) –

  fspath read as bytes

Returns:

• bytes –

  bytes from the fspath

Examples:

>>> from shellfish.fs._async import read_bytes_async, write_bytes_async
>>> from asyncio import run as aiorun
>>> fspath = "rbytes_async.doctest.txt"
>>> bites_to_save = b"These are some bytes"
>>> aiorun(write_bytes_async(fspath, bites_to_save))
20
>>> bites_to_save  # they are bytes!
b'These are some bytes'
>>> aiorun(read_bytes_async(fspath))
b'These are some bytes'
>>> import os; os.remove(fspath)

read_bytes_gen_async async

read_bytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[bytes]

Yield (asynchronously) bytes from a given fspath

Parameters:

• filepath

  (FsPath) –

  fspath to read from

• blocksize

  (int, default: 65536 ) –

  size of the block to read

Yields:

• AsyncIterable[bytes] –

  bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import write_bytes_gen_async, read_bytes_gen_async
>>> fspath = 'rbytes_gen_async.doctest.txt'
>>> bites_to_save = (b"These are some bytes... ", b"more bytes!")
>>> bites_to_save
(b'These are some bytes... ', b'more bytes!')
>>> run(write_bytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in read_bytes_gen_async(fspath, blocksize=4):
...         print(b)
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)
>>> async def async_gen():
...     for b in bites_to_save:
...        yield b
>>> run(write_bytes_gen_async(fspath, bites_to_save))
35
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)
>>> class AsyncIterable:
...     def __aiter__(self):
...         return async_gen()
>>> run(write_bytes_gen_async(fspath, AsyncIterable()))
35
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)

read_json_async async

read_json_async(filepath: FsPath) -> Any

Load/Read-&-parse json data given a fspath

Parameters:

• filepath

  (FsPath) –

  Filepath to load/read data from

Returns:

• Any –

  Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import read_json_async, write_json_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(write_json_async(fspath, data))
19
>>> run(read_json_async(fspath))
{'a': 1, 'b': 2, 'c': 3}
>>> import os; os.remove(fspath)

Lists:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> data = list(data.items())
>>> data  # has tuples, but will be saved as strings
[('a', 1), ('b', 2), ('c', 3)]
>>> fspath = "rjson_async_list.doctest.json"
>>> run(write_json_async(fspath, data))
25
>>> run(read_json_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

>>> import os; os.remove(fspath)

read_str_async async

read_str_async(
    filepath: FsPath, encoding: str = "utf-8"
) -> str

(ASYNC) Load/Read a string given a fspath

Parameters:

• filepath

  (FsPath) –

  Filepath for file to read

• encoding

  (str, default: 'utf-8' ) –

  File encoding (Default='utf-8')

Returns:

• str ( str ) –

  String read from given fspath

stat_async async

stat_async(fspath: FsPath) -> stat_result

Async version of os.stat

write_bytes_async async

write_bytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: int | None = None,
) -> int

(ASYNC) Write/Save bytes to a fspath

The parameter 'bites' is used instead of 'bytes' so as to not redefine the built-in python bytes object.

Parameters:

• append

  (bool, default: False ) –

  Append to the fspath if True; otherwise overwrite

• filepath

  (FsPath) –

  fspath to write to

• bites

  (bytes) –

  Bytes to be written

• chmod

  (int | None, default: None ) –

  chmod the fspath to this mode after writing

Returns:

• int –

  None

Examples:

>>> from shellfish.fs._async import read_bytes_async, write_bytes_async
>>> from asyncio import run as aiorun
>>> fspath = "wbytes_async.doctest.txt"
>>> bites_to_save = b"These are some bytes"
>>> aiorun(write_bytes_async(fspath, bites_to_save))
20
>>> bites_to_save  # they are bytes!
b'These are some bytes'
>>> aiorun(read_bytes_async(fspath))
b'These are some bytes'
>>> import os; os.remove(fspath)

write_bytes_gen_async async

write_bytes_gen_async(
    filepath: FsPath,
    bytes_gen: Iterable[bytes] | AsyncIterable[bytes],
    *,
    append: bool = False,
    chmod: int | None = None,
) -> int

Write/save bytes to a filepath from an (async)iterable/iterator of bytes

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• bytes_gen

  (Iterable[bytes] | AsyncIterable[bytes]) –

  AsyncIterable/Iterator of bytes to write

• append

  (bool, default: False ) –

  Append to the fspath if True; otherwise overwrite

• chmod

  (int | None, default: None ) –

  chmod the fspath if not None

Returns:

• int ( int ) –

  number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import write_bytes_gen_async, read_bytes_gen_async
>>> fspath = 'wbytes_gen_async.doctest.txt'
>>> bites_to_save = (b"These are some bytes... ", b"more bytes!")
>>> bites_to_save
(b'These are some bytes... ', b'more bytes!')
>>> run(write_bytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in read_bytes_gen_async(fspath, blocksize=4):
...         print(b)
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)
>>> async def async_gen():
...     for b in bites_to_save:
...        yield b
>>> run(write_bytes_gen_async(fspath, bites_to_save))
35
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)
>>> class AsyncIterable:
...     def __aiter__(self):
...         return async_gen()
>>> run(write_bytes_gen_async(fspath, AsyncIterable()))
35
>>> run(read())
b'Thes'
b'e ar'
b'e so'
b'me b'
b'ytes'
b'... '
b'more'
b' byt'
b'es!'
>>> remove(fspath)

write_json_async async

write_json_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Callable[[Any], Any] | None = None,
    append: bool = False,
    chmod: int | None = None,
    **kwargs: Any,
) -> int

Save/Write json-serial-ize-able data to a fspath

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• data

  (Any) –

  json-serial-ize-able data

• fmt

  (bool, default: False ) –

  Indented (2 spaces) or minify data (default=False)

• pretty

  (bool, default: False ) –

  Indented (2 spaces) or minify data (default=False)

• sort_keys

  (bool, default: False ) –

  Sort the data keys if the data is a dictionary.

• append_newline

  (bool, default: False ) –

  Sort the data keys if the data is a dictionary.

• default

  (Callable[[Any], Any] | None, default: None ) –

  default function hook

• append

  (bool, default: False ) –

  Append to the fspath if True; default is False

• chmod

  (Optional[int], default: None ) –

  chmod the fspath if not None

• **kwargs

  (Any, default: {} ) –

  Additional keyword arguments to pass to jsonbourne.JSON.dump

Returns:

• int ( int ) –

  Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import read_json_async, write_json_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(write_json_async(fspath, data))
19
>>> run(read_json_async(fspath))
{'a': 1, 'b': 2, 'c': 3}
>>> import os; os.remove(fspath)

Lists:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> data = list(data.items())
>>> data  # has tuples, but will be saved as strings
[('a', 1), ('b', 2), ('c', 3)]
>>> fspath = "wjson_async_list.doctest.json"
>>> run(write_json_async(fspath, data))
25
>>> run(read_json_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

>>> import os; os.remove(fspath)

write_str_async async

write_str_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: int | None = None,
) -> int

(ASYNC) Save/Write a string to fspath

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• string

  (str) –

  string to be written

• encoding

  (str, default: 'utf-8' ) –

  File encoding (Default='utf-8')

• append

  (bool, default: False ) –

  Append to the fspath if True; default is False

• chmod

  (Optional[int], default: None ) –

  chmod the fspath if not None

Returns:

• int ( int ) –

  number of bytes written

fspath

fspath(fspath: FsPath) -> str

Alias for os._fspath; returns fspath string for any type of path

isfile

isfile(fspath: FsPath) -> bool

Return True if the given path is a file; False otherwise

isdir

isdir(fspath: FsPath) -> bool

Return True if the given path is a directory; False otherwise

islink

islink(fspath: FsPath) -> bool

Return True if the given path is a link; False otherwise

exists

exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

file_exists

file_exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise; alias for isfile

dir_exists

dir_exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise; alias for isdir

is_dir

is_dir(fspath: FsPath) -> bool

Return True if the given path is a directory; alias for isdir

is_file

is_file(fspath: FsPath) -> bool

Return True if the given path is a file; alias for isfile

is_link

is_link(fspath: FsPath) -> bool

Return True if the given path is a link; alias for islink

safepath

safepath(fspath: FsPath) -> str

Check if a file/dir path is save/unused; returns an unused path.

Parameters:

• fspath

  (FsPath) –

  file-system path; file or directory path string or Path obj

Returns:

• str ( str ) –

  file/dir path that does not exist and contains the given path

filesize

filesize(fspath: FsPath) -> int

Return the size of the given file(path) in bytes

Parameters:

• fspath

  (FsPath) –

  Filepath as a string or pathlib.Path object

Returns:

• int ( int ) –

  size of the fspath in bytes

scandir

scandir(
    dirpath: FsPath = ".",
) -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

scandir_list

scandir_list(
    dirpath: FsPath = ".",
) -> list[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

• dirpath

  (FsPath, default: '.' ) –

  Dirpath to scan

Returns:

• list[DirEntry[AnyStr]] –

  list[DirEntry]: List of os.DirEntry objects

scandir_gen

scandir_gen(
    fspath: FsPath = ".",
    *,
    recursive: bool = False,
    follow_symlinks: bool = True,
    files: bool = True,
    dirs: bool = True,
    symlinks: bool = True,
    files_only: bool = False,
    dirs_only: bool = False,
    symlinks_only: bool = False,
) -> Iterator[DirEntry[str]]

Return an iterator of os.DirEntry objects

Parameters:

• fspath

  (FsPath, default: '.' ) –

  (FsPath): dirpath to look through

• recursive

  (bool, default: False ) –

  recursively scan the directory

• follow_symlinks

  (bool, default: True ) –

  follow symlinks when checking for dirs and files

• files

  (bool, default: True ) –

  include files

• dirs

  (bool, default: True ) –

  include directories

• symlinks

  (bool, default: True ) –

  include symlinks

• dirs_only

  (bool, default: False ) –

  only include directories

• files_only

  (bool, default: False ) –

  only include files

• symlinks_only

  (bool, default: False ) –

  only include symlinks

Returns:

• Iterator[DirEntry[str]] –

  Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

• ValueError –

  if any of the kwargs (dirs, files and symlinks) are not True

listdir_gen

listdir_gen(
    fspath: FsPath = ".",
    *,
    abspath: bool = False,
    follow_symlinks: bool = True,
    files: bool = True,
    dirs: bool = True,
    symlinks: bool = False,
    files_only: bool = False,
    dirs_only: bool = False,
    symlinks_only: bool = False,
) -> Iterator[Path]

Return an iterator of strings from DirEntries

Examples:

>>> tmpdir = 'listdir_gen.doctest'
>>> from shellfish import sh
>>> from os import makedirs, path, chdir
>>> from shutil import rmtree
>>> _makedirs(tmpdir, exist_ok=True)
>>> pwd = sh.pwd()
>>> sh.cd(tmpdir)
>>> filepath_parts = [
...     ("dir", "file1.txt"),
...     ("dir", "file2.txt"),
...     ("dir", "file3.txt"),
...     ("dir", "data1.json"),
...     ("dir", "dir2", "file1.txt"),
...     ("dir", "dir2", "file2.txt"),
...     ("dir", "dir2", "file3.txt"),
...     ("dir", "dir2a", "file1.txt"),
...     ("dir", "dir2a", "file2.txt"),
...     ("dir", "dir2a", "file3.txt"),
... ]
>>> from shellfish.fs import touch
>>> expected_files = []
>>> for f in filepath_parts:
...     fspath = path.join(*f)
...     fspath = path.join(tmpdir, fspath)
...     dirpath = path.dirname(fspath)
...     expected_files.append(fspath)
...     _makedirs(dirpath, exist_ok=True)
...     touch(fspath)
>>> dirpath = path.join(tmpdir, 'dir')
>>> dirpath.replace("\\", "/")
'listdir_gen.doctest/dir'
>>> sorted(listdir_gen(dirpath, dirs=False, symlinks=False))
['data1.json', 'file1.txt', 'file2.txt', 'file3.txt']
>>> abspaths = sorted(listdir_gen(dirpath, abspath=True, dirs=False, symlinks=False))
>>> for abspath in [p.replace("\\", "/") for p in abspaths]:
...    print(abspath)
listdir_gen.doctest/dir/data1.json
listdir_gen.doctest/dir/file1.txt
listdir_gen.doctest/dir/file2.txt
listdir_gen.doctest/dir/file3.txt
>>> sh.cd(pwd)
>>> import os
>>> if path.exists(tmpdir):
...     rmtree(tmpdir)
>>> path.isdir(tmpdir)
False

filepath_mtimedelta_sec

filepath_mtimedelta_sec(filepath: FsPath) -> float

Return the seconds since the file(path) was last modified

touch

touch(fspath: FsPath, *, mkdirp: bool = True) -> None

Create an empty file given a fspath

Parameters:

• fspath

  (FsPath) –

  File-system path for where to make an empty file

• mkdirp

  (bool, default: True ) –

  Make parent directories if they don't exist

files_gen

files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]

Yield file-paths beneath a given dirpath (defaults to os.getcwd())

Parameters:

• dirpath

  (FsPath, default: '.' ) –

  Directory path to walk down/through.

• abspath

  (bool, default: True ) –

  Yield the absolute path

• onerror

  (Callable[[OSError], Any] | None, default: None ) –

  Function called on OSError

• topdown

  (bool, default: True ) –

  Not applicable

• followlinks

  (bool, default: False ) –

  Follow links

• check

  (bool, default: True ) –

  Check that dir exists

Returns:

• Iterator[str] –

  Generator object that yields file-paths (absolute or relative)

Examples:

>>> tmpdir = 'files_gen.doctest'
>>> from os import makedirs; _makedirs(tmpdir, exist_ok=True)
>>> filepath_parts = [
...     ("dir", "file1.txt"),
...     ("dir", "file2.txt"),
...     ("dir", "file3.txt"),
...     ("dir", "dir2", "file1.txt"),
...     ("dir", "dir2", "file2.txt"),
...     ("dir", "dir2", "file3.txt"),
...     ("dir", "dir2a", "file1.txt"),
...     ("dir", "dir2a", "file2.txt"),
...     ("dir", "dir2a", "file3.txt"),
... ]
>>> from shellfish.fs import touch
>>> expected_files = []
>>> for f in filepath_parts:
...     fspath = path.join(*f)
...     fspath = path.join(tmpdir, fspath)
...     dirpath = path.dirname(fspath)
...     expected_files.append(fspath)
...     _makedirs(dirpath, exist_ok=True)
...     touch(fspath)
>>> from pprint import pprint
>>> expected_files = [el.replace('\\', '/') for el in expected_files]
>>> pprint(expected_files)
['files_gen.doctest/dir/file1.txt',
 'files_gen.doctest/dir/file2.txt',
 'files_gen.doctest/dir/file3.txt',
 'files_gen.doctest/dir/dir2/file1.txt',
 'files_gen.doctest/dir/dir2/file2.txt',
 'files_gen.doctest/dir/dir2/file3.txt',
 'files_gen.doctest/dir/dir2a/file1.txt',
 'files_gen.doctest/dir/dir2a/file2.txt',
 'files_gen.doctest/dir/dir2a/file3.txt']
>>> files_list = list(sorted(set(files_gen(tmpdir))))
>>> files_list = [el.replace('\\', '/') for el in files_list]
>>> pprint(files_list)
['files_gen.doctest/dir/dir2/file1.txt',
 'files_gen.doctest/dir/dir2/file2.txt',
 'files_gen.doctest/dir/dir2/file3.txt',
 'files_gen.doctest/dir/dir2a/file1.txt',
 'files_gen.doctest/dir/dir2a/file2.txt',
 'files_gen.doctest/dir/dir2a/file3.txt',
 'files_gen.doctest/dir/file1.txt',
 'files_gen.doctest/dir/file2.txt',
 'files_gen.doctest/dir/file3.txt']
>>> pprint(list(sorted(set(expected_files))))
['files_gen.doctest/dir/dir2/file1.txt',
 'files_gen.doctest/dir/dir2/file2.txt',
 'files_gen.doctest/dir/dir2/file3.txt',
 'files_gen.doctest/dir/dir2a/file1.txt',
 'files_gen.doctest/dir/dir2a/file2.txt',
 'files_gen.doctest/dir/dir2a/file3.txt',
 'files_gen.doctest/dir/file1.txt',
 'files_gen.doctest/dir/file2.txt',
 'files_gen.doctest/dir/file3.txt']
>>> list(sorted(set(files_list))) == list(sorted(set(expected_files)))
True
>>> from shutil import rmtree
>>> rmtree(tmpdir)

dirs_gen

dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]

Yield directory-paths beneath a dirpath (defaults to os.getcwd())

Parameters:

• dirpath

  (FsPath, default: '.' ) –

  Directory path to walk down/through.

• abspath

  (bool, default: True ) –

  Yield the absolute path

• onerror

  (Callable[[OSError], Any] | None, default: None ) –

  Function called on OSError

• topdown

  (bool, default: True ) –

  Not applicable

• followlinks

  (bool, default: False ) –

  Follow links

• check

  (bool, default: True ) –

  Check that dir exists

Returns:

• Iterator[str] –

  Generator object that yields directory paths (absolute or relative)

Examples:

>>> tmpdir = 'dirs_gen.doctest'
>>> from os import makedirs; _makedirs(tmpdir, exist_ok=True)
>>> filepath_parts = [
...     ("dir", "file1.txt"),
...     ("dir", "file2.txt"),
...     ("dir", "file3.txt"),
...     ("dir", "dir2", "file1.txt"),
...     ("dir", "dir2", "file2.txt"),
...     ("dir", "dir2", "file3.txt"),
...     ("dir", "dir2a", "file1.txt"),
...     ("dir", "dir2a", "file2.txt"),
...     ("dir", "dir2a", "file3.txt"),
... ]
>>> from shellfish.fs import touch
>>> expected_dirs = []
>>> expected_files = []
>>> for f in filepath_parts:
...     fspath = path.join(*f)
...     fspath = path.join(tmpdir, fspath)
...     dirpath = path.dirname(fspath)
...     expected_files.append(fspath)
...     expected_dirs.append(dirpath)
...     _makedirs(dirpath, exist_ok=True)
...     touch(fspath)
>>> expected_dirs = list(sorted(set(expected_dirs)))
>>> from pprint import pprint
>>> expected_files = [el.replace('\\', '/') for el in expected_files]
>>> pprint(expected_files)
['dirs_gen.doctest/dir/file1.txt',
 'dirs_gen.doctest/dir/file2.txt',
 'dirs_gen.doctest/dir/file3.txt',
 'dirs_gen.doctest/dir/dir2/file1.txt',
 'dirs_gen.doctest/dir/dir2/file2.txt',
 'dirs_gen.doctest/dir/dir2/file3.txt',
 'dirs_gen.doctest/dir/dir2a/file1.txt',
 'dirs_gen.doctest/dir/dir2a/file2.txt',
 'dirs_gen.doctest/dir/dir2a/file3.txt']
>>> expected_dirs = [el.replace('\\', '/') for el in expected_dirs]
>>> pprint(expected_dirs)
['dirs_gen.doctest/dir',
 'dirs_gen.doctest/dir/dir2',
 'dirs_gen.doctest/dir/dir2a']
>>> _files = list(files_gen(tmpdir))
>>> _dirs = list(dirs_gen(tmpdir))
>>> files_n_dirs_list = list(sorted(_files + _dirs))
>>> files_n_dirs_list = [el.replace('\\', '/') for el in files_n_dirs_list]
>>> pprint(files_n_dirs_list)
['dirs_gen.doctest',
 'dirs_gen.doctest/dir',
 'dirs_gen.doctest/dir/dir2',
 'dirs_gen.doctest/dir/dir2/file1.txt',
 'dirs_gen.doctest/dir/dir2/file2.txt',
 'dirs_gen.doctest/dir/dir2/file3.txt',
 'dirs_gen.doctest/dir/dir2a',
 'dirs_gen.doctest/dir/dir2a/file1.txt',
 'dirs_gen.doctest/dir/dir2a/file2.txt',
 'dirs_gen.doctest/dir/dir2a/file3.txt',
 'dirs_gen.doctest/dir/file1.txt',
 'dirs_gen.doctest/dir/file2.txt',
 'dirs_gen.doctest/dir/file3.txt']
>>> expected = sorted(set(expected_files + expected_dirs + [tmpdir]))
>>> expected = [el.replace('\\', '/') for el in expected]
>>> pprint(expected)
['dirs_gen.doctest',
 'dirs_gen.doctest/dir',
 'dirs_gen.doctest/dir/dir2',
 'dirs_gen.doctest/dir/dir2/file1.txt',
 'dirs_gen.doctest/dir/dir2/file2.txt',
 'dirs_gen.doctest/dir/dir2/file3.txt',
 'dirs_gen.doctest/dir/dir2a',
 'dirs_gen.doctest/dir/dir2a/file1.txt',
 'dirs_gen.doctest/dir/dir2a/file2.txt',
 'dirs_gen.doctest/dir/dir2a/file3.txt',
 'dirs_gen.doctest/dir/file1.txt',
 'dirs_gen.doctest/dir/file2.txt',
 'dirs_gen.doctest/dir/file3.txt']
>>> files_n_dirs_list == expected
True
>>> from shutil import rmtree
>>> rmtree(tmpdir)

files_dirs_gen

files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> tuple[Iterator[str], Iterator[str]]

Return a files_gen() and a dirs_gen() in one swell-foop

Parameters:

• dirpath

  (FsPath, default: '.' ) –

  Directory path to walk down/through.

• abspath

  (bool, default: True ) –

  Yield the absolute path

• onerror

  (Callable[[OSError], Any] | None, default: None ) –

  Function called on OSError

• topdown

  (bool, default: True ) –

  Not applicable

• followlinks

  (bool, default: False ) –

  Follow links

• check

  (bool, default: True ) –

  Check if dirpath is a directory

Returns:

• tuple[Iterator[str], Iterator[str]] –

  A tuple of two generators (files_gen(), dirs_gen())

Examples:

>>> tmpdir = 'files_dirs_gen.doctest'
>>> from os import makedirs; _makedirs(tmpdir, exist_ok=True)
>>> filepath_parts = [
...     ("dir", "file1.txt"),
...     ("dir", "file2.txt"),
...     ("dir", "file3.txt"),
...     ("dir", "dir2", "file1.txt"),
...     ("dir", "dir2", "file2.txt"),
...     ("dir", "dir2", "file3.txt"),
...     ("dir", "dir2a", "file1.txt"),
...     ("dir", "dir2a", "file2.txt"),
...     ("dir", "dir2a", "file3.txt"),
... ]
>>> from shellfish.fs import touch
>>> expected_dirs = []
>>> expected_files = []
>>> for f in filepath_parts:
...     fspath = path.join(*f)
...     fspath = path.join(tmpdir, fspath)
...     dirpath = path.dirname(fspath)
...     expected_files.append(fspath)
...     expected_dirs.append(dirpath)
...     _makedirs(dirpath, exist_ok=True)
...     touch(fspath)
>>> expected_dirs = list(sorted(set(expected_dirs)))
>>> from pprint import pprint
>>> expected_files = [el.replace('\\', '/') for el in expected_files]
>>> pprint(expected_files)
['files_dirs_gen.doctest/dir/file1.txt',
 'files_dirs_gen.doctest/dir/file2.txt',
 'files_dirs_gen.doctest/dir/file3.txt',
 'files_dirs_gen.doctest/dir/dir2/file1.txt',
 'files_dirs_gen.doctest/dir/dir2/file2.txt',
 'files_dirs_gen.doctest/dir/dir2/file3.txt',
 'files_dirs_gen.doctest/dir/dir2a/file1.txt',
 'files_dirs_gen.doctest/dir/dir2a/file2.txt',
 'files_dirs_gen.doctest/dir/dir2a/file3.txt']
>>> expected_dirs = [el.replace('\\', '/') for el in expected_dirs]
>>> pprint(expected_dirs)
['files_dirs_gen.doctest/dir',
 'files_dirs_gen.doctest/dir/dir2',
 'files_dirs_gen.doctest/dir/dir2a']
>>> _files, _dirs = files_dirs_gen(tmpdir)
>>> _files = list(_files)
>>> _dirs = list(_dirs)
>>> files_n_dirs_list = list(sorted(set(_files + _dirs)))
>>> files_n_dirs_list = [el.replace('\\', '/') for el in files_n_dirs_list]
>>> pprint(files_n_dirs_list)
['files_dirs_gen.doctest',
 'files_dirs_gen.doctest/dir',
 'files_dirs_gen.doctest/dir/dir2',
 'files_dirs_gen.doctest/dir/dir2/file1.txt',
 'files_dirs_gen.doctest/dir/dir2/file2.txt',
 'files_dirs_gen.doctest/dir/dir2/file3.txt',
 'files_dirs_gen.doctest/dir/dir2a',
 'files_dirs_gen.doctest/dir/dir2a/file1.txt',
 'files_dirs_gen.doctest/dir/dir2a/file2.txt',
 'files_dirs_gen.doctest/dir/dir2a/file3.txt',
 'files_dirs_gen.doctest/dir/file1.txt',
 'files_dirs_gen.doctest/dir/file2.txt',
 'files_dirs_gen.doctest/dir/file3.txt']
>>> expected = sorted(set(expected_files + expected_dirs + [tmpdir]))
>>> expected = [el.replace('\\', '/') for el in expected]
>>> pprint(expected)
['files_dirs_gen.doctest',
 'files_dirs_gen.doctest/dir',
 'files_dirs_gen.doctest/dir/dir2',
 'files_dirs_gen.doctest/dir/dir2/file1.txt',
 'files_dirs_gen.doctest/dir/dir2/file2.txt',
 'files_dirs_gen.doctest/dir/dir2/file3.txt',
 'files_dirs_gen.doctest/dir/dir2a',
 'files_dirs_gen.doctest/dir/dir2a/file1.txt',
 'files_dirs_gen.doctest/dir/dir2a/file2.txt',
 'files_dirs_gen.doctest/dir/dir2a/file3.txt',
 'files_dirs_gen.doctest/dir/file1.txt',
 'files_dirs_gen.doctest/dir/file2.txt',
 'files_dirs_gen.doctest/dir/file3.txt']
>>> files_n_dirs_list == expected
True
>>> from shutil import rmtree
>>> rmtree(tmpdir)

walk_gen

walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]

Yield all paths beneath a given dirpath (defaults to os.getcwd())

Parameters:

• dirpath

  (FsPath, default: '.' ) –

  Directory path to walk down/through.

• abspath

  (bool, default: True ) –

  Yield the absolute path

• onerror

  (Callable[[OSError], Any] | None, default: None ) –

  Function called on OSError

• topdown

  (bool, default: True ) –

  Not applicable

• followlinks

  (bool, default: False ) –

  Follow links

• check

  (bool, default: True ) –

  Check if dirpath exists

Returns:

• Iterator[str] –

  Generator object that yields directory paths (absolute or relative)

Examples:

>>> tmpdir = 'walk_gen.doctest'
>>> from os import makedirs; _makedirs(tmpdir, exist_ok=True)
>>> filepath_parts = [
...     ("dir", "file1.txt"),
...     ("dir", "file2.txt"),
...     ("dir", "file3.txt"),
...     ("dir", "dir2", "file1.txt"),
...     ("dir", "dir2", "file2.txt"),
...     ("dir", "dir2", "file3.txt"),
...     ("dir", "dir2a", "file1.txt"),
...     ("dir", "dir2a", "file2.txt"),
...     ("dir", "dir2a", "file3.txt"),
... ]
>>> from shellfish.fs import touch
>>> expected_dirs = []
>>> expected_files = []
>>> for f in filepath_parts:
...     fspath = path.join(*f).replace('\\', '/')
...     fspath = path.join(tmpdir, fspath).replace('\\', '/')
...     dirpath = path.dirname(fspath)
...     expected_files.append(fspath)
...     expected_dirs.append(dirpath)
...     _makedirs(dirpath, exist_ok=True)
...     touch(fspath)
>>> expected_dirs = [el.replace('\\', '/') for el in sorted(set(expected_dirs))]
>>> from pprint import pprint
>>> pprint(expected_files)
['walk_gen.doctest/dir/file1.txt',
 'walk_gen.doctest/dir/file2.txt',
 'walk_gen.doctest/dir/file3.txt',
 'walk_gen.doctest/dir/dir2/file1.txt',
 'walk_gen.doctest/dir/dir2/file2.txt',
 'walk_gen.doctest/dir/dir2/file3.txt',
 'walk_gen.doctest/dir/dir2a/file1.txt',
 'walk_gen.doctest/dir/dir2a/file2.txt',
 'walk_gen.doctest/dir/dir2a/file3.txt']
>>> pprint(expected_dirs)
['walk_gen.doctest/dir',
 'walk_gen.doctest/dir/dir2',
 'walk_gen.doctest/dir/dir2a']
>>> walk_gen_list = list(sorted(walk_gen(tmpdir)))
>>> walk_gen_list = [el.replace('\\', '/') for el in walk_gen_list]
>>> pprint(walk_gen_list)
['walk_gen.doctest',
 'walk_gen.doctest/dir',
 'walk_gen.doctest/dir/dir2',
 'walk_gen.doctest/dir/dir2/file1.txt',
 'walk_gen.doctest/dir/dir2/file2.txt',
 'walk_gen.doctest/dir/dir2/file3.txt',
 'walk_gen.doctest/dir/dir2a',
 'walk_gen.doctest/dir/dir2a/file1.txt',
 'walk_gen.doctest/dir/dir2a/file2.txt',
 'walk_gen.doctest/dir/dir2a/file3.txt',
 'walk_gen.doctest/dir/file1.txt',
 'walk_gen.doctest/dir/file2.txt',
 'walk_gen.doctest/dir/file3.txt']
>>> expected = sorted(set(expected_files + expected_dirs + [tmpdir]))
>>> pprint(expected)
['walk_gen.doctest',
 'walk_gen.doctest/dir',
 'walk_gen.doctest/dir/dir2',
 'walk_gen.doctest/dir/dir2/file1.txt',
 'walk_gen.doctest/dir/dir2/file2.txt',
 'walk_gen.doctest/dir/dir2/file3.txt',
 'walk_gen.doctest/dir/dir2a',
 'walk_gen.doctest/dir/dir2a/file1.txt',
 'walk_gen.doctest/dir/dir2a/file2.txt',
 'walk_gen.doctest/dir/dir2a/file3.txt',
 'walk_gen.doctest/dir/file1.txt',
 'walk_gen.doctest/dir/file2.txt',
 'walk_gen.doctest/dir/file3.txt']
>>> walk_gen_list == expected
True
>>> from shutil import rmtree
>>> rmtree(tmpdir)

filepath_gen

filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]

Yield all filepaths as pathlib.Path objects beneath a dirpath

dirpath_gen

dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]

Yield all dirpaths as pathlib.Path objects beneath a dirpath

path_gen

path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Callable[[OSError], Any] | None = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]

Yield all filepaths as pathlib.Path objects beneath a dirpath

write_bytes

write_bytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: int | None = None,
) -> int

Write/Save bytes to a fspath

The parameter 'bites' is used instead of 'bytes' to not redefine the built-in python bytes object.

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• bites

  (bytes) –

  Bytes to be written

• append

  (bool, default: False ) –

  Append to the file if True, overwrite otherwise; default is False

• chmod

  (Optional[int], default: None ) –

  chmod the file after writing; default is None

Returns:

• int ( int ) –

  Number of bytes written

Examples:

>>> from shellfish.fs import read_bytes, write_bytes
>>> fspath = "wbytes.doctest.txt"
>>> bites_to_save = b"These are some bytes"
>>> bites_to_save  # they are bytes!
b'These are some bytes'
>>> write_bytes(fspath, bites_to_save)
20
>>> read_bytes(fspath)
b'These are some bytes'
>>> import os; os.remove(fspath)

read_bytes

read_bytes(filepath: FsPath) -> bytes

Read bytes from a fspath

Parameters:

• filepath

  (FsPath) –

  fspath read as bytes

Returns:

• bytes –

  bytes from the fspath

Examples:

>>> from shellfish.fs import read_bytes, write_bytes
>>> fspath = "rbytes.doctest.txt"
>>> bites_to_save = b"These are some bytes"
>>> write_bytes(fspath, bites_to_save)
20
>>> bites_to_save  # they are bytes!
b'These are some bytes'
>>> read_bytes(fspath)
b'These are some bytes'
>>> import os; os.remove(fspath)

file_lines_gen

file_lines_gen(
    filepath: FsPath, *, keepends: bool = True
) -> Iterable[str]

Yield lines from a given fspath

Parameters:

• filepath

  (FsPath) –

  File to yield lines from

• keepends

  (bool, default: True ) –

  Flag to keep the ends of the file lines

Yields:

• Iterable[str] –

  Lines from the given fspath

Examples:

>>> string = '\n'.join(str(i) for i in range(1, 10))
>>> string
'1\n2\n3\n4\n5\n6\n7\n8\n9'
>>> fspath = "file_lines_gen.doctest.txt"
>>> from shellfish.fs import write_str
>>> write_str(fspath, string)
17
>>> for file_line in file_lines_gen(fspath):
...     file_line
'1\n'
'2\n'
'3\n'
'4\n'
'5\n'
'6\n'
'7\n'
'8\n'
'9'
>>> for file_line in file_lines_gen(fspath, keepends=False):
...     file_line
'1'
'2'
'3'
'4'
'5'
'6'
'7'
'8'
'9'
>>> import os; os.remove(fspath)

read_bytes_gen

read_bytes_gen(
    filepath: FsPath, blocksize: int = 65536
) -> Iterable[bytes]

Yield bytes from a given fspath

write_bytes_gen

write_bytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    *,
    append: bool = False,
    chmod: int | None = None,
) -> int

Write/Save bytes to a fspath

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• bytes_gen

  (Iterable[bytes]) –

  Bytes to be written

• append

  (bool, default: False ) –

  Append to the file if True, overwrite otherwise; default is False

• chmod

  (Optional[int], default: None ) –

  chmod the file after writing; default is None

Returns:

• int ( int ) –

  Number of bytes written

Examples:

>>> from shellfish.fs import read_bytes, write_bytes
>>> fspath = "wbytes_gen.doctest.txt"
>>> bites_to_save = (b"These are some bytes... ", b"more bytes!")
>>> bites_to_save  # they are bytes!
(b'These are some bytes... ', b'more bytes!')
>>> write_bytes_gen(fspath, (b for b in bites_to_save))
35
>>> read_bytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

read_str

read_str(
    filepath: FsPath, *, encoding: str = "utf-8"
) -> str

Load/Read a string given a fspath

Parameters:

• filepath

  (FsPath) –

  Filepath for file to read

• encoding

  (str, default: 'utf-8' ) –

  Encoding to use for reading the file

Returns:

• str ( str ) –

  String read from given fspath

Examples:

>>> from shellfish.fs import read_str, write_str
>>> fspath = "read_str.doctest.txt"
>>> write_str(fspath, r'Check out this string')
21
>>> read_str(fspath)
'Check out this string'
>>> import os; os.remove(fspath)

write_str

write_str(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: int | None = None,
) -> int

Save/Write a string to fspath

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• string

  (str) –

  string to be written

• encoding

  (str, default: 'utf-8' ) –

  String encoding to write file with

• append

  (bool, default: False ) –

  Flag to append to file; default = False

• chmod

  (Optional[int], default: None ) –

  Optional chmod to set on file

Returns:

• int –

  None

Examples:

>>> from shellfish.fs import read_str, write_str
>>> fspath = "sstring.doctest.txt"
>>> write_str(fspath, r'Check out this string')
21
>>> read_str(fspath)
'Check out this string'
>>> import os; os.remove(fspath)

write_json

write_json(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Callable[[Any], Any] | None = None,
    chmod: int | None = None,
    append: bool = False,
    **kwargs: Any,
) -> int

Save/Write json-serial-ize-able data to a fspath

Parameters:

• filepath

  (FsPath) –

  fspath to write to

• data

  (Any) –

  json-serial-ize-able data

• fmt

  (bool, default: False ) –

  Indented (2 spaces) or minify data (default=False)

• pretty

  (bool, default: False ) –

  Indented (2 spaces) or minify data (default=False)

• sort_keys

  (bool, default: False ) –

  Sort the data keys if the data is a dictionary.

• append_newline

  (bool, default: False ) –

  Append a newline to the end of the file

• default

  (Callable[[Any], Any] | None, default: None ) –

  default function hook

• chmod

  (Optional[int], default: None ) –

  Optional chmod to set on file

• append

  (bool, default: False ) –

  Append to the file if True, overwrite otherwise; default

• **kwargs

  (Any, default: {} ) –

  Additional keyword arguments to pass to jsonbourne.JSON.dumpb

Returns:

• int ( int ) –

  Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import read_json, write_json

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> write_json(fspath, data)
19
>>> read_json(fspath)
{'a': 1, 'b': 2, 'c': 3}
>>> import os; os.remove(fspath)

Lists:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> data = list(data.items())
>>> data  # has tuples, but will be saved as strings
[('a', 1), ('b', 2), ('c', 3)]
>>> fspath = "rjson_dict.doctest.json"
>>> write_json(fspath, data)
25
>>> read_json(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

read_json

read_json(filepath: FsPath) -> Any

Load/Read-&-parse json data given a fspath

Parameters:

• filepath

  (FsPath) –

  Filepath to load/read data from

Returns:

• Any –

  Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import read_json, write_json

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> write_json(fspath, data)
19
>>> read_json(fspath)
{'a': 1, 'b': 2, 'c': 3}
>>> import os; os.remove(fspath)

Lists:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> data = list(data.items())
>>> data  # has tuples, but will be saved as strings
[('a', 1), ('b', 2), ('c', 3)]
>>> fspath = "rjson_dict.doctest.json"
>>> write_json(fspath, data)
25
>>> read_json(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

extension

extension(fspath: str, *, period: bool = False) -> str

Return the extension for a fspath

Examples:

>>> from shellfish.fs import extension
>>> extension("foo.bar")
'bar'
>>> extension("foo.tar.gz")
'tar.gz'
>>> extension("foo.tar.gz", period=True)
'.tar.gz'

sep_split

sep_split(fspath: FsPath) -> tuple[str, ...]

Split a string on the current platform os.path.sep value

sep_join

sep_join(path_strings: Iterator[str]) -> str

Join iterable of strings on the current platform os.path.sep value

sep_strip

sep_strip(fspath: FsPath) -> str

Strip a string of the current platform's os.path.sep value

sep_lstrip

sep_lstrip(fspath: FsPath) -> str

Left-strip a string of the current platform's os.path.sep value

sep_rstrip

sep_rstrip(fspath: FsPath) -> str

Right-strip a string of the current platform's os.path.sep value

filecmp

filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool

Compare 2 files for equality given their filepaths

Parameters:

• left

  (FsPath) –

  Filepath 1

• right

  (FsPath) –

  Filepath 2

• shallow

  (bool, default: True ) –

  Check only size and modification time if True

• blocksize

  (int, default: 65536 ) –

  Chunk size to read files

Returns:

• bool –

  True if files are equal, False otherwise

shebang

shebang(fspath: FsPath) -> str | None

Get the shebang string given a fspath; Returns None if no shebang

Parameters:

• fspath

  (FsPath) –

  Path to file that might have a shebang

Returns:

• str | None –

  Optional[str]: The shebang string if it exists, None otherwise

Examples:

>>> from inspect import getabsfile
>>> script = 'ashellscript.sh'
>>> with open(script, 'w') as f:
...     f.write('#!/bin/bash\necho "howdy"\n')
25
>>> shebang(script)
'#!/bin/bash'
>>> from os import remove
>>> remove(script)

chmod

chmod(fspath: FsPath, mode: int) -> None

Change the access permissions of a file

Parameters:

• fspath

  (FsPath) –

  Path to file to chmod

• mode

  (int) –

  Permissions mode as an int

mkdir

mkdir(
    fspath: FsPath,
    *,
    parents: bool = False,
    p: bool = False,
    exist_ok: bool = False,
) -> None

Make directory at given fspath

Parameters:

• fspath

  (FsPath) –

  Directory path to create

• parents

  (bool, default: False ) –

  Make parent dirs if True; do not make parent dirs if False

• p

  (bool, default: False ) –

  Make parent dirs if True; do not make parent dirs if False (alias of parents)

• exist_ok

  (bool, default: False ) –

  Throw error if directory exists and exist_ok is False

Returns:

• None –

  None

mkdirp

mkdirp(fspath: FsPath) -> None

Make directory and parents

glob

glob(
    pattern: str,
    *,
    recursive: bool = False,
    r: bool = False,
) -> Iterator[str]

Return an iterator of fspaths matching the given glob pattern

Parameters:

• pattern

  (str) –

  Glob pattern

• recursive

  (bool, default: False ) –

  Recursively search directories if True

• r

  (bool, default: False ) –

  Recursively search directories if True (Alias for recursive)

Returns:

• Iterator[str] –

  Iterator[str]: Iterator of fspaths matching the glob pattern

move

move(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

• src

  (FsPath) –

  source file(s)

• dest

  (FsPath) –

  destination path

rmfile

rmfile(fspath: FsPath, *, dryrun: bool = False) -> str

Remove a file at given fspath

Parameters:

• fspath

  (FsPath) –

  Filepath to remove

• dryrun

  (bool, default: False ) –

  Do not remove file if True

Returns:

• str –

  None

rmdir

rmdir(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
) -> None

Remove directory at given fspath

Parameters:

• fspath

  (FsPath) –

  Directory path to remove

• force

  (bool, default: False ) –

  Force removal of files and directories

• recursive

  (bool, default: False ) –

  Recursively remove all contents if True

Returns:

• None –

  None

rm_gen

rm_gen(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    dryrun: bool = False,
) -> Generator[str, Any, Any]

Remove files & directories in the style of the shell

Parameters:

• fspath

  (FsPath) –

  Path to file or directory to remove

• force

  (bool, default: False ) –

  Force removal of files and directories

• recursive

  (bool, default: False ) –

  Flag to remove recursively (like the -r in rm -r dir)

• dryrun

  (bool, default: False ) –

  Do not remove file if True

Raises:

• ValueError –

  If recursive and r are False and fspath is a directory

rm

rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    dryrun: bool = False,
    verbose: bool = False,
) -> list[str] | None

Remove files & directories in the style of the shell

Parameters:

• fspath

  (FsPath) –

  Path to file or directory to remove

• force

  (bool, default: False ) –

  ignore errors and missing files/dirs; default is False

• recursive

  (bool, default: False ) –

  Flag to remove recursively (like the -r in rm -r dir)

• dryrun

  (bool, default: False ) –

  Do not remove file if True

• verbose

  (bool, default: False ) –

  Print the files being removed

Raises:

• ValueError –

  If recursive and r are False and fspath is a directory

stat

stat(fspath: FsPath) -> stat_result

Return the os.stat_result object for a given fspath

Parameters:

• fspath

  (FsPath) –

  Path to file or directory

Returns:

• stat_result –

  os.stat_result: stat_result object

copy_file

copy_file(
    src: FsPath,
    dest: FsPath,
    *,
    dryrun: bool = False,
    mkdirp: bool = False,
) -> tuple[str, str]

Copy a file given a source-path and a destination-path

Parameters:

• src

  (str) –

  Source fspath

• dest

  (str) –

  Destination fspath

• dryrun

  (bool, default: False ) –

  Do not copy file if True just return the src and dest

• mkdirp

  (bool, default: False ) –

  Create parent directories if they do not exist

cp

cp(
    src: FsPath,
    dest: FsPath,
    *,
    force: bool = True,
    recursive: bool = False,
    r: bool = False,
    f: bool = True,
) -> None

Copy the directory/file src to the directory/file dest

Parameters:

• src

  (str) –

  Source directory/file to copy

• dest

  (FsPath) –

  Destination directory/file to copy

• force

  (bool, default: True ) –

  Force the copy (like -f flag for cp in shell)

• recursive

  (bool, default: False ) –

  Recursive copy (like -r flag for cp in shell)

• r

  (bool, default: False ) –

  alias for recursive

• f

  (bool, default: True ) –

  alias for force

Raises:

• ValueError –

  If src is a directory and recursive and r are both False