shellfish.fs.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish

shellfish ~ shell and file-system utils

Classes

shellfish.Done(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

PRun => 'ProcessRun' for finished processes

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.Done.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.Done.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.Done.__ge__(filepath: FsPath) -> 'Done'

Operator overload for writing stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __ge__(self, filepath: FsPath) -> "Done":
    """Operator overload for writing stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath)
    return self

shellfish.Done.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.Done.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.Done.__gt__(filepath: FsPath) -> None

Operator overload for writing a stdout to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __gt__(self, filepath: FsPath) -> None:
    """Operator overload for writing a stdout to a fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath)

shellfish.Done.__irshift__(filepath: FsPath) -> 'Done'

Operator overload for appending stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __irshift__(self, filepath: FsPath) -> "Done":
    """Operator overload for appending stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath, append=True)
    return self

shellfish.Done.__post_init__() -> None

Write the stdout/stdout to sys.stdout/sys.stderr post object init

Source code in libs/shellfish/shellfish/sh.py

def __post_init__(self) -> None:
    """Write the stdout/stdout to sys.stdout/sys.stderr post object init"""
    if self.verbose:
        self.sys_print()

shellfish.Done.__rshift__(filepath: FsPath) -> None

Operator overload for appending stdout to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __rshift__(self, filepath: FsPath) -> None:
    """Operator overload for appending stdout to fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath, append=True)

shellfish.Done.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.Done.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.Done.check(ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0) -> None

Check returncode and stderr

Raises:

Type	Description
DoneError	If return code is non-zero and stderr is not None

Source code in libs/shellfish/shellfish/sh.py

def check(
    self,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
) -> None:
    """Check returncode and stderr

    Raises:
        DoneError: If return code is non-zero and stderr is not None

    """
    if isinstance(ok_code, int):
        if self.returncode != ok_code and self.stderr:
            raise DoneError(done=self)
    else:
        if self.returncode not in ok_code:
            raise DoneError(done=self)

shellfish.Done.completed_process() -> CompletedProcess[str]

Return subprocess.CompletedProcess object

Source code in libs/shellfish/shellfish/sh.py

def completed_process(self) -> CompletedProcess[str]:
    """Return subprocess.CompletedProcess object"""
    return CompletedProcess(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
    )

shellfish.Done.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.Done.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.Done.done_dict() -> DoneDict

Return Done object as typed-dict

Source code in libs/shellfish/shellfish/sh.py

def done_dict(self) -> DoneDict:
    """Return Done object as typed-dict"""
    return DoneDict(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_dict(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.Done.done_obj() -> DoneObj

Return Done object typed dict

Source code in libs/shellfish/shellfish/sh.py

def done_obj(self) -> DoneObj:
    """Return Done object typed dict"""
    return DoneObj(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_obj(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.Done.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.Done.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.Done.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.Done.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.Done.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.Done.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.Done.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.Done.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.Done.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.Done.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.Done.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.Done.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.Done.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.Done.grep(string: str) -> List[str]

Return lines in stdout that have

Parameters:

Name	Type	Description	Default
string	str	String to search for	required

Returns:

Type	Description
List[str]	List[str]: List of strings of stdout lines containing the given search string

Source code in libs/shellfish/shellfish/sh.py

def grep(self, string: str) -> List[str]:
    """Return lines in stdout that have

    Args:
        string (str): String to search for

    Returns:
        List[str]: List of strings of stdout lines containing the given
            search string

    """
    return [
        line for line in self.stdout.splitlines(keepends=False) if string in line
    ]

shellfish.Done.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.Done.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.Done.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.Done.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.Done.json_parse(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout"""
    return (
        self.json_parse_stdout(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
        if not stderr
        else self.json_parse_stderr(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
    )

shellfish.Done.json_parse_stderr(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stderr

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stderr(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stderr"""
    return JSON.loads(self.stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.Done.json_parse_stdout(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stdout(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stdout"""
    return JSON.loads(self.stdout, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.Done.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.Done.parse_json(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout (alias bc I keep flip-flopping the fn name)

Source code in libs/shellfish/shellfish/sh.py

def parse_json(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout (alias bc I keep flip-flopping the fn name)"""
    return self.json_parse(stderr=stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.Done.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.Done.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.Done.sys_print() -> None

Write self.stdout to sys.stdout and self.stderr to sys.stderr

Source code in libs/shellfish/shellfish/sh.py

def sys_print(self) -> None:
    """Write self.stdout to sys.stdout and self.stderr to sys.stderr"""
    sys.stdout.write(self.stdout)
    sys.stderr.write(self.stderr)

shellfish.Done.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.Done.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.Done.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.Done.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.Done.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.Done.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.Done.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.Done.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.Done.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.Done.write_stderr(filepath: FsPath, *, append: bool = False) -> None

Write stderr as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stderr(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stderr as a string to a fspath

    Args:
        filepath: Filepath of location to write stderr
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stderr, append=append)

shellfish.Done.write_stdout(filepath: FsPath, *, append: bool = False) -> None

Write stdout as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stdout(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stdout as a string to a fspath

    Args:
        filepath: Filepath to write stdout to
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stdout, append=append)

shellfish.DoneError(done: Done)

Bases: SubprocessError

Raised when run() is called with check=True and the process returns a non-zero exit status.

Attributes:

Name	Type	Description
cmd	str	command that was run
returncode	int	exit status of the process
stdout	str	standard output (stdout) of the process
stderr	str	standard error (stderr) of the process

Source code in libs/shellfish/shellfish/sh.py

def __init__(self, done: Done) -> None:
    self.returncode = done.returncode
    self.cmd = done.args
    self.stderr = done.stderr
    self.stdout = done.stdout
    self.cmd = done.args
    self.done = done

shellfish.DoneObj

Bases: TypedDict

Todo

deprecate this in favor of DoneDict

shellfish.Flag

Flag obj

Examples:

>>> Flag.__help
'--help'
>>> Flag._v
'-v'

shellfish.FlagMeta

Bases: type

Meta class

Functions

shellfish.FlagMeta.attr2flag(string: str) -> str cached staticmethod

Convert and return attr to string

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
@lru_cache(maxsize=None)
def attr2flag(string: str) -> str:
    """Convert and return attr to string"""
    return string.replace("_", "-")

shellfish.HrTime(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

High resolution time

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.HrTime.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.HrTime.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.HrTime.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.HrTime.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.HrTime.__post_init__() -> Any

Function place holder that is called after object initialization

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def __post_init__(self) -> Any:
    """Function place holder that is called after object initialization"""

shellfish.HrTime.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.HrTime.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.HrTime.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.HrTime.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.HrTime.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.HrTime.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.HrTime.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.HrTime.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.HrTime.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.HrTime.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.HrTime.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.HrTime.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.HrTime.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.HrTime.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.HrTime.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.HrTime.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.HrTime.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.HrTime.from_seconds(seconds: float) -> 'HrTime' classmethod

Return HrTime object from seconds

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
'HrTime'	HrTime object

Source code in libs/shellfish/shellfish/sh.py

@classmethod
def from_seconds(cls, seconds: float) -> "HrTime":
    """Return HrTime object from seconds

    Args:
        seconds (float): number of seconds

    Returns:
        HrTime object

    """
    _sec, _ns = seconds2hrtime(seconds)
    return cls(sec=_sec, ns=_ns)

shellfish.HrTime.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.HrTime.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.HrTime.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.HrTime.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.HrTime.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.HrTime.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.HrTime.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.HrTime.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.HrTime.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.HrTime.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.HrTime.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.HrTime.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.HrTime.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.HrTime.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.HrTime.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.HrTime.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.LIN

Bases: LIN

Linux (and Mac) shell commands/methods container

Functions

shellfish.LIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	str	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (str): Allow link to exist

    """
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.LIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): Allow link to exist

    """
    for link, target in link_target_tuples:
        LIN.link_dir(link, target, exist_ok=exist_ok)

shellfish.LIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	Allow links to already exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): Allow links to already exist

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.LIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
exist_ok	bool	Allow links to already exist	False
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        exist_ok (bool): Allow links to already exist
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.

    """
    for link, target in link_target_tuples:
        LIN.link_file(link, target, exist_ok=exist_ok)

shellfish.LIN.rsync(src: str, dest: str, delete: bool = False, mkdirs: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> Done staticmethod

Run an rsync subprocess

Parameters:

Name	Type	Description	Default
mkdirs	bool	Make destination directories if they do not already exist; defaults to False.	False
src	str	Source directory path	required
dest	str	Destination directory path	required
delete	bool	Delete files/directories in destination if they do exist in source	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Name	Type	Description
Done	Done	Done object containing the info for the rsync run

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync(
    src: str,
    dest: str,
    delete: bool = False,
    mkdirs: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> Done:
    """Run an `rsync` subprocess

    Args:
        mkdirs (bool): Make destination directories if they do not already
            exist; defaults to False.
        src (str): Source directory path
        dest (str): Destination directory path
        delete (bool): Delete files/directories in destination if they do
            exist in source
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        Done: Done object containing the info for the rsync run

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection

    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    rsync_args = LIN.rsync_args(
        src, dest, delete=delete, exclude=exclude, include=include, dry_run=dry_run
    )

    done = do(args=list(filter(None, rsync_args)))
    return done

shellfish.LIN.rsync_args(src: str, dest: str, delete: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> List[str] staticmethod

Return args for rsync command on linux/mac

Parameters:

Name	Type	Description	Default
src	str	path to remote (raid) tdir	required
dest	str	path to local tdir	required
delete	bool	Flag that will do a 'hard sync'	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from rsync

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync_args(
    src: str,
    dest: str,
    delete: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> List[str]:
    """Return args for rsync command on linux/mac

    Args:
        src: path to remote (raid) tdir
        dest: path to local tdir
        delete: Flag that will do a 'hard sync'
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        subprocess return code from rsync

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection


    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []

    if not dest.endswith("/"):
        dest = f"{dest}/"
    if not src.endswith("/"):
        src = f"{src}/"
    _args: List[Union[str, None]] = [
        "rsync",
        "-a",
        "-O",
        "--no-o",
        "--no-g",
        "--no-p",
        "--delete" if delete else None,
        *(f'--exclude="{pattern}"' for pattern in exclude),
        *(f'--include="{pattern}"' for pattern in include),
        *(("--dry-run", "-i") if dry_run else (None,)),
        src,
        dest,
    ]
    return list(filter(None, _args))

shellfish.LIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.LIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_dir(link)

shellfish.LIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.LIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_file(link)

shellfish.Stdio

Bases: IntEnum

Standard-io enum object

shellfish.WIN

Bases: WIN

Windows shell commands/methods container

Functions

shellfish.WIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, do not raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, do not raise an exception if the link exists

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath, target_is_directory=True)
    except OSError:
        batman.MKLINK(
            linkpath,
            targetpath,
            D=True,
        )

shellfish.WIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, do not raise an exception if the link(s) exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, do not raise an exception if the link(s) exist

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_dir(link, target, exist_ok=exist_ok)
    except OSError:
        args = [
            batman.MKLINK_ARGS(link, target, D=True)
            for link, target in link_target_tuples
            if WIN._check_link_target_dirs(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in args])

shellfish.WIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        symlink(targetpath, linkpath)
    except OSError:
        makedirs(path.split(linkpath)[0], exist_ok=True)
        batman.MKLINK(
            linkpath,
            targetpath,
        )

shellfish.WIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_file(link, target, exist_ok=exist_ok)
    except OSError:
        link_target_tuples = list(link_target_tuples)
        _args = [
            batman.MKLINK_ARGS(link, target, D=False)
            for link, target in link_target_tuples
            if WIN._check_link_target_files(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in _args])

shellfish.WIN.robocopy(src: str, dest: str, *, mkdirs: bool = True, delete: bool = False, exclude_files: Optional[Iterable[str]] = None, exclude_dirs: Optional[Iterable[str]] = None, dry_run: bool = False) -> Done staticmethod

Robocopy wrapper function (crude in that it opens a subprocess)

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[Iterable[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[Iterable[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False
mkdirs	bool	Flag to make destinaation directories if they do not already exist	True

Returns:

Type	Description
Done	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy(
    src: str,
    dest: str,
    *,
    mkdirs: bool = True,
    delete: bool = False,
    exclude_files: Optional[Iterable[str]] = None,
    exclude_dirs: Optional[Iterable[str]] = None,
    dry_run: bool = False,
) -> Done:  # pragma: nocov
    """Robocopy wrapper function (crude in that it opens a subprocess)

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run
        mkdirs (bool): Flag to make destinaation directories if they do
            not already exist

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    _exclude_files = [] if exclude_files is None else list(exclude_files)
    _exclude_dirs = [] if exclude_dirs is None else list(exclude_dirs)
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    _args = WIN.robocopy_args(
        src=src,
        dest=dest,
        delete=delete,
        exclude_files=_exclude_files,
        exclude_dirs=_exclude_dirs,
        dry_run=dry_run,
    )
    return do(args=_args)

shellfish.WIN.robocopy_args(src: str, dest: str, *, delete: bool = False, exclude_files: Optional[List[str]] = None, exclude_dirs: Optional[List[str]] = None, dry_run: bool = False) -> List[str] staticmethod

Return list of robocopy command args

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[List[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[List[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy_args(
    src: str,
    dest: str,
    *,
    delete: bool = False,
    exclude_files: Optional[List[str]] = None,
    exclude_dirs: Optional[List[str]] = None,
    dry_run: bool = False,
) -> List[str]:
    """Return list of robocopy command args

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    if exclude_files is None:
        exclude_files = []
    if exclude_dirs is None:
        exclude_dirs = []
    _args = [
        "robocopy",
        src,
        dest,
        "/MIR" if delete else "/E",
        "/mt",
        "/W:1",
        "/R:1",
    ]
    if exclude_dirs:
        _args.extend(["/XD", *exclude_dirs])
    if exclude_files:
        _args.extend(["/XF", *exclude_files])
    if dry_run:
        _args.append("/L")
    return list(filter(None, _args))

shellfish.WIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.RD(link)

shellfish.WIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_dir(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            commands=[batman.RD_ARGS(link) for link in links]
        )

shellfish.WIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link (str): path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.DEL(link)

shellfish.WIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_file(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            [batman.DEL_ARGS(link) for link in links],
        )

Functions

shellfish.basename(fspath: FsPath) -> str

Return the basename of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def basename(fspath: FsPath) -> str:
    """Return the basename of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.basename(str(fspath))

shellfish.cd(dirpath: FsPath) -> None

Change directory to given dirpath; alias for os.chdir

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory fspath	required

Source code in libs/shellfish/shellfish/sh.py

def cd(dirpath: FsPath) -> None:
    """Change directory to given dirpath; alias for `os.chdir`

    Args:
        dirpath: Directory fspath

    """
    chdir(str(dirpath))

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

Change the access permissions of a file

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file to chmod	required
mode	int	Permissions mode as an int	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def chmod(fspath: FsPath, mode: int) -> None:
    """Change the access permissions of a file

    Args:
        fspath (FsPath): Path to file to chmod
        mode (int): Permissions mode as an int

    """
    return _chmod(path=str(fspath), mode=mode)

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

Name	Type	Description	Default
src	str	Source fspath	required
dest	str	Destination fspath	required
dryrun	bool	Do not copy file if True just return the src and dest	False
mkdirp	bool	Create parent directories if they do not exist	False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source fspath
        dest (str): Destination fspath
        dryrun (bool): Do not copy file if True just return the src and dest
        mkdirp (bool): Create parent directories if they do not exist

    """
    _dest = Path(dest)
    if not dryrun and mkdirp:
        _dest.parent.mkdir(parents=mkdirp, exist_ok=True)
    elif not _dest.parent.exists() or not _dest.parent.is_dir():
        raise FileNotFoundError(f"Destination directory {_dest.parent} does not exist")
    if not dryrun:
        wbytes_gen(dest, lbytes_gen(src, blocksize=2**18))
        _copystat(src, dest, follow_symlinks=True)
    return (str(src), str(dest))

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

Name	Type	Description	Default
src	str	Source directory/file to copy	required
dest	FsPath	Destination directory/file to copy	required
force	bool	Force the copy (like -f flag for cp in shell)	True
recursive	bool	Recursive copy (like -r flag for cp in shell)	False
r	bool	alias for recursive	False
f	bool	alias for force	True

Raises:

Type	Description
ValueError	If src is a directory and recursive and r are both False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source directory/file to copy
        dest: Destination directory/file to copy
        force: Force the copy (like -f flag for cp in shell)
        recursive: Recursive copy (like -r flag for cp in shell)
        r: alias for recursive
        f: alias for force

    Raises:
        ValueError: If src is a directory and recursive and r are both `False`

    """
    _recursive = recursive or r
    _force = force or f
    for _src in iglob(_fspath(src), recursive=True):
        _dest = dest
        if (path.exists(dest) and not _force) or _src == dest:
            return
        if path.isdir(_src) and not _recursive:
            raise ValueError("Source ({}) is directory; use r=True")
        if path.isfile(_src) and path.isdir(dest):
            _dest = path.join(dest, path.basename(_src))
        if path.isfile(_src) or path.islink(src):
            copy_file(_src, _dest)
        if path.isdir(_src):
            if not path.exists(dest):
                _makedirs(dest)
            copytree(src, dest, dirs_exist_ok=True)

shellfish.decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str

Return Stdio bytes from stdout/stderr as a string

Args:
    stdio_bytes (bytes): STDOUT/STDERR bytes
    lf (bool): Replace `

line endings with `

Returns:
    str: decoded stdio bytes

Source code in libs/shellfish/shellfish/sh.py

def decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str:
    """Return Stdio bytes from stdout/stderr as a string

    Args:
        stdio_bytes (bytes): STDOUT/STDERR bytes
        lf (bool): Replace `\r\n` line endings with `\n`

    Returns:
        str: decoded stdio bytes

    """
    if isinstance(stdio_bytes, str):
        return stdio_bytes
    if lf:
        return decode_stdio_bytes(stdio_bytes, lf=False).replace("\r\n", "\n")
    try:
        return str(stdio_bytes.decode())
    except AttributeError:
        return ""
    except Exception:
        pass

    try:
        return str(stdio_bytes.decode("utf-8"))
    except UnicodeDecodeError:
        pass
    return str(stdio_bytes.decode("latin-1"))

shellfish.dir_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dir_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isdir"""
    return isdir(fspath)

shellfish.dir_exists_async(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.dirname(fspath: FsPath) -> str

Return dirname/parent-dir of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def dirname(fspath: FsPath) -> str:
    """Return dirname/parent-dir of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.dirname(_fspath(fspath))

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

Yield all dirpaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all dirpaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in dirs_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield directory-paths beneath a dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        dirpath if abspath else str(dirpath).replace(dirpath, "").strip(sep)
        for dirpath in (
            pwd
            for pwd, dirs, files in walk(
                str(dirpath),
                onerror=onerror,
                topdown=topdown,
                followlinks=followlinks,
            )
        )
    )

shellfish.do(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[FsPath] = None, shell: bool = False, check: bool = False, tee: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
tee	bool	Flag to tee the subprocess stdout and stderr to sys.stdout/stderr	False
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check against	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	if args and *popenargs are both given

Source code in libs/shellfish/shellfish/sh.py

def do(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    shell: bool = False,
    check: bool = False,
    tee: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        tee (bool): Flag to tee the subprocess stdout and stderr to sys.stdout/stderr
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check against
        dryrun: Don't run the subprocess

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: if args and *popenargs are both given

    """
    if args and popenargs:
        raise ValueError("Cannot give *popenargs and `args` kwargs")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win():
        args = validate_popen_args_windows(args, env)
    _input = validate_stdin(input)
    return _do(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        check=check,
        verbose=verbose,
        input=_input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
        tee=tee,
    )

shellfish.do_async(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend environment with the current environment (Default value = True)	True
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	If both *popenargs and args are given

Source code in libs/shellfish/shellfish/sh.py

async def do_async(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: If both *popenargs and args are given

    """
    if args and popenargs:
        raise ValueError("Cannot give *args and args-keyword-argument")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win() and sys.version_info < (3, 8):
        done = await do_asyncify(
            args=args,
            env=env,
            extenv=extenv,
            cwd=cwd,
            shell=shell,
            verbose=verbose,
            input=input,
            check=check,
            timeout=timeout,
            ok_code=ok_code,
            dryrun=dryrun,
        )
        done.async_proc = True
        return done
    if not shell and is_win():
        args = validate_popen_args_windows(args, env)
    return await _do_async(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.doa(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Alias for sh.do_async

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False
extenv	bool	Extend environment with the current environment (Default value = True)	True

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

async def doa(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Alias for sh.do_async

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object
        extenv: Extend environment with the current environment (Default value = True)

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return await do_async(
        *popenargs,
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise"""
    return path.exists(_fspath(fspath))

shellfish.export(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Raises:

Type	Description
ValueError	if unable to parse key/val

Source code in libs/shellfish/shellfish/sh.py

def export(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Raises:
        ValueError: if unable to parse key/val

    """
    if val:
        environ[key] = val
        return (key, val)
    if "=" in key:
        _key = key.split("=")[0]
        return export(_key, key[len(_key) + 1 :])
    raise ValueError(
        f"Unable to parse env variable - key: {str(key)}, value: {str(val)}"
    )

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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'

    """
    if period:
        return "".join(Path(fspath).suffixes)
    return "".join(Path(fspath).suffixes).lstrip(".")

shellfish.file_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isfile"""
    return isfile(fspath)

shellfish.file_exists_async(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

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

Yield lines from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	File to yield lines from	required
keepends	bool	Flag to keep the ends of the file lines	True

Yields:

Type	Description
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 wstring
>>> wstring(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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_lines_gen(filepath: FsPath, keepends: bool = True) -> Iterable[str]:
    r"""Yield lines from a given fspath

    Args:
        filepath: File to yield lines from
        keepends: Flag to keep the ends of the file lines

    Yields:
        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 wstring
        >>> wstring(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)


    """
    with open(filepath) as f:
        if keepends:
            yield from (line for line in f)
        else:
            yield from (line.rstrip("\n").rstrip("\r\n") for line in f)

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

Compare 2 files for equality given their filepaths

Parameters:

Name	Type	Description	Default
left	FsPath	Filepath 1	required
right	FsPath	Filepath 2	required
shallow	bool	Check only size and modification time if True	True
blocksize	int	Chunk size to read files	65536

Returns:

Type	Description
bool	True if files are equal, False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool:
    """Compare 2 files for equality given their filepaths

    Args:
        left (FsPath): Filepath 1
        right (FsPath): Filepath 2
        shallow (bool): Check only size and modification time if True
        blocksize (int): Chunk size to read files

    Returns:
        True if files are equal, False otherwise

    """
    left_stat = stat(left)
    right_stat = stat(right)
    if (
        shallow
        and left_stat.st_size == right_stat.st_size
        and left_stat.st_mtime == right_stat.st_mtime
    ):
        return True
    if left_stat.st_size != right_stat.st_size:
        return False
    return not any(
        left_chunk != right_chunk
        for left_chunk, right_chunk in zip(
            rbytes_gen(left, blocksize=blocksize),
            rbytes_gen(right, blocksize=blocksize),
        )
    )

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in files_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.filepath_mtimedelta_sec(filepath: FsPath) -> float

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_mtimedelta_sec(filepath: FsPath) -> float:
    """Return the seconds since the file(path) was last modified"""
    return time() - path.getmtime(_fspath(filepath))

shellfish.files_dirs_gen(dirpath: FsPath = '.', *, abspath: bool = True, topdown: bool = True, onerror: Optional[Callable[[OSError], Any]] = 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:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath is a directory	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Tuple[Iterator[str], Iterator[str]]:
    r"""Return a files_gen() and a dirs_gen() in one swell-foop

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath is a directory

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

    """
    return files_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    ), dirs_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield file-paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        filepath if abspath else str(filepath).replace(dirpath, "").strip(sep)
        for filepath in (
            path.join(pwd, filename)
            for pwd, dirs, files in walk(
                str(dirpath),
                topdown=topdown,
                onerror=onerror,
                followlinks=followlinks,
            )
            for filename in files
        )
    )

shellfish.filesize(fspath: FsPath) -> int

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath as a string or pathlib.Path object	required

Returns:

Name	Type	Description
int	int	size of the fspath in bytes

Source code in libs/shellfish/shellfish/fs/__init__.py

def filesize(fspath: FsPath) -> int:
    """Return the size of the given file(path) in bytes

    Args:
        fspath (FsPath): Filepath as a string or pathlib.Path object

    Returns:
        int: size of the fspath in bytes

    """
    return stat(fspath).st_size

shellfish.filesize_async(fspath: FsPath) -> int async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def 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

    """
    _stat_res = await aios.stat(str(fspath))
    return _stat_res.st_size

shellfish.flatten_args(*args: Union[Any, List[Any]]) -> List[str]

Flatten possibly nested iterables of sequences to a list of strings

Examples:

>>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
['cmd', 'uno', 'dos', 'tres']
>>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
['cmd', 'uno', 'dos', 'tres', '4444', 'five']

Source code in libs/shellfish/shellfish/sh.py

def flatten_args(*args: Union[Any, List[Any]]) -> List[str]:
    """Flatten possibly nested iterables of sequences to a list of strings

    Examples:
        >>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
        ['cmd', 'uno', 'dos', 'tres']
        >>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
        ['cmd', 'uno', 'dos', 'tres', '4444', 'five']

    """
    return list(_flatten_strings(*args))

shellfish.fspath(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def fspath(fspath: FsPath) -> str:
    """Alias for os._fspath; returns fspath string for any type of path"""
    return _fspath(fspath)

shellfish.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish.is_dir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.is_file(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_file(fspath: FsPath) -> bool:
    """Return True if the given path is a file; alias for isfile"""
    return isfile(fspath)

shellfish.is_file_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.is_link(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_link(fspath: FsPath) -> bool:
    """Return True if the given path is a link; alias for islink"""
    return islink(fspath)

shellfish.is_link_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.isdir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isdir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; False otherwise"""
    return path.isdir(_fspath(fspath))

shellfish.isdir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.isfile(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isfile(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return path.isfile(_fspath(fspath))

shellfish.isfile_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.islink(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def islink(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return path.islink(_fspath(fspath))

shellfish.islink_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.listdir_async(fspath: FsPath) -> List[str] async

Async version of os.listdir

Source code in libs/shellfish/shellfish/fs/_async.py

async def listdir_async(fspath: FsPath) -> List[str]:
    """Async version of `os.listdir`"""
    return await aios.listdir(_fspath(fspath))

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]:
    r"""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

    """
    _attr = "path" if abspath else "name"
    return (
        getattr(el, _attr)
        for el in scandir_gen(
            fspath,
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )
    )

shellfish.ls(dirpath: FsPath = '.', abspath: bool = False) -> List[str]

List files and dirs given a dirpath (defaults to pwd)

Parameters:

Name	Type	Description	Default
dirpath	FsPath	path-string to directory to list	'.'
abspath	bool	Give absolute paths	False

Returns:

Type	Description
List[str]	List of the directory items

Source code in libs/shellfish/shellfish/sh.py

def ls(dirpath: FsPath = ".", abspath: bool = False) -> List[str]:
    """List files and dirs given a dirpath (defaults to pwd)

    Args:
        dirpath (FsPath): path-string to directory to list
        abspath (bool): Give absolute paths

    Returns:
        List of the directory items

    """
    if abspath:
        return [el.path for el in scandir(str(dirpath))]
    return listdir(str(dirpath))

shellfish.ls_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the directories in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want list directories	'.'
abspath	bool	Return absolute directory paths	False

Returns:

Type	Description
List[str]	List of directories as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_dirs(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the directories in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want list directories
        abspath (bool): Return absolute directory paths

    Returns:
        List of directories as strings

    """
    dirs = (el for el in scandir(str(dirpath)) if el.is_dir())
    if abspath:
        return list(map(lambda el: el.path, dirs))
    return list(map(lambda el: el.name, dirs))

shellfish.ls_files(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the files in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want to list files	'.'
abspath	bool	Return absolute filepaths	False

Returns:

Type	Description
List[str]	List of files as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_files(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the files in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want to list files
        abspath (bool): Return absolute filepaths

    Returns:
        List of files as strings

    """
    files = (el for el in scandir(str(dirpath)) if el.is_file())
    if abspath:
        return list(map(lambda el: el.path, files))
    return list(map(lambda el: el.name, files))

shellfish.ls_files_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> Tuple[List[str], List[str]]

List the files and directories given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to execute on	'.'
abspath	bool	Return absolute file/directory paths	False

Returns:

Type	Description
Tuple[List[str], List[str]]	Two lists of strings; the first is a list of the files and the second is a list of the directories

Source code in libs/shellfish/shellfish/sh.py

def ls_files_dirs(
    dirpath: FsPath = ".", *, abspath: bool = False
) -> Tuple[List[str], List[str]]:
    """List the files and directories given directory path

    Args:
        dirpath (FsPath): Directory path to execute on
        abspath (bool): Return absolute file/directory paths

    Returns:
        Two lists of strings; the first is a list of the files and the second
            is a list of the directories

    """
    dir_items = list(fs.scandir_gen(dirpath, files=True, dirs=True))
    dir_dir_entries = (el for el in dir_items if el.is_dir())
    file_dir_entries = (el for el in dir_items if el.is_file())
    if not abspath:
        return [el.name for el in file_dir_entries], [el.name for el in dir_dir_entries]
    return [el.path for el in file_dir_entries], [el.path for el in dir_dir_entries]

shellfish.lstat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

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

Make directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to create	required
parents	bool	Make parent dirs if True; do not make parent dirs if False	False
p	bool	Make parent dirs if True; do not make parent dirs if False (alias of parents)	False
exist_ok	bool	Throw error if directory exists and exist_ok is False	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdir(
    fspath: FsPath, *, parents: bool = False, p: bool = False, exist_ok: bool = False
) -> None:
    """Make directory at given fspath

    Args:
        fspath (FsPath): Directory path to create
        parents (bool): Make parent dirs if True; do not make parent dirs if False
        p (bool): Make parent dirs if True; do not make parent dirs if False (alias of parents)
        exist_ok (bool): Throw error if directory exists and exist_ok is False

    Returns:
         None

    """
    _parents = parents or p
    if _parents or exist_ok:
        return _makedirs(_fspath(fspath), exist_ok=_parents or exist_ok)
    return _mkdir(_fspath(fspath))

shellfish.mkdirp(fspath: FsPath) -> None

Make directory and parents

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdirp(fspath: FsPath) -> None:
    """Make directory and parents"""
    return mkdir(fspath=fspath, parents=True)

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

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def move(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    _dst_str = str(dest)
    for file in iglob(str(src), recursive=True):
        _move(file, _dst_str)

shellfish.mv(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/sh.py

def mv(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    fs.move(src, dest)

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in walk_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.pwd() -> str

Return present-working-directory path string; alias for os.getcwd

Returns:

Name	Type	Description
str	str	present working directory as string

Examples:

>>> import os
>>> pwd() == os.getcwd()
True

Source code in libs/shellfish/shellfish/sh.py

def pwd() -> str:
    """Return present-working-directory path string; alias for os.getcwd

    Returns:
        str: present working directory as string

    Examples:
        >>> import os
        >>> pwd() == os.getcwd()
        True

    """
    return getcwd()

shellfish.q(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> q("hello world")
"'hello world'"
>>> q("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def q(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> q("hello world")
        "'hello world'"
        >>> q("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.quote(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> quote("hello world")
"'hello world'"
>>> quote("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def quote(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> quote("hello world")
        "'hello world'"
        >>> quote("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.rbytes(filepath: FsPath) -> bytes

Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes(filepath: FsPath) -> bytes:
    """Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    with open(filepath, "rb") as file:
        return bytes(file.read())

shellfish.rbytes_async(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

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

Yield bytes from a given fspath

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]:
    """Yield bytes from a given fspath"""
    with open(filepath, "rb") as f:
        while True:
            data = f.read(blocksize)
            if not data:
                break
            yield data

shellfish.rbytes_gen_async(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.rjson(filepath: FsPath) -> Any

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def rjson(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)

    """
    return JSON.loads(lstring(filepath=filepath))

shellfish.rjson_async(filepath: FsPath) -> Any async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rjson_async(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    json_string = await rbytes_async(filepath)
    return JSON.loads(json_string)

shellfish.rm(fspath: FsPath, *, force: bool = False, recursive: bool = False, verbose: bool = False, f: bool = False, r: bool = False, v: bool = False, dryrun: bool = False) -> None

Remove files & directories in the style of the shell

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory to remove	required
force	bool	Flag to force removal; ignore missing	False
recursive	bool	Flag to remove recursively (like the -r in rm -r dir)	False
verbose	bool	Flag to be verbose	False
f	bool	alias for force kwarg	False
v	bool	alias for verbose	False
r	bool	alias for recursive kwarg	False
dryrun	bool	Flag to not actually remove anything	False

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/sh.py

def rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    verbose: bool = False,
    f: bool = False,
    r: bool = False,
    v: bool = False,
    dryrun: bool = False,
) -> None:
    """Remove files & directories in the style of the shell

    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Flag to force removal; ignore missing
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        verbose (bool): Flag to be verbose
        f (bool): alias for force kwarg
        v (bool): alias for verbose
        r (bool): alias for recursive kwarg
        dryrun (bool): Flag to not actually remove anything

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if verbose or v:
        echo(f"Removing {fspath}")
    fs.rm(
        fspath,
        force=force or f,
        recursive=recursive or r,
        dryrun=dryrun,
    )

shellfish.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 Args: fspath (FsPath): Path to file or directory to remove force (bool): Force removal of files and directories recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Force removal of files and directories
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if has_magic(str(fspath)):
        if dryrun:
            yield from iglob(_fspath(fspath), recursive=recursive)
        else:
            for _path_str in iglob(str(fspath), recursive=recursive):
                if isfile(_path_str):
                    remove(_path_str)
                elif recursive:
                    rmdir(_path_str, recursive=True, force=force)
                else:
                    raise ValueError(
                        f"{str(_path_str)} (under {str(fspath)}) is a directory -- use r=True or recursive=True"
                    )
    else:
        if isfile(fspath):
            if not dryrun:
                remove(_fspath(fspath))
            yield _fspath(fspath)
        elif recursive:
            if not dryrun:
                rmdir(fspath, force=force, recursive=True)
            yield _fspath(fspath)
        else:
            raise ValueError(
                f"{str(fspath)} is a directory -- use r=True or recursive=True"
            )

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

Remove directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to remove	required
force	bool	Force removal of files and directories	False
recursive	bool	Recursively remove all contents if True	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmdir(fspath: FsPath, *, force: bool = False, recursive: bool = False) -> None:
    """Remove directory at given fspath

    Args:
        fspath (FsPath): Directory path to remove
        force (bool): Force removal of files and directories
        recursive (bool): Recursively remove all contents if True

    Returns:
        None

    """
    if force:
        try:
            return rmdir(fspath, recursive=recursive)
        except FileNotFoundError:
            return
    if recursive:
        return rmtree(_fspath(fspath))
    return _rmdir(_fspath(fspath))

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

Remove a file at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath to remove	required
dryrun	bool	Do not remove file if True	False

Returns:

Type	Description
str	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmfile(fspath: FsPath, *, dryrun: bool = False) -> str:
    """Remove a file at given fspath

    Args:
        fspath (FsPath): Filepath to remove
        dryrun (bool): Do not remove file if True

    Returns:
        None

    """
    if not dryrun:
        remove(_fspath(fspath))
    return _fspath(fspath)

shellfish.rstring(filepath: FsPath, *, encoding: str = 'utf-8') -> str

Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	Encoding to use for reading the file	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rstring(filepath: FsPath, *, encoding: str = "utf-8") -> str:
    r"""Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding: Encoding to use for reading the file

    Returns:
        str: String read from given fspath

    Examples:
        ``` python
        >>> from shellfish.fs import rstring, wstring
        >>> fspath = "lstring.doctest.txt"
        >>> sstring(fspath, r'Check out this string')
        21
        >>> lstring(fspath)
        'Check out this string'
        >>> import os; os.remove(fspath)

        ```

    """
    _bytes = rbytes(filepath=filepath)
    try:
        return _bytes.decode(encoding=encoding)
    except UnicodeDecodeError:  # Catch the unicode decode error
        pass
    return _bytes.decode(encoding="latin2")

shellfish.rstring_async(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.safepath(fspath: FsPath) -> str

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	file-system path; file or directory path string or Path obj	required

Returns:

Name	Type	Description
str	str	file/dir path that does not exist and contains the given path

Source code in libs/shellfish/shellfish/fs/__init__.py

def safepath(fspath: FsPath) -> str:
    """Check if a file/dir path is save/unused; returns an unused path.

    Args:
        fspath: file-system path; file or directory path string or Path obj

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

    """
    path_str = str(fspath)
    if path.exists(path_str):
        f_bn, f_ext = path.splitext(path_str)
        for n in count(1):
            safe_save_path = f"{f_bn}_{str(n).zfill(3)}.{f_ext}"
            if not path.exists(safe_save_path):
                return safe_save_path
    return path_str

shellfish.scandir(dirpath: FsPath = '.') -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir(dirpath: FsPath = ".") -> Iterable[DirEntry[AnyStr]]:
    """Typed version of os.scandir"""
    if not isdir(dirpath):
        raise NotADirectoryError(f"{dirpath} is not a directory")
    return cast("Iterable[DirEntry[AnyStr]]", _scandir(fspath(dirpath)))

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

Name	Type	Description	Default
fspath	FsPath	(FsPath): dirpath to look through	'.'
recursive	bool	recursively scan the directory	False
follow_symlinks	bool	follow symlinks when checking for dirs and files	True
files	bool	include files	True
dirs	bool	include directories	True
symlinks	bool	include symlinks	True
dirs_only	bool	only include directories	False
files_only	bool	only include files	False
symlinks_only	bool	only include symlinks	False

Returns:

Type	Description
Iterator[DirEntry[str]]	Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]]:
    r"""Return an iterator of os.DirEntry objects

    Args:
        fspath: (FsPath): dirpath to look through
        recursive (bool): recursively scan the directory
        follow_symlinks (bool): follow symlinks when checking for dirs and files
        files (bool): include files
        dirs (bool): include directories
        symlinks (bool): include symlinks
        dirs_only (bool): only include directories
        files_only (bool): only include files
        symlinks_only (bool): only include symlinks

    Returns:
        Iterator[DirEntry]: Iterator of os.DirEntry objects

    Raises:
        ValueError: if any of the kwargs (`dirs`, `files` and `symlinks`) are not True

    """
    if not recursive:
        return scandir_gen_filter(
            scandir(fspath),
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )

    return scandir_gen_filter(
        chain(
            scandir(fspath),
            *(
                scandir_gen(
                    el.path,
                    recursive=True,
                    follow_symlinks=follow_symlinks,
                    files=files,
                    dirs=True,
                    symlinks=symlinks,
                    files_only=files_only,
                    dirs_only=dirs_only,
                    symlinks_only=symlinks_only,
                )
                for el in scandir(fspath)
                if el.is_dir(follow_symlinks=follow_symlinks)
            ),
        ),
        follow_symlinks=follow_symlinks,
        files=files,
        dirs=dirs,
        symlinks=symlinks,
        files_only=files_only,
        dirs_only=dirs_only,
        symlinks_only=symlinks_only,
    )

shellfish.scandir_list(dirpath: FsPath = '.') -> List[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Dirpath to scan	'.'

Returns:

Type	Description
List[DirEntry[AnyStr]]	List[DirEntry]: List of os.DirEntry objects

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir_list(dirpath: FsPath = ".") -> List[DirEntry[AnyStr]]:
    """Return a list of os.DirEntry objects

    Args:
        dirpath: Dirpath to scan

    Returns:
        List[DirEntry]: List of os.DirEntry objects

    """
    return list(scandir(dirpath))

shellfish.seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]

Return hr-time Tuple[int, int] (seconds, nanoseconds)

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
Tuple[int, int]	Tuple[int, int]: (seconds, nanoseconds)

Source code in libs/shellfish/shellfish/sh.py

def seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]:
    """Return hr-time Tuple[int, int] (seconds, nanoseconds)

    Args:
        seconds (float): number of seconds

    Returns:
        Tuple[int, int]: (seconds, nanoseconds)

    """
    _sec, _ns = divmod(int(seconds * 1_000_000_000), 1_000_000_000)
    return _sec, _ns

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

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_join(path_strings: Iterator[str]) -> str:
    """Join iterable of strings on the current platform os.path.sep value"""
    return sep.join(path_strings)

shellfish.sep_lstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_lstrip(fspath: FsPath) -> str:
    """Left-strip a string of the current platform's os.path.sep value"""
    return str(fspath).lstrip(sep)

shellfish.sep_rstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_rstrip(fspath: FsPath) -> str:
    """Right-strip a string of the current platform's os.path.sep value"""
    return str(fspath).rstrip(sep)

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

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_split(fspath: FsPath) -> Tuple[str, ...]:
    """Split a string on the current platform os.path.sep value"""
    return tuple(el for el in str(fspath).split(sep) if el != sep and el != "")

shellfish.sep_strip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_strip(fspath: FsPath) -> str:
    """Strip a string of the current platform's os.path.sep value"""
    return str(fspath).strip(sep)

shellfish.setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Returns:

Type	Description
Tuple[str, str]	Tuple[str, str]: environment variable key/value pair

Source code in libs/shellfish/shellfish/sh.py

def setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Returns:
        Tuple[str, str]: environment variable key/value pair

    """
    return export(key=key, val=val)

shellfish.shebang(fspath: FsPath) -> Union[None, str]

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file that might have a shebang	required

Returns:

Type	Description
Union[None, str]	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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def shebang(fspath: FsPath) -> Union[None, str]:
    r"""Get the shebang string given a fspath; Returns None if no shebang

    Args:
        fspath (FsPath): Path to file that might have a shebang

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

    """
    with open(fspath) as f:
        first = f.readline().replace("\r\n", "\n").strip("\n")
        return first if "#!" in first[:2] else None

shellfish.shell(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, shell: bool = True, extenv: bool = True, cwd: Optional[FsPath] = None, check: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously in current shell

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
shell	bool	Run in shell or sub-shell; default is True for shx	True
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check if ok	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

def shell(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    shell: bool = True,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    check: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously in current shell

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        shell: Run in shell or sub-shell; default is True for `shx`
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check if ok
        dryrun: Don't run the subprocess


    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return do(
        *popenargs,
        args=args,
        shell=shell,
        env=env,
        extenv=extenv,
        cwd=cwd,
        check=check,
        verbose=verbose,
        input=input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]

Typed alias for shlex.split

Source code in libs/shellfish/shellfish/sh.py

def shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]:
    """Typed alias for shlex.split"""
    return _shplit(string, comments=comments, posix=posix)

shellfish.source(filepath: FsPath, _globals: bool = True) -> None

Execute/run a python file given a fspath and put globals in globasl

Parameters:

Name	Type	Description	Default
filepath	FsPath	Path to python file	required
_globals	bool	Exec using globals	True

Source code in libs/shellfish/shellfish/sh.py

def source(filepath: FsPath, _globals: bool = True) -> None:  # pragma: nocov
    """Execute/run a python file given a fspath and put globals in globasl

    Args:
        filepath (FsPath): Path to python file
        _globals (bool): Exec using globals

    """
    string = fs.lstring(str(filepath))
    if _globals:
        exec(string, globals())
    else:
        exec(string)

shellfish.stat(fspath: FsPath) -> os_stat_result

Return the os.stat_result object for a given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory	required

Returns:

Type	Description
stat_result	os.stat_result: stat_result object

Source code in libs/shellfish/shellfish/fs/__init__.py

def stat(fspath: FsPath) -> os_stat_result:
    """Return the os.stat_result object for a given fspath

    Args:
        fspath (FsPath): Path to file or directory

    Returns:
        os.stat_result: stat_result object

    """
    return _stat(_fspath(fspath))

shellfish.stat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

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

Create an empty file given a fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path for where to make an empty file	required
mkdirp	bool	Make parent directories if they don't exist	True

Source code in libs/shellfish/shellfish/fs/__init__.py

def touch(fspath: FsPath, *, mkdirp: bool = True) -> None:
    """Create an empty file given a fspath

    Args:
        fspath (FsPath): File-system path for where to make an empty file
        mkdirp (bool): Make parent directories if they don't exist

    """
    if not path.exists(str(fspath)):
        if mkdirp:
            parent_dir = path.dirname(str(fspath))
            if parent_dir:
                _makedirs(parent_dir, exist_ok=True)
        with open(fspath, "a"):
            utime(fspath, None)

shellfish.tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str

Create a directory tree string given a directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory string to make tree for	required
filterfn	Optional[Callable[[str], bool]]	Function to filter sub-directories and sub-files with	None

Returns:

Name	Type	Description
str	str	Directory-tree string

Examples:

>>> tmpdir = 'tree.doctest'
>>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
>>> from pathlib import Path
>>> 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"),
... ]
>>> 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)
...     Path(fspath).touch()
>>> print(tree(tmpdir))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── file1.txt
    ├── file2.txt
    └── file3.txt
>>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   └── file3.txt
    ├── file1.txt
    └── file3.txt
>>> from shutil import rmtree
>>> rmtree(tmpdir)

Source code in libs/shellfish/shellfish/sh.py

def tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str:
    """Create a directory tree string given a directory path

    Args:
        dirpath (FsPath): Directory string to make tree for
        filterfn: Function to filter sub-directories and sub-files with

    Returns:
        str: Directory-tree string

    Examples:
        >>> tmpdir = 'tree.doctest'
        >>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
        >>> from pathlib import Path
        >>> 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"),
        ... ]
        >>> 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)
        ...     Path(fspath).touch()
        >>> print(tree(tmpdir))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── file1.txt
            ├── file2.txt
            └── file3.txt
        >>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   └── file3.txt
            ├── file1.txt
            └── file3.txt
        >>> from shutil import rmtree
        >>> rmtree(tmpdir)

    """
    return "\n".join(
        p.displayable() for p in _DirTree.make_tree(Path(dirpath), filterfn=filterfn)
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield all paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        (
            str(path_string)
            if abspath
            else str(path_string).replace(dirpath, "").strip(sep)
        )
        for path_string in chain.from_iterable(
            (
                pwd,
                *(path.join(pwd, _file) for _file in files),
            )
            for pwd, dirs, files in walk(
                dirpath,
                topdown=topdown,
                followlinks=followlinks,
                onerror=onerror,
            )
        )
    )

shellfish.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = 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:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        filepath: fspath to write to
        bites: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

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

    """
    _write_mode = "ab" if append else "wb"
    with open(filepath, _write_mode) as fd:
        nbytes = fd.write(bites)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes

shellfish.wbytes_async(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.wbytes_gen(filepath: FsPath, bytes_gen: Iterable[bytes], append: bool = False, chmod: Optional[int] = None) -> int

Write/Save bytes to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Iterable[bytes]	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

>>> from shellfish.fs import rbytes, wbytes
>>> 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!')
>>> wbytes_gen(fspath, (b for b in bites_to_save))
35
>>> rbytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/Save bytes to a fspath

    Args:
        filepath: fspath to write to
        bytes_gen: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

    Examples:
        >>> from shellfish.fs import rbytes, wbytes
        >>> 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!')
        >>> wbytes_gen(fspath, (b for b in bites_to_save))
        35
        >>> rbytes(fspath)
        b'These are some bytes... more bytes!'
        >>> import os; os.remove(fspath)

    """
    _mode = const.ab if append else const.wb
    with open(filepath, mode=_mode) as fd:
        nbytes_written = sum(fd.write(chunk) for chunk in bytes_gen)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes_written

shellfish.wbytes_gen_async(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.where(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which; alias of shellfish.sh.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def where(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`; alias of shellfish.sh.which

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

shellfish.which(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def which(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return _which(cmd, path=path)

shellfish.which_lru(cmd: str, path: Optional[str] = None) -> Optional[str] cached

Return the result of shutil.which and cache the results

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

@lru_cache(maxsize=128)
def which_lru(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which` and cache the results

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

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

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Append a newline to the end of the file	False
default	Optional[Callable[[Any], Any]]	default function hook	None
chmod	Optional[int]	Optional chmod to set on file	None
append	bool	Append to the file if True, overwrite otherwise; default	False
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dumpb	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wjson(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    chmod: Optional[int] = None,
    append: bool = False,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Append a newline to the end of the file
        default: default function hook
        chmod (Optional[int]): Optional chmod to set on file
        append (bool): Append to the file if True, overwrite otherwise; default
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dumpb

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)


    """
    return wbytes(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        chmod=chmod,
        append=append,
    )

shellfish.wjson_async(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, append: bool = False, chmod: Optional[int] = None, **kwargs: Any) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Sort the data keys if the data is a dictionary.	False
default	Optional[Callable[[Any], Any]]	default function hook	None
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dump	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wjson_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    append: bool = False,
    chmod: Optional[int] = None,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Sort the data keys if the data is a dictionary.
        default: default function hook
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dump

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "wjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    return await wbytes_async(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        append=append,
        chmod=chmod,
    )

shellfish.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int

Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	String encoding to write file with	'utf-8'
append	bool	Flag to append to file; default = False	False
chmod	Optional[int]	Optional chmod to set on file	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wstring(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding: String encoding to write file with
        append (bool): Flag to append to file; default = False
        chmod (Optional[int]): Optional chmod to set on file

    Returns:
        None

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

    """
    return wbytes(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.wstring_async(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

Modules

shellfish.__about__

Package metadata/info

shellfish.__main__

pkg entry ~ python -m shellfish

Functions

shellfish.__main__.main() -> None

Print package metadata

Source code in libs/shellfish/shellfish/__main__.py

def main() -> None:
    """Print package metadata"""
    import json

    sys.stdout.write(
        json.dumps(
            {
                "package": __title__,
                "version": __version__,
                "pkgroot": __pkgroot__,
            },
            indent=2,
        )
    )

shellfish.aios

aios = asyncio + os

Classes

shellfish.aios.DirEntryAsync(dir_entry: os.DirEntry[AnyStr])

Bases: Generic[AnyStr]

DirEntryAsync os.DirEntry + async

Signature of os.DirEntry:

@final
class DirEntry(Generic[AnyStr]):
    # This is what the scandir iterator yields
    # The constructor is hidden

    @property
    def name(self) -> AnyStr: ...
    @property
    def path(self) -> AnyStr: ...
    def inode(self) -> int: ...
    def is_dir(self, *, follow_symlinks: bool = True) -> bool: ...
    def is_file(self, *, follow_symlinks: bool = True) -> bool: ...
    def is_symlink(self) -> bool: ...
    def stat(self, *, follow_symlinks: bool = True) -> stat_result: ...
    def __fspath__(self) -> AnyStr: ...
    if sys.version_info >= (3, 9):
        def __class_getitem__(cls, item: Any) -> GenericAlias: ...

Source code in libs/shellfish/shellfish/aios/__init__.py

def __init__(self, dir_entry: os.DirEntry[AnyStr]) -> None:
    self._dir_entry = dir_entry

Functions

shellfish.aios.scandir(path: AnyStr) -> AsyncIterator[DirEntryAsync[AnyStr]] async

Async version of os.scandir

Signature of os.scandir:

def scandir(path: AnyStr) -> Iterator[DirEntry[AnyStr]]: ...

Source code in libs/shellfish/shellfish/aios/__init__.py

async def scandir(path: AnyStr) -> AsyncIterator[DirEntryAsync[AnyStr]]:
    """Async version of os.scandir

    Signature of os.scandir:
        ```python
        def scandir(path: AnyStr) -> Iterator[DirEntry[AnyStr]]: ...
        ```
    """

    # for dir_entry in map(_dir_entry_async, os.scandir(path)):
    for dir_entry in (DirEntryAsync(el) for el in os.scandir(path)):
        yield dir_entry

shellfish.aioshutil

aios = asyncio + shutil

Functions

shellfish.batman

batman = bat/cmd windows utils

Functions

shellfish.batman.MKLINK(link: FsPath, target: FsPath, *, D: bool = False, H: bool = False, J: bool = False, check: bool = False) -> CompletedProcess[str]

Creates a symbolic link.

Returns:

Type	Description
CompletedProcess[str]	pass

Output of MKLINK /?:

MKLINK [[/D] | [/H] | [/J]] Link Target

        /D      Creates a directory symbolic link.  Default is a file
                symbolic link.
        /H      Creates a hard link instead of a symbolic link.
        /J      Creates a Directory Junction.
        Link    Specifies the new symbolic link name.
        Target  Specifies the path (relative or absolute) that the new link
                refers to.

Source code in libs/shellfish/shellfish/batman.py

def MKLINK(
    link: FsPath,
    target: FsPath,
    *,
    D: bool = False,
    H: bool = False,
    J: bool = False,
    check: bool = False,
) -> CompletedProcess[str]:
    """
    Creates a symbolic link.

    Returns:
        pass

    Output of `MKLINK /?`:
        ```
        MKLINK [[/D] | [/H] | [/J]] Link Target

                /D      Creates a directory symbolic link.  Default is a file
                        symbolic link.
                /H      Creates a hard link instead of a symbolic link.
                /J      Creates a Directory Junction.
                Link    Specifies the new symbolic link name.
                Target  Specifies the path (relative or absolute) that the new link
                        refers to.

        ```

    """
    link = _fspath(Path(link))
    target = _fspath(Path(target))
    _args = _MKLINK(link, target, D=D, H=H, J=J)
    return run(args=_args, check=check, capture_output=True, text=True, shell=True)

shellfish.batman.MKLINK_OPT(D: bool = False, H: bool = False, J: bool = False) -> Union[str, None]

Return the appropriate /D, /H, or /J option for windows mklink

Parameters:

Name	Type	Description	Default
D	bool	mklink /D creates a directory symbolic link.	False
H	bool	mklink /H creates a hard link instead of a symbolic link.	False
J	bool	mklink /J creates a directory junction.	False

Returns:

Type	Description
Union[str, None]	Union[str, None]: The appropriate /D, /H, or /J option for windows mklink

Examples:

>>> MKLINK_OPT(D=True)
'/D'
>>> MKLINK_OPT(H=True)
'/H'
>>> MKLINK_OPT(J=True)
'/J'
>>> MKLINK_OPT()
>>> MKLINK_OPT(D=True, H=True)
Traceback (most recent call last):
...
ValueError: Only one of D, H, J can be True.  Got True, True, False

Source code in libs/shellfish/shellfish/batman.py

def MKLINK_OPT(D: bool = False, H: bool = False, J: bool = False) -> Union[str, None]:
    """Return the appropriate /D, /H, or /J option for windows mklink

    Args:
        D (bool): `mklink /D` creates a directory symbolic link.
        H (bool): `mklink /H` creates a hard link instead of a symbolic link.
        J (bool): `mklink /J` creates a directory junction.

    Returns:
        Union[str, None]: The appropriate /D, /H, or /J option for windows mklink

    Examples:
        >>> MKLINK_OPT(D=True)
        '/D'
        >>> MKLINK_OPT(H=True)
        '/H'
        >>> MKLINK_OPT(J=True)
        '/J'
        >>> MKLINK_OPT()
        >>> MKLINK_OPT(D=True, H=True)
        Traceback (most recent call last):
        ...
        ValueError: Only one of D, H, J can be True.  Got True, True, False

    """
    # Check that only one of D, H, J is True
    if sum((D, H, J)) > 1:
        raise ValueError(f"Only one of D, H, J can be True.  Got {D}, {H}, {J}")
    if D:
        return "/D"
    if H:
        return "/H"
    if J:
        return "/J"
    return None

shellfish.batman.RD(fspath: FsPath, *, S: bool = False, Q: bool = False, R: bool = False, P: bool = False, F: bool = False, X: bool = False, Y: bool = False, Z: bool = False, A: bool = False, check: bool = False) -> CompletedProcess[str]

Removes a directory.

Returns:

Type	Description
CompletedProcess[str]	pass

Output of RD /?:

RD [/S] [/Q] [/R] [/P] [/F] [/X] [/Y] [/Z] [/A] [Drive:]Path

        /S      Recursively removes subdirectories and files.
        /Q      Quiet.  Do not display progress messages.
        /R      Recursively removes subdirectories and files.
        /P      Prompts before each removal.
        /F      Do not display confirmation messages.
        /X      Do not display confirmation messages.
        /Y      Do not display confirmation messages.
        /Z      Do not display confirmation messages.
        /A      Do not display confirmation messages.
        Drive:  Specifies the drive or root directory of the path.
        Path    Specifies the path to be removed.

Source code in libs/shellfish/shellfish/batman.py

def RD(
    fspath: FsPath,
    *,
    S: bool = False,
    Q: bool = False,
    R: bool = False,
    P: bool = False,
    F: bool = False,
    X: bool = False,
    Y: bool = False,
    Z: bool = False,
    A: bool = False,
    check: bool = False,
) -> CompletedProcess[str]:
    """
    Removes a directory.

    Returns:
        pass


    Output of `RD /?`:
        ```
        RD [/S] [/Q] [/R] [/P] [/F] [/X] [/Y] [/Z] [/A] [Drive:]Path

                /S      Recursively removes subdirectories and files.
                /Q      Quiet.  Do not display progress messages.
                /R      Recursively removes subdirectories and files.
                /P      Prompts before each removal.
                /F      Do not display confirmation messages.
                /X      Do not display confirmation messages.
                /Y      Do not display confirmation messages.
                /Z      Do not display confirmation messages.
                /A      Do not display confirmation messages.
                Drive:  Specifies the drive or root directory of the path.
                Path    Specifies the path to be removed.

        ```

    """
    _args = _RD(fspath, S=S, Q=Q, R=R, P=P, F=F, X=X, Y=Y, Z=Z, A=A)
    return run(args=_args, check=check, capture_output=True, text=True, shell=True)

shellfish.batman.bat(fspath: FsPath, *, check: bool = False, text: bool = True, shell: bool = False) -> CompletedProcess[AnyStr]

Run a bat file

Source code in libs/shellfish/shellfish/batman.py

def bat(
    fspath: FsPath, *, check: bool = False, text: bool = True, shell: bool = False
) -> CompletedProcess[AnyStr]:
    """Run a bat file"""
    bat_filepath = which(fspath)
    if bat_filepath is None:
        fspath_obj = Path(fspath)
        if not fspath_obj.exists():
            raise FileNotFoundError(fspath)
    else:
        fspath_obj = Path(bat_filepath)
    return run(
        args=[str(fspath)] if shell else ["cmd", "/c", _fspath(fspath_obj)],
        capture_output=True,
        shell=shell,
        text=text,
        check=check,
        cwd=fspath_obj.parent,
    )

shellfish.const

Constants

shellfish.dev

UNDER CONSTRUCTION

Modules

shellfish.dev.do

Classes

shellfish.dev.do.Do(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

PRun => 'ProcessRun' for finished processes

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.dev.do.Do.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.dev.do.Do.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.dev.do.Do.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.dev.do.Do.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.dev.do.Do.__post_init__() -> Any

Function place holder that is called after object initialization

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def __post_init__(self) -> Any:
    """Function place holder that is called after object initialization"""

shellfish.dev.do.Do.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.dev.do.Do.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.dev.do.Do.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.dev.do.Do.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.dev.do.Do.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.dev.do.Do.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.dev.do.Do.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.dev.do.Do.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.dev.do.Do.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.dev.do.Do.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.dev.do.Do.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.dev.do.Do.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.dev.do.Do.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.dev.do.Do.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.dev.do.Do.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.dev.do.Do.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.dev.do.Do.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.dev.do.Do.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.dev.do.Do.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.dev.do.Do.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.dev.do.Do.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.dev.do.Do.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.dev.do.Do.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.dev.do.Do.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.dev.do.Do.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.dev.do.Do.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.dev.do.Do.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.dev.do.Do.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.dev.do.Do.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.dev.do.Do.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.dev.do.Do.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.dev.do.Do.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.dev.do.Do.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.dev.do.DoDict

Bases: TypedDict

Do dictionary

shellfish.dev.popen_gen

Classes Functions

shellfish.dev.popen_gen.popen_gen(*popenargs: Any, **popenkwargs: Any) -> Iterable[Tuple[Stdio, str]]

Create and open a subprocess and yield tuples with stdout/stderr lines

Parameters:

Name	Type	Description	Default
*popenargs	Any	Args to be passed to Popen	()
**popenkwargs	Any	Kwargs to be passed to Popen	{}

Yields:

Type	Description
Iterable[Tuple[Stdio, str]]	Tuple[str, str]: Tuples that are of the form ('stdout', stdout_line) or ('stderr', stderr_line) for the stdout and stderr lines for the subprocess created.

Source code in libs/shellfish/shellfish/dev/popen_gen.py

def popen_gen(*popenargs: Any, **popenkwargs: Any) -> Iterable[Tuple[Stdio, str]]:
    """Create and open a subprocess and yield tuples with stdout/stderr lines

    Args:
        *popenargs: Args to be passed to Popen
        **popenkwargs: Kwargs to be passed to Popen

    Yields:
        Tuple[str, str]: Tuples that are of the form ('stdout', stdout_line)
            or ('stderr', stderr_line) for the stdout and stderr lines for
            the subprocess created.

    """
    with Popen(*popenargs, **popenkwargs, stdout=PIPE, stderr=PIPE, text=True) as proc:  # type: ignore[call-overload]
        yield from popen_pipes_gen(proc)

shellfish.dev.popen_gen.popen_pipes_gen(proc: Popen[AnyStr], timeout: Optional[float] = None) -> Iterable[Tuple[Stdio, str]]

Yield stdout and stderr lines from a subprocess

Parameters:

Name	Type	Description	Default
proc	Popen	Popen process	required
timeout	Optional[float]	Timeout in seconds. Defaults to None.	None

Yields:

Type	Description
Iterable[Tuple[Stdio, str]]	Tuple[Stdio, str]: Tuples with stdio enum marker followed by a string

Raises:

Type	Description
ValueError	if proc is not Popen or proc.stdout or proc.stderr is None

Source code in libs/shellfish/shellfish/dev/popen_gen.py

def popen_pipes_gen(
    proc: Popen[AnyStr], timeout: Optional[float] = None
) -> Iterable[Tuple[Stdio, str]]:
    """Yield stdout and stderr lines from a subprocess

    Args:
        proc (Popen): Popen process
        timeout (Optional[float], optional): Timeout in seconds. Defaults to None.

    Yields:
        Tuple[Stdio, str]: Tuples with stdio enum marker followed by a string

    Raises:
        ValueError: if proc is not Popen or proc.stdout or proc.stderr is None

    """
    if not isinstance(proc, Popen):
        raise ValueError("proc must be a Popen object")
    _raise_err = False
    if proc.stdout is not None and proc.stderr is not None:
        ti = time()
        with ThreadPoolExecutor(2) as pool:
            q_stdout: Queue[AnyStr] = Queue()
            q_stderr: Queue[AnyStr] = Queue()
            _block = True
            stdout_future = pool.submit(
                _enqueue_output_iter_readline, proc.stdout, q_stdout, _block
            )
            stderr_future = pool.submit(
                _enqueue_output_iter_readline, proc.stderr, q_stderr, _block
            )
            while proc.poll() is None:
                try:
                    yield Stdio.stdout, q_stdout.get_nowait()
                except Empty:
                    pass
                try:
                    yield Stdio.stderr, q_stderr.get_nowait()
                except Empty:
                    pass
                if timeout is not None and time() - ti > timeout:
                    _raise_err = True
                    stdout_future.cancel()
                    stderr_future.cancel()
                    pool.shutdown(wait=False)
                    break
        if _raise_err and timeout is not None:
            proc.terminate()
            raise TimeoutExpired(proc.args, timeout, output=None, stderr=None)

    else:
        raise ValueError("proc.stdout and proc.stderr must be not None")

shellfish.dev.run_async

Classes

shellfish.dotenv

dot.env utils

Functions

shellfish.dotenv.ldotenv(fspath: Optional[FsPath] = None) -> Dict[str, str]

Load a dotenv file from a fspath and return the keyvalues as a dict

Examples:

>>> import os
>>> import shutil
>>> dot_env_list = ['a=1', 'ANOTHER=2']
>>> with open('.env.test', 'w') as f: f.write('\n'.join(dot_env_list))
13
>>> ldotenv('.env.test')
{'a': '1', 'ANOTHER': '2'}
>>> if os.path.exists('.env.test'): os.remove('.env.test')
>>> os.makedirs('env-test', exist_ok=True)
>>> with open(os.path.join('env-test', '.env'), 'w') as f: f.write('\n'.join(dot_env_list))
13
>>> ldotenv('env-test')
{'a': '1', 'ANOTHER': '2'}
>>> if os.path.exists('env-test'): shutil.rmtree('env-test')
>>> ldotenv('path/does/not/exist')
Traceback (most recent call last):
...
ValueError: Given fspath/dirpath does not exist: path/does/not/exist

Source code in libs/shellfish/shellfish/dotenv.py

def ldotenv(fspath: Optional[FsPath] = None) -> Dict[str, str]:
    r"""Load a dotenv file from a fspath and return the keyvalues as a dict

    Examples:
        >>> import os
        >>> import shutil
        >>> dot_env_list = ['a=1', 'ANOTHER=2']
        >>> with open('.env.test', 'w') as f: f.write('\n'.join(dot_env_list))
        13
        >>> ldotenv('.env.test')
        {'a': '1', 'ANOTHER': '2'}
        >>> if os.path.exists('.env.test'): os.remove('.env.test')
        >>> os.makedirs('env-test', exist_ok=True)
        >>> with open(os.path.join('env-test', '.env'), 'w') as f: f.write('\n'.join(dot_env_list))
        13
        >>> ldotenv('env-test')
        {'a': '1', 'ANOTHER': '2'}
        >>> if os.path.exists('env-test'): shutil.rmtree('env-test')
        >>> ldotenv('path/does/not/exist')
        Traceback (most recent call last):
        ...
        ValueError: Given fspath/dirpath does not exist: path/does/not/exist

    """
    if fspath:
        if path.isfile(str(fspath)):
            dotenv_string = _rstring(fspath)
            return parse_dotenv(dotenv_string)
        if path.isdir(str(fspath)):
            dotenv_filepath = path.join(str(fspath), ".env")
            if path.exists(dotenv_filepath):
                return ldotenv(dotenv_filepath)
        raise ValueError(f"Given fspath/dirpath does not exist: {str(fspath)}")
    return ldotenv(getcwd())

shellfish.dotenv.parse_dotenv(string: str) -> Dict[str, str]

Parse env string to dictionary

Examples:

>>> dot_env_list = ['a=1', 'ANOTHER=2']
>>> dotenv_string = '\n'.join(dot_env_list)
>>> parse_dotenv(dotenv_string)
{'a': '1', 'ANOTHER': '2'}

Source code in libs/shellfish/shellfish/dotenv.py

def parse_dotenv(string: str) -> Dict[str, str]:
    r"""Parse env string to dictionary

    Examples:
        >>> dot_env_list = ['a=1', 'ANOTHER=2']
        >>> dotenv_string = '\n'.join(dot_env_list)
        >>> parse_dotenv(dotenv_string)
        {'a': '1', 'ANOTHER': '2'}

    """
    return {
        key: " ".join(shplit(val))
        for key, _, val in (
            el.partition("=")
            for el in filter(
                None,
                strip_comments(string.replace("\r\n", "\n").strip("\n")).splitlines(
                    keepends=False
                ),
            )
        )
    }

shellfish.dotenv.parse_env(string: str) -> Dict[str, str]

Parse env string to dictionary

Examples:

>>> dot_env_list = ['a=1', 'ANOTHER=2']
>>> dotenv_string = '\n'.join(dot_env_list)
>>> parse_dotenv(dotenv_string)
{'a': '1', 'ANOTHER': '2'}

Source code in libs/shellfish/shellfish/dotenv.py

def parse_env(string: str) -> Dict[str, str]:
    r"""Parse env string to dictionary

    Examples:
        >>> dot_env_list = ['a=1', 'ANOTHER=2']
        >>> dotenv_string = '\n'.join(dot_env_list)
        >>> parse_dotenv(dotenv_string)
        {'a': '1', 'ANOTHER': '2'}

    """
    return parse_dotenv(string)

shellfish.dotenv.strip_comments(string: str) -> str

Remove comments from python/shell scripts given the script as a string

Parameters:

Name	Type	Description	Default
string	str	string with # comments	required

Returns:

Name	Type	Description
str	str	input string with comments striped out

Examples:

Here is an example of stripping comments from a python-ish script:

>>> python_script_ish = r'''# some encoding
... # this is a comment
... # this is another comment
... print('hello bob')
... print('hello bobert')  # bob is short for bobert
... '''
>>> a = strip_comments(python_script_ish)
>>> a.splitlines(keepends=False)
['', '', '', "print('hello bob')", "print('hello bobert')  "]

Here is an example of stripping comments from a bash/shell-ish script:

>>> bash_script_ish = r'''#!/bin/bash
... # this is a comment
... # this is another comment
... echo "hello"
... echo "hello again" # comment
... '''
>>> a = strip_comments(bash_script_ish)
>>> a.splitlines(keepends=False)
['', '', '', 'echo "hello"', 'echo "hello again" ']

Source code in libs/shellfish/shellfish/dotenv.py

def strip_comments(string: str) -> str:
    """Remove comments from python/shell scripts given the script as a string

    Args:
        string (str): string with `#` comments

    Returns:
        str: input string with comments striped out

    Examples:
        Here is an example of stripping comments from a python-ish script:

        >>> python_script_ish = r'''# some encoding
        ... # this is a comment
        ... # this is another comment
        ... print('hello bob')
        ... print('hello bobert')  # bob is short for bobert
        ... '''
        >>> a = strip_comments(python_script_ish)
        >>> a.splitlines(keepends=False)
        ['', '', '', "print('hello bob')", "print('hello bobert')  "]

        Here is an example of stripping comments from a bash/shell-ish script:

        >>> bash_script_ish = r'''#!/bin/bash
        ... # this is a comment
        ... # this is another comment
        ... echo "hello"
        ... echo "hello again" # comment
        ... '''
        >>> a = strip_comments(bash_script_ish)
        >>> a.splitlines(keepends=False)
        ['', '', '', 'echo "hello"', 'echo "hello again" ']

    """
    filelines = string.splitlines(keepends=False)
    comment_re = re.compile(r'(?:"(?:[^"\\]|\\.)*"|[^"#])*(#|$)')

    def _strip_comments_line(line: str) -> str:
        comment_re_match = comment_re.match(line)
        if comment_re_match:
            return line[: comment_re_match.start(1)]
        return line

    return "\n".join(_strip_comments_line(line) for line in filelines)

shellfish.echo

Echo/Print

Functions

shellfish.echo.echo(*objects: Any, sep: str = ' ', end: str = '\n', file: Optional[IO[str]] = None, flush: bool = False) -> None

Print/echo function

Args:
    *objects: Item(s) to print/echo
    sep: Separator to print with
    end: End of print suffix; defaults to `

` file: File like object to write to if not stdout flush: Flush the file after writing

Examples:
    >>> echo("shellfish")
    shellfish

Source code in libs/shellfish/shellfish/echo.py

def echo(
    *objects: Any,
    sep: str = " ",
    end: str = "\n",
    file: Optional[IO[str]] = None,
    flush: bool = False,
) -> None:
    """Print/echo function

    Args:
        *objects: Item(s) to print/echo
        sep: Separator to print with
        end: End of print suffix; defaults to `\n`
        file: File like object to write to if not stdout
        flush: Flush the file after writing

    Examples:
        >>> echo("shellfish")
        shellfish

    """
    print(*objects, sep=sep, end=end, file=file, flush=flush)

shellfish.exe

Exes/commands

Classes

shellfish.exe.ExeABC(cmd: str, subcmd: Optional[Union[Tuple[str, ...], List[str], str]] = None, abspath: Optional[str] = None, check: bool = False, cwd: Optional[FsPath] = None, env: Optional[Dict[str, str]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, shell: bool = False, timeout: Optional[Union[float, int]] = None, verbose: bool = False)

Source code in libs/shellfish/shellfish/exe.py

def __init__(
    self,
    cmd: str,
    subcmd: Optional[Union[Tuple[str, ...], List[str], str]] = None,
    abspath: Optional[str] = None,
    check: bool = False,
    cwd: Optional[FsPath] = None,
    env: Optional[Dict[str, str]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    shell: bool = False,
    timeout: Optional[Union[float, int]] = None,
    verbose: bool = False,
):
    self.cmd = cmd
    if subcmd is not None:
        self.subcmd = (subcmd,) if isinstance(subcmd, str) else tuple(subcmd)
    self.abspath = abspath
    self.env = env
    self.cwd = cwd
    self.shell = shell
    self.verbose = verbose
    self.timeout = timeout
    self.ok_code = (
        {
            ok_code,
        }
        if isinstance(ok_code, int)
        else set(ok_code)
    )
    self.check = check
    self.__post_init__()

Functions

shellfish.exe.ExeABC.__post_init__() -> None

Post-initialization

Source code in libs/shellfish/shellfish/exe.py

def __post_init__(self) -> None:
    """Post-initialization"""

shellfish.exe.ExeABC.which() -> str

Return the path to the exe

Source code in libs/shellfish/shellfish/exe.py

def which(self) -> str:
    """Return the path to the exe"""
    return self._which()

Functions

Modules

shellfish.fs

file-system utils

Classes

shellfish.fs.Stdio

Bases: IntEnum

Standard-io enum object

Functions

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

Change the access permissions of a file

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file to chmod	required
mode	int	Permissions mode as an int	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def chmod(fspath: FsPath, mode: int) -> None:
    """Change the access permissions of a file

    Args:
        fspath (FsPath): Path to file to chmod
        mode (int): Permissions mode as an int

    """
    return _chmod(path=str(fspath), mode=mode)

shellfish.fs.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:

Name	Type	Description	Default
src	str	Source fspath	required
dest	str	Destination fspath	required
dryrun	bool	Do not copy file if True just return the src and dest	False
mkdirp	bool	Create parent directories if they do not exist	False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source fspath
        dest (str): Destination fspath
        dryrun (bool): Do not copy file if True just return the src and dest
        mkdirp (bool): Create parent directories if they do not exist

    """
    _dest = Path(dest)
    if not dryrun and mkdirp:
        _dest.parent.mkdir(parents=mkdirp, exist_ok=True)
    elif not _dest.parent.exists() or not _dest.parent.is_dir():
        raise FileNotFoundError(f"Destination directory {_dest.parent} does not exist")
    if not dryrun:
        wbytes_gen(dest, lbytes_gen(src, blocksize=2**18))
        _copystat(src, dest, follow_symlinks=True)
    return (str(src), str(dest))

shellfish.fs.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:

Name	Type	Description	Default
src	str	Source directory/file to copy	required
dest	FsPath	Destination directory/file to copy	required
force	bool	Force the copy (like -f flag for cp in shell)	True
recursive	bool	Recursive copy (like -r flag for cp in shell)	False
r	bool	alias for recursive	False
f	bool	alias for force	True

Raises:

Type	Description
ValueError	If src is a directory and recursive and r are both False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source directory/file to copy
        dest: Destination directory/file to copy
        force: Force the copy (like -f flag for cp in shell)
        recursive: Recursive copy (like -r flag for cp in shell)
        r: alias for recursive
        f: alias for force

    Raises:
        ValueError: If src is a directory and recursive and r are both `False`

    """
    _recursive = recursive or r
    _force = force or f
    for _src in iglob(_fspath(src), recursive=True):
        _dest = dest
        if (path.exists(dest) and not _force) or _src == dest:
            return
        if path.isdir(_src) and not _recursive:
            raise ValueError("Source ({}) is directory; use r=True")
        if path.isfile(_src) and path.isdir(dest):
            _dest = path.join(dest, path.basename(_src))
        if path.isfile(_src) or path.islink(src):
            copy_file(_src, _dest)
        if path.isdir(_src):
            if not path.exists(dest):
                _makedirs(dest)
            copytree(src, dest, dirs_exist_ok=True)

shellfish.fs.dir_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dir_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isdir"""
    return isdir(fspath)

shellfish.fs.dir_exists_async(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

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

Yield all dirpaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all dirpaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in dirs_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield directory-paths beneath a dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        dirpath if abspath else str(dirpath).replace(dirpath, "").strip(sep)
        for dirpath in (
            pwd
            for pwd, dirs, files in walk(
                str(dirpath),
                onerror=onerror,
                topdown=topdown,
                followlinks=followlinks,
            )
        )
    )

shellfish.fs.exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise"""
    return path.exists(_fspath(fspath))

shellfish.fs.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'

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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'

    """
    if period:
        return "".join(Path(fspath).suffixes)
    return "".join(Path(fspath).suffixes).lstrip(".")

shellfish.fs.file_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isfile"""
    return isfile(fspath)

shellfish.fs.file_exists_async(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

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

Yield lines from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	File to yield lines from	required
keepends	bool	Flag to keep the ends of the file lines	True

Yields:

Type	Description
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 wstring
>>> wstring(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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_lines_gen(filepath: FsPath, keepends: bool = True) -> Iterable[str]:
    r"""Yield lines from a given fspath

    Args:
        filepath: File to yield lines from
        keepends: Flag to keep the ends of the file lines

    Yields:
        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 wstring
        >>> wstring(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)


    """
    with open(filepath) as f:
        if keepends:
            yield from (line for line in f)
        else:
            yield from (line.rstrip("\n").rstrip("\r\n") for line in f)

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

Compare 2 files for equality given their filepaths

Parameters:

Name	Type	Description	Default
left	FsPath	Filepath 1	required
right	FsPath	Filepath 2	required
shallow	bool	Check only size and modification time if True	True
blocksize	int	Chunk size to read files	65536

Returns:

Type	Description
bool	True if files are equal, False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool:
    """Compare 2 files for equality given their filepaths

    Args:
        left (FsPath): Filepath 1
        right (FsPath): Filepath 2
        shallow (bool): Check only size and modification time if True
        blocksize (int): Chunk size to read files

    Returns:
        True if files are equal, False otherwise

    """
    left_stat = stat(left)
    right_stat = stat(right)
    if (
        shallow
        and left_stat.st_size == right_stat.st_size
        and left_stat.st_mtime == right_stat.st_mtime
    ):
        return True
    if left_stat.st_size != right_stat.st_size:
        return False
    return not any(
        left_chunk != right_chunk
        for left_chunk, right_chunk in zip(
            rbytes_gen(left, blocksize=blocksize),
            rbytes_gen(right, blocksize=blocksize),
        )
    )

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in files_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.fs.filepath_mtimedelta_sec(filepath: FsPath) -> float

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_mtimedelta_sec(filepath: FsPath) -> float:
    """Return the seconds since the file(path) was last modified"""
    return time() - path.getmtime(_fspath(filepath))

shellfish.fs.files_dirs_gen(dirpath: FsPath = '.', *, abspath: bool = True, topdown: bool = True, onerror: Optional[Callable[[OSError], Any]] = 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:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath is a directory	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Tuple[Iterator[str], Iterator[str]]:
    r"""Return a files_gen() and a dirs_gen() in one swell-foop

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath is a directory

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

    """
    return files_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    ), dirs_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield file-paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        filepath if abspath else str(filepath).replace(dirpath, "").strip(sep)
        for filepath in (
            path.join(pwd, filename)
            for pwd, dirs, files in walk(
                str(dirpath),
                topdown=topdown,
                onerror=onerror,
                followlinks=followlinks,
            )
            for filename in files
        )
    )

shellfish.fs.filesize(fspath: FsPath) -> int

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath as a string or pathlib.Path object	required

Returns:

Name	Type	Description
int	int	size of the fspath in bytes

Source code in libs/shellfish/shellfish/fs/__init__.py

def filesize(fspath: FsPath) -> int:
    """Return the size of the given file(path) in bytes

    Args:
        fspath (FsPath): Filepath as a string or pathlib.Path object

    Returns:
        int: size of the fspath in bytes

    """
    return stat(fspath).st_size

shellfish.fs.filesize_async(fspath: FsPath) -> int async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def 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

    """
    _stat_res = await aios.stat(str(fspath))
    return _stat_res.st_size

shellfish.fs.fspath(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def fspath(fspath: FsPath) -> str:
    """Alias for os._fspath; returns fspath string for any type of path"""
    return _fspath(fspath)

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

Return an iterator of fspaths matching the given glob pattern

Parameters:

Name	Type	Description	Default
pattern	str	Glob pattern	required
recursive	bool	Recursively search directories if True	False
r	bool	Recursively search directories if True (Alias for recursive)	False

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def glob(pattern: str, *, recursive: bool = False, r: bool = False) -> Iterator[str]:
    """Return an iterator of fspaths matching the given glob pattern

    Args:
        pattern: Glob pattern
        recursive: Recursively search directories if True
        r: Recursively search directories if True (Alias for recursive)

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

    """
    return iglob(pattern, recursive=recursive or r)

shellfish.fs.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish.fs.is_dir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.fs.is_file(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_file(fspath: FsPath) -> bool:
    """Return True if the given path is a file; alias for isfile"""
    return isfile(fspath)

shellfish.fs.is_file_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.fs.is_link(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_link(fspath: FsPath) -> bool:
    """Return True if the given path is a link; alias for islink"""
    return islink(fspath)

shellfish.fs.is_link_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.fs.isdir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isdir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; False otherwise"""
    return path.isdir(_fspath(fspath))

shellfish.fs.isdir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.isfile(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isfile(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return path.isfile(_fspath(fspath))

shellfish.fs.isfile_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.islink(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def islink(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return path.islink(_fspath(fspath))

shellfish.fs.islink_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.fs.listdir_async(fspath: FsPath) -> List[str] async

Async version of os.listdir

Source code in libs/shellfish/shellfish/fs/_async.py

async def listdir_async(fspath: FsPath) -> List[str]:
    """Async version of `os.listdir`"""
    return await aios.listdir(_fspath(fspath))

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]:
    r"""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

    """
    _attr = "path" if abspath else "name"
    return (
        getattr(el, _attr)
        for el in scandir_gen(
            fspath,
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )
    )

shellfish.fs.lstat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

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

Make directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to create	required
parents	bool	Make parent dirs if True; do not make parent dirs if False	False
p	bool	Make parent dirs if True; do not make parent dirs if False (alias of parents)	False
exist_ok	bool	Throw error if directory exists and exist_ok is False	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdir(
    fspath: FsPath, *, parents: bool = False, p: bool = False, exist_ok: bool = False
) -> None:
    """Make directory at given fspath

    Args:
        fspath (FsPath): Directory path to create
        parents (bool): Make parent dirs if True; do not make parent dirs if False
        p (bool): Make parent dirs if True; do not make parent dirs if False (alias of parents)
        exist_ok (bool): Throw error if directory exists and exist_ok is False

    Returns:
         None

    """
    _parents = parents or p
    if _parents or exist_ok:
        return _makedirs(_fspath(fspath), exist_ok=_parents or exist_ok)
    return _mkdir(_fspath(fspath))

shellfish.fs.mkdirp(fspath: FsPath) -> None

Make directory and parents

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdirp(fspath: FsPath) -> None:
    """Make directory and parents"""
    return mkdir(fspath=fspath, parents=True)

shellfish.fs.move(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def move(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    _dst_str = str(dest)
    for file in iglob(str(src), recursive=True):
        _move(file, _dst_str)

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in walk_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.fs.rbytes(filepath: FsPath) -> bytes

Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes(filepath: FsPath) -> bytes:
    """Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    with open(filepath, "rb") as file:
        return bytes(file.read())

shellfish.fs.rbytes_async(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.fs.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]

Yield bytes from a given fspath

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]:
    """Yield bytes from a given fspath"""
    with open(filepath, "rb") as f:
        while True:
            data = f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.rbytes_gen_async(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.rjson(filepath: FsPath) -> Any

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def rjson(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)

    """
    return JSON.loads(lstring(filepath=filepath))

shellfish.fs.rjson_async(filepath: FsPath) -> Any async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rjson_async(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    json_string = await rbytes_async(filepath)
    return JSON.loads(json_string)

shellfish.fs.rm(fspath: FsPath, *, force: bool = False, recursive: bool = False, dryrun: bool = False, verbose: bool = False) -> Union[List[str], None]

Remove files & directories in the style of the shell Args: fspath (FsPath): Path to file or directory to remove force (bool): ignore errors and missing files/dirs; default is False recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    dryrun: bool = False,
    verbose: bool = False,
) -> Union[List[str], None]:
    """Remove files & directories in the style of the shell
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): ignore errors and missing files/dirs; default is False
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if verbose:
        return list(
            rm_gen(fspath=fspath, force=force, recursive=recursive, dryrun=dryrun)
        )
    else:
        exhaust(rm_gen(fspath=fspath, force=force, recursive=recursive, dryrun=dryrun))
        return None

shellfish.fs.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 Args: fspath (FsPath): Path to file or directory to remove force (bool): Force removal of files and directories recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Force removal of files and directories
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if has_magic(str(fspath)):
        if dryrun:
            yield from iglob(_fspath(fspath), recursive=recursive)
        else:
            for _path_str in iglob(str(fspath), recursive=recursive):
                if isfile(_path_str):
                    remove(_path_str)
                elif recursive:
                    rmdir(_path_str, recursive=True, force=force)
                else:
                    raise ValueError(
                        f"{str(_path_str)} (under {str(fspath)}) is a directory -- use r=True or recursive=True"
                    )
    else:
        if isfile(fspath):
            if not dryrun:
                remove(_fspath(fspath))
            yield _fspath(fspath)
        elif recursive:
            if not dryrun:
                rmdir(fspath, force=force, recursive=True)
            yield _fspath(fspath)
        else:
            raise ValueError(
                f"{str(fspath)} is a directory -- use r=True or recursive=True"
            )

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

Remove directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to remove	required
force	bool	Force removal of files and directories	False
recursive	bool	Recursively remove all contents if True	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmdir(fspath: FsPath, *, force: bool = False, recursive: bool = False) -> None:
    """Remove directory at given fspath

    Args:
        fspath (FsPath): Directory path to remove
        force (bool): Force removal of files and directories
        recursive (bool): Recursively remove all contents if True

    Returns:
        None

    """
    if force:
        try:
            return rmdir(fspath, recursive=recursive)
        except FileNotFoundError:
            return
    if recursive:
        return rmtree(_fspath(fspath))
    return _rmdir(_fspath(fspath))

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

Remove a file at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath to remove	required
dryrun	bool	Do not remove file if True	False

Returns:

Type	Description
str	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmfile(fspath: FsPath, *, dryrun: bool = False) -> str:
    """Remove a file at given fspath

    Args:
        fspath (FsPath): Filepath to remove
        dryrun (bool): Do not remove file if True

    Returns:
        None

    """
    if not dryrun:
        remove(_fspath(fspath))
    return _fspath(fspath)

shellfish.fs.rstring(filepath: FsPath, *, encoding: str = 'utf-8') -> str

Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	Encoding to use for reading the file	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rstring(filepath: FsPath, *, encoding: str = "utf-8") -> str:
    r"""Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding: Encoding to use for reading the file

    Returns:
        str: String read from given fspath

    Examples:
        ``` python
        >>> from shellfish.fs import rstring, wstring
        >>> fspath = "lstring.doctest.txt"
        >>> sstring(fspath, r'Check out this string')
        21
        >>> lstring(fspath)
        'Check out this string'
        >>> import os; os.remove(fspath)

        ```

    """
    _bytes = rbytes(filepath=filepath)
    try:
        return _bytes.decode(encoding=encoding)
    except UnicodeDecodeError:  # Catch the unicode decode error
        pass
    return _bytes.decode(encoding="latin2")

shellfish.fs.rstring_async(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.fs.safepath(fspath: FsPath) -> str

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	file-system path; file or directory path string or Path obj	required

Returns:

Name	Type	Description
str	str	file/dir path that does not exist and contains the given path

Source code in libs/shellfish/shellfish/fs/__init__.py

def safepath(fspath: FsPath) -> str:
    """Check if a file/dir path is save/unused; returns an unused path.

    Args:
        fspath: file-system path; file or directory path string or Path obj

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

    """
    path_str = str(fspath)
    if path.exists(path_str):
        f_bn, f_ext = path.splitext(path_str)
        for n in count(1):
            safe_save_path = f"{f_bn}_{str(n).zfill(3)}.{f_ext}"
            if not path.exists(safe_save_path):
                return safe_save_path
    return path_str

shellfish.fs.scandir(dirpath: FsPath = '.') -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir(dirpath: FsPath = ".") -> Iterable[DirEntry[AnyStr]]:
    """Typed version of os.scandir"""
    if not isdir(dirpath):
        raise NotADirectoryError(f"{dirpath} is not a directory")
    return cast("Iterable[DirEntry[AnyStr]]", _scandir(fspath(dirpath)))

shellfish.fs.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:

Name	Type	Description	Default
fspath	FsPath	(FsPath): dirpath to look through	'.'
recursive	bool	recursively scan the directory	False
follow_symlinks	bool	follow symlinks when checking for dirs and files	True
files	bool	include files	True
dirs	bool	include directories	True
symlinks	bool	include symlinks	True
dirs_only	bool	only include directories	False
files_only	bool	only include files	False
symlinks_only	bool	only include symlinks	False

Returns:

Type	Description
Iterator[DirEntry[str]]	Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]]:
    r"""Return an iterator of os.DirEntry objects

    Args:
        fspath: (FsPath): dirpath to look through
        recursive (bool): recursively scan the directory
        follow_symlinks (bool): follow symlinks when checking for dirs and files
        files (bool): include files
        dirs (bool): include directories
        symlinks (bool): include symlinks
        dirs_only (bool): only include directories
        files_only (bool): only include files
        symlinks_only (bool): only include symlinks

    Returns:
        Iterator[DirEntry]: Iterator of os.DirEntry objects

    Raises:
        ValueError: if any of the kwargs (`dirs`, `files` and `symlinks`) are not True

    """
    if not recursive:
        return scandir_gen_filter(
            scandir(fspath),
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )

    return scandir_gen_filter(
        chain(
            scandir(fspath),
            *(
                scandir_gen(
                    el.path,
                    recursive=True,
                    follow_symlinks=follow_symlinks,
                    files=files,
                    dirs=True,
                    symlinks=symlinks,
                    files_only=files_only,
                    dirs_only=dirs_only,
                    symlinks_only=symlinks_only,
                )
                for el in scandir(fspath)
                if el.is_dir(follow_symlinks=follow_symlinks)
            ),
        ),
        follow_symlinks=follow_symlinks,
        files=files,
        dirs=dirs,
        symlinks=symlinks,
        files_only=files_only,
        dirs_only=dirs_only,
        symlinks_only=symlinks_only,
    )

shellfish.fs.scandir_list(dirpath: FsPath = '.') -> List[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Dirpath to scan	'.'

Returns:

Type	Description
List[DirEntry[AnyStr]]	List[DirEntry]: List of os.DirEntry objects

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir_list(dirpath: FsPath = ".") -> List[DirEntry[AnyStr]]:
    """Return a list of os.DirEntry objects

    Args:
        dirpath: Dirpath to scan

    Returns:
        List[DirEntry]: List of os.DirEntry objects

    """
    return list(scandir(dirpath))

shellfish.fs.sep_join(path_strings: Iterator[str]) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_join(path_strings: Iterator[str]) -> str:
    """Join iterable of strings on the current platform os.path.sep value"""
    return sep.join(path_strings)

shellfish.fs.sep_lstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_lstrip(fspath: FsPath) -> str:
    """Left-strip a string of the current platform's os.path.sep value"""
    return str(fspath).lstrip(sep)

shellfish.fs.sep_rstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_rstrip(fspath: FsPath) -> str:
    """Right-strip a string of the current platform's os.path.sep value"""
    return str(fspath).rstrip(sep)

shellfish.fs.sep_split(fspath: FsPath) -> Tuple[str, ...]

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_split(fspath: FsPath) -> Tuple[str, ...]:
    """Split a string on the current platform os.path.sep value"""
    return tuple(el for el in str(fspath).split(sep) if el != sep and el != "")

shellfish.fs.sep_strip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_strip(fspath: FsPath) -> str:
    """Strip a string of the current platform's os.path.sep value"""
    return str(fspath).strip(sep)

shellfish.fs.shebang(fspath: FsPath) -> Union[None, str]

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file that might have a shebang	required

Returns:

Type	Description
Union[None, str]	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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def shebang(fspath: FsPath) -> Union[None, str]:
    r"""Get the shebang string given a fspath; Returns None if no shebang

    Args:
        fspath (FsPath): Path to file that might have a shebang

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

    """
    with open(fspath) as f:
        first = f.readline().replace("\r\n", "\n").strip("\n")
        return first if "#!" in first[:2] else None

shellfish.fs.stat(fspath: FsPath) -> os_stat_result

Return the os.stat_result object for a given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory	required

Returns:

Type	Description
stat_result	os.stat_result: stat_result object

Source code in libs/shellfish/shellfish/fs/__init__.py

def stat(fspath: FsPath) -> os_stat_result:
    """Return the os.stat_result object for a given fspath

    Args:
        fspath (FsPath): Path to file or directory

    Returns:
        os.stat_result: stat_result object

    """
    return _stat(_fspath(fspath))

shellfish.fs.stat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

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

Create an empty file given a fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path for where to make an empty file	required
mkdirp	bool	Make parent directories if they don't exist	True

Source code in libs/shellfish/shellfish/fs/__init__.py

def touch(fspath: FsPath, *, mkdirp: bool = True) -> None:
    """Create an empty file given a fspath

    Args:
        fspath (FsPath): File-system path for where to make an empty file
        mkdirp (bool): Make parent directories if they don't exist

    """
    if not path.exists(str(fspath)):
        if mkdirp:
            parent_dir = path.dirname(str(fspath))
            if parent_dir:
                _makedirs(parent_dir, exist_ok=True)
        with open(fspath, "a"):
            utime(fspath, None)

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield all paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        (
            str(path_string)
            if abspath
            else str(path_string).replace(dirpath, "").strip(sep)
        )
        for path_string in chain.from_iterable(
            (
                pwd,
                *(path.join(pwd, _file) for _file in files),
            )
            for pwd, dirs, files in walk(
                dirpath,
                topdown=topdown,
                followlinks=followlinks,
                onerror=onerror,
            )
        )
    )

shellfish.fs.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = 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:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        filepath: fspath to write to
        bites: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

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

    """
    _write_mode = "ab" if append else "wb"
    with open(filepath, _write_mode) as fd:
        nbytes = fd.write(bites)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes

shellfish.fs.wbytes_async(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.fs.wbytes_gen(filepath: FsPath, bytes_gen: Iterable[bytes], append: bool = False, chmod: Optional[int] = None) -> int

Write/Save bytes to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Iterable[bytes]	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

>>> from shellfish.fs import rbytes, wbytes
>>> 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!')
>>> wbytes_gen(fspath, (b for b in bites_to_save))
35
>>> rbytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/Save bytes to a fspath

    Args:
        filepath: fspath to write to
        bytes_gen: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

    Examples:
        >>> from shellfish.fs import rbytes, wbytes
        >>> 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!')
        >>> wbytes_gen(fspath, (b for b in bites_to_save))
        35
        >>> rbytes(fspath)
        b'These are some bytes... more bytes!'
        >>> import os; os.remove(fspath)

    """
    _mode = const.ab if append else const.wb
    with open(filepath, mode=_mode) as fd:
        nbytes_written = sum(fd.write(chunk) for chunk in bytes_gen)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes_written

shellfish.fs.wbytes_gen_async(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.fs.wjson(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, chmod: Optional[int] = None, append: bool = False, **kwargs: Any) -> int

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Append a newline to the end of the file	False
default	Optional[Callable[[Any], Any]]	default function hook	None
chmod	Optional[int]	Optional chmod to set on file	None
append	bool	Append to the file if True, overwrite otherwise; default	False
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dumpb	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wjson(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    chmod: Optional[int] = None,
    append: bool = False,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Append a newline to the end of the file
        default: default function hook
        chmod (Optional[int]): Optional chmod to set on file
        append (bool): Append to the file if True, overwrite otherwise; default
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dumpb

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)


    """
    return wbytes(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        chmod=chmod,
        append=append,
    )

shellfish.fs.wjson_async(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, append: bool = False, chmod: Optional[int] = None, **kwargs: Any) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Sort the data keys if the data is a dictionary.	False
default	Optional[Callable[[Any], Any]]	default function hook	None
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dump	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wjson_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    append: bool = False,
    chmod: Optional[int] = None,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Sort the data keys if the data is a dictionary.
        default: default function hook
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dump

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "wjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    return await wbytes_async(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        append=append,
        chmod=chmod,
    )

shellfish.fs.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int

Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	String encoding to write file with	'utf-8'
append	bool	Flag to append to file; default = False	False
chmod	Optional[int]	Optional chmod to set on file	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wstring(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding: String encoding to write file with
        append (bool): Flag to append to file; default = False
        chmod (Optional[int]): Optional chmod to set on file

    Returns:
        None

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

    """
    return wbytes(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.fs.wstring_async(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

Modules

shellfish.fs.promises

shellfish.fs.promises

Functions

shellfish.fs.promises.dir_exists(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.promises.file_exists(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.promises.is_dir(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.fs.promises.is_file(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.fs.promises.is_link(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.fs.promises.isdir(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.promises.isfile(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.promises.islink(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.fs.promises.lstat(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

shellfish.fs.promises.rbytes(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.fs.promises.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.promises.rstring(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.fs.promises.stat(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

shellfish.fs.promises.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.fs.promises.wbytes_gen(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.fs.promises.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.libhash

Classes

shellfish.libhash.Hashed(b: bytes, s: str, __slots__=('b', 's')) dataclass

Hashed Result

Functions

shellfish.libhash.hash_bytes_gen(it: Iterator[bytes], hashlike: HashLike) -> str

Return the hash of an iterator of bytes

Parameters:

Name	Type	Description	Default
it	Iterator[bytes]	Iterator of bytes	required
hashlike	hash	Hash like object; can be a string or a '_Hash' object	required

Returns:

Name	Type	Description
str	str	Hash of the iterator

Source code in libs/shellfish/shellfish/libhash.py

def hash_bytes_gen(it: Iterator[bytes], hashlike: HashLike) -> str:
    """Return the hash of an iterator of bytes

    Args:
        it (Iterator[bytes]): Iterator of bytes
        hashlike (hash): Hash like object; can be a string or a '_Hash' object

    Returns:
        str: Hash of the iterator

    """
    _hasher = hasher(hashlike)
    for chunk in it:
        _hasher.update(chunk)
    return _hasher.hexdigest()

shellfish.libhash.hasher(obj: HashLike) -> '_Hash'

Return a hash object from a string or a hash object

Parameters:

Name	Type	Description	Default
obj	Union[str, hash]	String or hash object	required

Returns:

Name	Type	Description
hash	'_Hash'	Hash object

Examples:

>>> hashobj = hasher("sha256")
>>> hashobj.update(b"Hello World")
>>> hashobj.hexdigest()
'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'

Source code in libs/shellfish/shellfish/libhash.py

def hasher(obj: HashLike) -> "_Hash":
    """Return a hash object from a string or a hash object

    Args:
        obj (Union[str, hash]): String or hash object

    Returns:
        hash: Hash object

    Examples:
        >>> hashobj = hasher("sha256")
        >>> hashobj.update(b"Hello World")
        >>> hashobj.hexdigest()
        'a591a6d40bf420404a011733cfb7b190d62c65bf0bcda32b57b277d9ad9f146e'

    """
    if isinstance(obj, str):
        return string2hasher(obj)
    return obj

shellfish.libhash.string2hasher(string: str) -> '_Hash'

Return a hash object from a string

Parameters:

Name	Type	Description	Default
string	str	String to hash	required

Returns:

Name	Type	Description
hash	'_Hash'	Hash object

Source code in libs/shellfish/shellfish/libhash.py

def string2hasher(string: str) -> "_Hash":
    """Return a hash object from a string

    Args:
        string (str): String to hash

    Returns:
        hash: Hash object

    """
    try:
        return _HASHERS[string]()
    except KeyError:
        raise ValueError(
            f"Invalid hash algorithm: {string} (valid: {list(_HASHERS.keys())})"
        ) from None

shellfish.libsh

shellfish internals

Modules

shellfish.libsh.args

Functions

shellfish.libsh.args.arganystr(string: AnyStr) -> AnyStr

Return given string with quotes if needed

Examples:

>>> arganystr("a b")
"'a b'"
>>> arganystr("a b c")
"'a b c'"
>>> arganystr(b"a b")
b"'a b'"

Source code in libs/shellfish/shellfish/libsh/args.py

def arganystr(string: AnyStr) -> AnyStr:
    """Return given string with quotes if needed

    Examples:
        >>> arganystr("a b")
        "'a b'"
        >>> arganystr("a b c")
        "'a b c'"
        >>> arganystr(b"a b")
        b"'a b'"

    """
    if isinstance(string, bytes):
        return arganystr(string.decode()).encode()
    return _quote(string) if " " in string else string

shellfish.libsh.args.args2cmd(args: PopenArgs) -> Union[str, bytes]

Return single command string from given popenargs

Examples:

>>> args2cmd(["ls", "-l"])
'ls -l'
>>> args2cmd(["ls", "-l", "a b"])
"ls -l 'a b'"
>>> args2cmd(["ls", "-l", "a b", "c d"])
"ls -l 'a b' 'c d'"

Source code in libs/shellfish/shellfish/libsh/args.py

def args2cmd(args: PopenArgs) -> Union[str, bytes]:
    """Return single command string from given popenargs

    Examples:
        >>> args2cmd(["ls", "-l"])
        'ls -l'
        >>> args2cmd(["ls", "-l", "a b"])
        "ls -l 'a b'"
        >>> args2cmd(["ls", "-l", "a b", "c d"])
        "ls -l 'a b' 'c d'"

    """
    return (
        args
        if isinstance(args, (bytes, str))
        else " ".join(map(argstr, map(str, flatten_args(args))))
    )

shellfish.libsh.args.argstr(string: Union[str, bytes]) -> str

Return given string with quotes if needed

Examples:

>>> argstr("a b")
"'a b'"
>>> argstr("a b c")
"'a b c'"
>>> argstr(b"a b")
"'a b'"

Source code in libs/shellfish/shellfish/libsh/args.py

def argstr(string: Union[str, bytes]) -> str:
    """Return given string with quotes if needed

    Examples:
        >>> argstr("a b")
        "'a b'"
        >>> argstr("a b c")
        "'a b c'"
        >>> argstr(b"a b")
        "'a b'"

    """
    return arganystr(string if isinstance(string, str) else string.decode())

shellfish.libsh.args.flatten_args(*args: PopenArgs) -> List[str]

Flatten possibly nested iterables of sequences to a list of strings

Examples:

>>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
['cmd', 'uno', 'dos', 'tres']
>>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
['cmd', 'uno', 'dos', 'tres', '4444', 'five']

Source code in libs/shellfish/shellfish/libsh/args.py

def flatten_args(*args: PopenArgs) -> List[str]:
    """Flatten possibly nested iterables of sequences to a list of strings

    Examples:
        >>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
        ['cmd', 'uno', 'dos', 'tres']
        >>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
        ['cmd', 'uno', 'dos', 'tres', '4444', 'five']

    """
    return list(_flatten_strings(args))  # type: ignore[arg-type]

shellfish.osfs

Os specific filesystem utils/operations

Classes

shellfish.osfs.LIN

Bases: OsFsAbc

Linux (and Mac) shell commands/methods container

Functions

shellfish.osfs.LIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	str	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (str): Allow link to exist

    """
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.osfs.LIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): Allow link to exist

    """
    for link, target in link_target_tuples:
        LIN.link_dir(link, target, exist_ok=exist_ok)

shellfish.osfs.LIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	Allow links to already exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): Allow links to already exist

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.osfs.LIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
exist_ok	bool	Allow links to already exist	False
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        exist_ok (bool): Allow links to already exist
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.

    """
    for link, target in link_target_tuples:
        LIN.link_file(link, target, exist_ok=exist_ok)

shellfish.osfs.LIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.osfs.LIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_dir(link)

shellfish.osfs.LIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.osfs.LIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_file(link)

shellfish.osfs.OsFsAbc

Bases: ABC

Abstract base class for OS-specific fns

shellfish.osfs.WIN

Bases: OsFsAbc

Windows shell commands/methods container

Functions

shellfish.osfs.WIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, do not raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, do not raise an exception if the link exists

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath, target_is_directory=True)
    except OSError:
        batman.MKLINK(
            linkpath,
            targetpath,
            D=True,
        )

shellfish.osfs.WIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, do not raise an exception if the link(s) exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, do not raise an exception if the link(s) exist

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_dir(link, target, exist_ok=exist_ok)
    except OSError:
        args = [
            batman.MKLINK_ARGS(link, target, D=True)
            for link, target in link_target_tuples
            if WIN._check_link_target_dirs(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in args])

shellfish.osfs.WIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        symlink(targetpath, linkpath)
    except OSError:
        makedirs(path.split(linkpath)[0], exist_ok=True)
        batman.MKLINK(
            linkpath,
            targetpath,
        )

shellfish.osfs.WIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_file(link, target, exist_ok=exist_ok)
    except OSError:
        link_target_tuples = list(link_target_tuples)
        _args = [
            batman.MKLINK_ARGS(link, target, D=False)
            for link, target in link_target_tuples
            if WIN._check_link_target_files(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in _args])

shellfish.osfs.WIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.RD(link)

shellfish.osfs.WIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_dir(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            commands=[batman.RD_ARGS(link) for link in links]
        )

shellfish.osfs.WIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link (str): path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.DEL(link)

shellfish.osfs.WIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_file(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            [batman.DEL_ARGS(link) for link in links],
        )

Modules

shellfish.process

Current running process info

Classes

shellfish.process.Env

Env with attr access

Examples:

>>> from os import environ
>>> if 'SOMEENVVARIABLE' in environ:
...     del environ['SOMEENVVARIABLE']
>>> environ.get('SOMEENVVARIABLE')  # Does not exist in environ
>>> Env.SOMEENVVARIABLE
>>> Env.SOMEENVVARIABLE = 'value'
>>> Env.SOMEENVVARIABLE
'value'
>>> environ.get('SOMEENVVARIABLE')
'value'
>>> environ['SOMEENVVARIABLE']
'value'
>>> 'SOMEENVVARIABLE' in Env
True
>>> {k: v for k, v in Env.items() if k == 'SOMEENVVARIABLE'}
{'SOMEENVVARIABLE': 'value'}
>>> del Env['SOMEENVVARIABLE']
>>> 'SOMEENVVARIABLE' in Env
False

Functions

shellfish.process.env_dict() -> Dict[str, str]

Return the current environment-variables as a dictionary

Source code in libs/shellfish/shellfish/process.py

def env_dict() -> Dict[str, str]:
    """Return the current environment-variables as a dictionary"""
    return env.asdict()

shellfish.process.hostname() -> str

Return the current computer's hostname

Returns:

Name	Type	Description
str	str	hostname

Examples:

>>> hn = hostname()
>>> isinstance(hn, str)
True

Source code in libs/shellfish/shellfish/process.py

def hostname() -> str:
    """Return the current computer's hostname

    Returns:
        str: hostname

    Examples:
        >>> hn = hostname()
        >>> isinstance(hn, str)
        True

    """
    return platform.node()

shellfish.process.is_cpython() -> bool

Return True if running on CPython; False otherwise

Source code in libs/shellfish/shellfish/process.py

def is_cpython() -> bool:
    """Return True if running on CPython; False otherwise"""
    return "cpython" in platform.python_implementation().lower()

shellfish.process.is_mac() -> bool

Determine if current operating system is macos/osx

Returns:

Type	Description
bool	True if on a mac; False otherwise

Source code in libs/shellfish/shellfish/process.py

def is_mac() -> bool:
    """Determine if current operating system is macos/osx

    Returns:
        True if on a mac; False otherwise

    """
    return "darwin" in platform.system().lower()

shellfish.process.is_notebook() -> bool

Determine if running in ipython/jupyter notebook; returns True/False

Source code in libs/shellfish/shellfish/process.py

def is_notebook() -> bool:  # pragma: nocov
    """Determine if running in ipython/jupyter notebook; returns True/False"""
    try:
        shell = get_ipython().__class__.__name__  # type: ignore[name-defined]
        if shell == "ZMQInteractiveShell":
            return True  # Jupyter notebook or qtconsole
        elif shell == "TerminalInteractiveShell":
            return False  # Terminal running IPython
        else:
            return False  # Other type (?)
    except NameError:
        return False  # Probably standard Python interpreter

shellfish.process.is_pypy() -> bool

Return True if running on pypy3; False otherwise

Source code in libs/shellfish/shellfish/process.py

def is_pypy() -> bool:
    """Return True if running on pypy3; False otherwise"""
    return "pypy" in platform.python_implementation().lower()

shellfish.process.is_win() -> bool

Determine if current operating system is windows

Returns:

Type	Description
bool	True if on a windows machine; False otherwise

Source code in libs/shellfish/shellfish/process.py

def is_win() -> bool:
    """Determine if current operating system is windows

    Returns:
        True if on a windows machine; False otherwise

    """
    return IS_WIN

shellfish.process.is_wsl() -> bool

Return True if python is running under (WSL); Return False otherwise

Source code in libs/shellfish/shellfish/process.py

def is_wsl() -> bool:  # pragma: nocov
    """Return True if python is running under (WSL); Return False otherwise"""
    if sys.platform in {"win32", "cygwin", "darwin"}:
        return False

    if "microsoft" in platform.release().lower():
        return True

    try:
        with open("/proc/version") as f:
            if "microsoft" in f.read().lower():
                return True
    except FileNotFoundError:
        pass

    return False

shellfish.process.ismac() -> bool

Alias for is_mac()

Source code in libs/shellfish/shellfish/process.py

def ismac() -> bool:
    """Alias for is_mac()"""
    return is_mac()

shellfish.process.iswin() -> bool

Alias for is_win()

Source code in libs/shellfish/shellfish/process.py

def iswin() -> bool:
    """Alias for is_win()"""
    return is_win()

shellfish.process.iswsl() -> bool

Alias for is_wsl()

Source code in libs/shellfish/shellfish/process.py

def iswsl() -> bool:
    """Alias for is_wsl()"""
    return is_wsl()

shellfish.process.linux_version() -> str

Return rhel7 or rhel8 based on the current linux version

Source code in libs/shellfish/shellfish/process.py

def linux_version() -> str:
    """Return rhel7 or rhel8 based on the current linux version"""
    try:
        with open("/etc/redhat-release") as file:
            release_info = file.read()
            if "release 7" in release_info:
                return "rhel7"
            elif "release 8" in release_info:
                return "rhel8"
            else:
                return "other"
    except FileNotFoundError:
        return "linux"

shellfish.process.opsys() -> str

Return the current process' os type: 'mac' | 'lin' | 'win' | 'wsl'

Source code in libs/shellfish/shellfish/process.py

def opsys() -> str:
    """Return the current process' os type: 'mac' | 'lin' | 'win' | 'wsl'"""
    if is_win():
        return "win"
    if is_wsl():
        return "wsl"
    if is_mac():
        return "mac"
    return linux_version()

shellfish.process.sys_path_sep() -> str

Return the system path separator string (; on windows -- : otherwise)

Examples:

>>> import os
>>> sep = sys_path_sep()
>>> isinstance(sep, str)
True
>>> os.pathsep == sep
True

Source code in libs/shellfish/shellfish/process.py

def sys_path_sep() -> str:
    """Return the system path separator string (; on windows -- : otherwise)

    Examples:
        >>> import os
        >>> sep = sys_path_sep()
        >>> isinstance(sep, str)
        True
        >>> os.pathsep == sep
        True

    """
    return pathsep

shellfish.process.syspath_paths(syspath: Optional[str] = None) -> List[str]

Return the current sys.path as a list

Examples:

>>> sys_paths = syspath_paths()
>>> isinstance(sys_paths, list)
True
>>> sys_path_arg = 'path1;path2;path3' if is_win() else 'path1:path2:path3'
>>> sys_paths_w_args = syspath_paths(syspath=sys_path_arg)
>>> isinstance(sys_paths_w_args, list)
True
>>> sys_paths_w_args == ['path1', 'path2', 'path3']
True

Source code in libs/shellfish/shellfish/process.py

def syspath_paths(syspath: Optional[str] = None) -> List[str]:
    """Return the current sys.path as a list

    Examples:
        >>> sys_paths = syspath_paths()
        >>> isinstance(sys_paths, list)
        True
        >>> sys_path_arg = 'path1;path2;path3' if is_win() else 'path1:path2:path3'
        >>> sys_paths_w_args = syspath_paths(syspath=sys_path_arg)
        >>> isinstance(sys_paths_w_args, list)
        True
        >>> sys_paths_w_args == ['path1', 'path2', 'path3']
        True

    """
    if syspath is None:
        return list(filter(None, sys.path))
    return list(filter(None, syspath.split(pathsep)))

shellfish.process.tmpenv(**kwargs: str) -> Generator[Type[Env], Any, None]

Context manager for Env

Source code in libs/shellfish/shellfish/process.py

@contextmanager
def tmpenv(**kwargs: str) -> Generator[Type[Env], Any, None]:
    """Context manager for Env"""
    old_env = dict(environ)
    if kwargs:
        env.update(kwargs)
    try:
        yield env
    finally:
        environ.clear()
        environ.update(old_env)

shellfish.psu

psutils-utils

shellfish.sh

shell utils

Classes

shellfish.sh.Done(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

PRun => 'ProcessRun' for finished processes

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.sh.Done.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.sh.Done.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.sh.Done.__ge__(filepath: FsPath) -> 'Done'

Operator overload for writing stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __ge__(self, filepath: FsPath) -> "Done":
    """Operator overload for writing stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath)
    return self

shellfish.sh.Done.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.sh.Done.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.sh.Done.__gt__(filepath: FsPath) -> None

Operator overload for writing a stdout to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __gt__(self, filepath: FsPath) -> None:
    """Operator overload for writing a stdout to a fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath)

shellfish.sh.Done.__irshift__(filepath: FsPath) -> 'Done'

Operator overload for appending stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __irshift__(self, filepath: FsPath) -> "Done":
    """Operator overload for appending stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath, append=True)
    return self

shellfish.sh.Done.__post_init__() -> None

Write the stdout/stdout to sys.stdout/sys.stderr post object init

Source code in libs/shellfish/shellfish/sh.py

def __post_init__(self) -> None:
    """Write the stdout/stdout to sys.stdout/sys.stderr post object init"""
    if self.verbose:
        self.sys_print()

shellfish.sh.Done.__rshift__(filepath: FsPath) -> None

Operator overload for appending stdout to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __rshift__(self, filepath: FsPath) -> None:
    """Operator overload for appending stdout to fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath, append=True)

shellfish.sh.Done.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.sh.Done.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.sh.Done.check(ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0) -> None

Check returncode and stderr

Raises:

Type	Description
DoneError	If return code is non-zero and stderr is not None

Source code in libs/shellfish/shellfish/sh.py

def check(
    self,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
) -> None:
    """Check returncode and stderr

    Raises:
        DoneError: If return code is non-zero and stderr is not None

    """
    if isinstance(ok_code, int):
        if self.returncode != ok_code and self.stderr:
            raise DoneError(done=self)
    else:
        if self.returncode not in ok_code:
            raise DoneError(done=self)

shellfish.sh.Done.completed_process() -> CompletedProcess[str]

Return subprocess.CompletedProcess object

Source code in libs/shellfish/shellfish/sh.py

def completed_process(self) -> CompletedProcess[str]:
    """Return subprocess.CompletedProcess object"""
    return CompletedProcess(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
    )

shellfish.sh.Done.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.sh.Done.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.sh.Done.done_dict() -> DoneDict

Return Done object as typed-dict

Source code in libs/shellfish/shellfish/sh.py

def done_dict(self) -> DoneDict:
    """Return Done object as typed-dict"""
    return DoneDict(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_dict(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.sh.Done.done_obj() -> DoneObj

Return Done object typed dict

Source code in libs/shellfish/shellfish/sh.py

def done_obj(self) -> DoneObj:
    """Return Done object typed dict"""
    return DoneObj(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_obj(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.sh.Done.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.Done.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.sh.Done.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.Done.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.sh.Done.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.sh.Done.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.sh.Done.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.sh.Done.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.sh.Done.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.sh.Done.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.sh.Done.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.sh.Done.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.sh.Done.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.sh.Done.grep(string: str) -> List[str]

Return lines in stdout that have

Parameters:

Name	Type	Description	Default
string	str	String to search for	required

Returns:

Type	Description
List[str]	List[str]: List of strings of stdout lines containing the given search string

Source code in libs/shellfish/shellfish/sh.py

def grep(self, string: str) -> List[str]:
    """Return lines in stdout that have

    Args:
        string (str): String to search for

    Returns:
        List[str]: List of strings of stdout lines containing the given
            search string

    """
    return [
        line for line in self.stdout.splitlines(keepends=False) if string in line
    ]

shellfish.sh.Done.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.sh.Done.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.sh.Done.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.sh.Done.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.sh.Done.json_parse(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout"""
    return (
        self.json_parse_stdout(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
        if not stderr
        else self.json_parse_stderr(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
    )

shellfish.sh.Done.json_parse_stderr(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stderr

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stderr(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stderr"""
    return JSON.loads(self.stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.json_parse_stdout(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stdout(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stdout"""
    return JSON.loads(self.stdout, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.sh.Done.parse_json(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout (alias bc I keep flip-flopping the fn name)

Source code in libs/shellfish/shellfish/sh.py

def parse_json(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout (alias bc I keep flip-flopping the fn name)"""
    return self.json_parse(stderr=stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.sh.Done.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.Done.sys_print() -> None

Write self.stdout to sys.stdout and self.stderr to sys.stderr

Source code in libs/shellfish/shellfish/sh.py

def sys_print(self) -> None:
    """Write self.stdout to sys.stdout and self.stderr to sys.stderr"""
    sys.stdout.write(self.stdout)
    sys.stderr.write(self.stderr)

shellfish.sh.Done.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.sh.Done.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.sh.Done.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.sh.Done.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.Done.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.sh.Done.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.sh.Done.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.sh.Done.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.sh.Done.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.sh.Done.write_stderr(filepath: FsPath, *, append: bool = False) -> None

Write stderr as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stderr(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stderr as a string to a fspath

    Args:
        filepath: Filepath of location to write stderr
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stderr, append=append)

shellfish.sh.Done.write_stdout(filepath: FsPath, *, append: bool = False) -> None

Write stdout as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stdout(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stdout as a string to a fspath

    Args:
        filepath: Filepath to write stdout to
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stdout, append=append)

shellfish.sh.DoneError(done: Done)

Bases: SubprocessError

Raised when run() is called with check=True and the process returns a non-zero exit status.

Attributes:

Name	Type	Description
cmd	str	command that was run
returncode	int	exit status of the process
stdout	str	standard output (stdout) of the process
stderr	str	standard error (stderr) of the process

Source code in libs/shellfish/shellfish/sh.py

def __init__(self, done: Done) -> None:
    self.returncode = done.returncode
    self.cmd = done.args
    self.stderr = done.stderr
    self.stdout = done.stdout
    self.cmd = done.args
    self.done = done

shellfish.sh.DoneObj

Bases: TypedDict

Todo

deprecate this in favor of DoneDict

shellfish.sh.Flag

Flag obj

Examples:

>>> Flag.__help
'--help'
>>> Flag._v
'-v'

shellfish.sh.FlagMeta

Bases: type

Meta class

Functions

shellfish.sh.FlagMeta.attr2flag(string: str) -> str cached staticmethod

Convert and return attr to string

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
@lru_cache(maxsize=None)
def attr2flag(string: str) -> str:
    """Convert and return attr to string"""
    return string.replace("_", "-")

shellfish.sh.HrTime(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

High resolution time

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.sh.HrTime.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.sh.HrTime.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.sh.HrTime.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.sh.HrTime.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.sh.HrTime.__post_init__() -> Any

Function place holder that is called after object initialization

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def __post_init__(self) -> Any:
    """Function place holder that is called after object initialization"""

shellfish.sh.HrTime.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.sh.HrTime.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.sh.HrTime.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.sh.HrTime.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.sh.HrTime.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.HrTime.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.sh.HrTime.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.HrTime.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.sh.HrTime.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.sh.HrTime.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.sh.HrTime.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.sh.HrTime.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.sh.HrTime.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.sh.HrTime.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.sh.HrTime.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.sh.HrTime.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.sh.HrTime.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.sh.HrTime.from_seconds(seconds: float) -> 'HrTime' classmethod

Return HrTime object from seconds

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
'HrTime'	HrTime object

Source code in libs/shellfish/shellfish/sh.py

@classmethod
def from_seconds(cls, seconds: float) -> "HrTime":
    """Return HrTime object from seconds

    Args:
        seconds (float): number of seconds

    Returns:
        HrTime object

    """
    _sec, _ns = seconds2hrtime(seconds)
    return cls(sec=_sec, ns=_ns)

shellfish.sh.HrTime.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.sh.HrTime.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.sh.HrTime.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.sh.HrTime.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.sh.HrTime.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.sh.HrTime.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.sh.HrTime.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.HrTime.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.sh.HrTime.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.sh.HrTime.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.sh.HrTime.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.HrTime.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.sh.HrTime.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.sh.HrTime.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.sh.HrTime.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.sh.HrTime.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.sh.HrTimeDict

Bases: TypedDict

High resolution time

shellfish.sh.HrTimeObj

Bases: TypedDict

Todo

deprecate this in favor of HrTimeDict

shellfish.sh.LIN

Bases: LIN

Linux (and Mac) shell commands/methods container

Functions

shellfish.sh.LIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	str	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (str): Allow link to exist

    """
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.sh.LIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): Allow link to exist

    """
    for link, target in link_target_tuples:
        LIN.link_dir(link, target, exist_ok=exist_ok)

shellfish.sh.LIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	Allow links to already exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): Allow links to already exist

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.sh.LIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
exist_ok	bool	Allow links to already exist	False
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        exist_ok (bool): Allow links to already exist
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.

    """
    for link, target in link_target_tuples:
        LIN.link_file(link, target, exist_ok=exist_ok)

shellfish.sh.LIN.rsync(src: str, dest: str, delete: bool = False, mkdirs: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> Done staticmethod

Run an rsync subprocess

Parameters:

Name	Type	Description	Default
mkdirs	bool	Make destination directories if they do not already exist; defaults to False.	False
src	str	Source directory path	required
dest	str	Destination directory path	required
delete	bool	Delete files/directories in destination if they do exist in source	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Name	Type	Description
Done	Done	Done object containing the info for the rsync run

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync(
    src: str,
    dest: str,
    delete: bool = False,
    mkdirs: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> Done:
    """Run an `rsync` subprocess

    Args:
        mkdirs (bool): Make destination directories if they do not already
            exist; defaults to False.
        src (str): Source directory path
        dest (str): Destination directory path
        delete (bool): Delete files/directories in destination if they do
            exist in source
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        Done: Done object containing the info for the rsync run

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection

    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    rsync_args = LIN.rsync_args(
        src, dest, delete=delete, exclude=exclude, include=include, dry_run=dry_run
    )

    done = do(args=list(filter(None, rsync_args)))
    return done

shellfish.sh.LIN.rsync_args(src: str, dest: str, delete: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> List[str] staticmethod

Return args for rsync command on linux/mac

Parameters:

Name	Type	Description	Default
src	str	path to remote (raid) tdir	required
dest	str	path to local tdir	required
delete	bool	Flag that will do a 'hard sync'	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from rsync

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync_args(
    src: str,
    dest: str,
    delete: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> List[str]:
    """Return args for rsync command on linux/mac

    Args:
        src: path to remote (raid) tdir
        dest: path to local tdir
        delete: Flag that will do a 'hard sync'
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        subprocess return code from rsync

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection


    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []

    if not dest.endswith("/"):
        dest = f"{dest}/"
    if not src.endswith("/"):
        src = f"{src}/"
    _args: List[Union[str, None]] = [
        "rsync",
        "-a",
        "-O",
        "--no-o",
        "--no-g",
        "--no-p",
        "--delete" if delete else None,
        *(f'--exclude="{pattern}"' for pattern in exclude),
        *(f'--include="{pattern}"' for pattern in include),
        *(("--dry-run", "-i") if dry_run else (None,)),
        src,
        dest,
    ]
    return list(filter(None, _args))

shellfish.sh.LIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.sh.LIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_dir(link)

shellfish.sh.LIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.sh.LIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_file(link)

shellfish.sh.Stdio

Bases: IntEnum

Standard-io enum object

shellfish.sh.WIN

Bases: WIN

Windows shell commands/methods container

Functions

shellfish.sh.WIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, do not raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, do not raise an exception if the link exists

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath, target_is_directory=True)
    except OSError:
        batman.MKLINK(
            linkpath,
            targetpath,
            D=True,
        )

shellfish.sh.WIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, do not raise an exception if the link(s) exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, do not raise an exception if the link(s) exist

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_dir(link, target, exist_ok=exist_ok)
    except OSError:
        args = [
            batman.MKLINK_ARGS(link, target, D=True)
            for link, target in link_target_tuples
            if WIN._check_link_target_dirs(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in args])

shellfish.sh.WIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        symlink(targetpath, linkpath)
    except OSError:
        makedirs(path.split(linkpath)[0], exist_ok=True)
        batman.MKLINK(
            linkpath,
            targetpath,
        )

shellfish.sh.WIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_file(link, target, exist_ok=exist_ok)
    except OSError:
        link_target_tuples = list(link_target_tuples)
        _args = [
            batman.MKLINK_ARGS(link, target, D=False)
            for link, target in link_target_tuples
            if WIN._check_link_target_files(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in _args])

shellfish.sh.WIN.robocopy(src: str, dest: str, *, mkdirs: bool = True, delete: bool = False, exclude_files: Optional[Iterable[str]] = None, exclude_dirs: Optional[Iterable[str]] = None, dry_run: bool = False) -> Done staticmethod

Robocopy wrapper function (crude in that it opens a subprocess)

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[Iterable[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[Iterable[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False
mkdirs	bool	Flag to make destinaation directories if they do not already exist	True

Returns:

Type	Description
Done	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy(
    src: str,
    dest: str,
    *,
    mkdirs: bool = True,
    delete: bool = False,
    exclude_files: Optional[Iterable[str]] = None,
    exclude_dirs: Optional[Iterable[str]] = None,
    dry_run: bool = False,
) -> Done:  # pragma: nocov
    """Robocopy wrapper function (crude in that it opens a subprocess)

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run
        mkdirs (bool): Flag to make destinaation directories if they do
            not already exist

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    _exclude_files = [] if exclude_files is None else list(exclude_files)
    _exclude_dirs = [] if exclude_dirs is None else list(exclude_dirs)
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    _args = WIN.robocopy_args(
        src=src,
        dest=dest,
        delete=delete,
        exclude_files=_exclude_files,
        exclude_dirs=_exclude_dirs,
        dry_run=dry_run,
    )
    return do(args=_args)

shellfish.sh.WIN.robocopy_args(src: str, dest: str, *, delete: bool = False, exclude_files: Optional[List[str]] = None, exclude_dirs: Optional[List[str]] = None, dry_run: bool = False) -> List[str] staticmethod

Return list of robocopy command args

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[List[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[List[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy_args(
    src: str,
    dest: str,
    *,
    delete: bool = False,
    exclude_files: Optional[List[str]] = None,
    exclude_dirs: Optional[List[str]] = None,
    dry_run: bool = False,
) -> List[str]:
    """Return list of robocopy command args

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    if exclude_files is None:
        exclude_files = []
    if exclude_dirs is None:
        exclude_dirs = []
    _args = [
        "robocopy",
        src,
        dest,
        "/MIR" if delete else "/E",
        "/mt",
        "/W:1",
        "/R:1",
    ]
    if exclude_dirs:
        _args.extend(["/XD", *exclude_dirs])
    if exclude_files:
        _args.extend(["/XF", *exclude_files])
    if dry_run:
        _args.append("/L")
    return list(filter(None, _args))

shellfish.sh.WIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.RD(link)

shellfish.sh.WIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_dir(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            commands=[batman.RD_ARGS(link) for link in links]
        )

shellfish.sh.WIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link (str): path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.DEL(link)

shellfish.sh.WIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_file(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            [batman.DEL_ARGS(link) for link in links],
        )

Functions

shellfish.sh.basename(fspath: FsPath) -> str

Return the basename of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def basename(fspath: FsPath) -> str:
    """Return the basename of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.basename(str(fspath))

shellfish.sh.cd(dirpath: FsPath) -> None

Change directory to given dirpath; alias for os.chdir

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory fspath	required

Source code in libs/shellfish/shellfish/sh.py

def cd(dirpath: FsPath) -> None:
    """Change directory to given dirpath; alias for `os.chdir`

    Args:
        dirpath: Directory fspath

    """
    chdir(str(dirpath))

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

Change the access permissions of a file

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file to chmod	required
mode	int	Permissions mode as an int	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def chmod(fspath: FsPath, mode: int) -> None:
    """Change the access permissions of a file

    Args:
        fspath (FsPath): Path to file to chmod
        mode (int): Permissions mode as an int

    """
    return _chmod(path=str(fspath), mode=mode)

shellfish.sh.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:

Name	Type	Description	Default
src	str	Source fspath	required
dest	str	Destination fspath	required
dryrun	bool	Do not copy file if True just return the src and dest	False
mkdirp	bool	Create parent directories if they do not exist	False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source fspath
        dest (str): Destination fspath
        dryrun (bool): Do not copy file if True just return the src and dest
        mkdirp (bool): Create parent directories if they do not exist

    """
    _dest = Path(dest)
    if not dryrun and mkdirp:
        _dest.parent.mkdir(parents=mkdirp, exist_ok=True)
    elif not _dest.parent.exists() or not _dest.parent.is_dir():
        raise FileNotFoundError(f"Destination directory {_dest.parent} does not exist")
    if not dryrun:
        wbytes_gen(dest, lbytes_gen(src, blocksize=2**18))
        _copystat(src, dest, follow_symlinks=True)
    return (str(src), str(dest))

shellfish.sh.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:

Name	Type	Description	Default
src	str	Source directory/file to copy	required
dest	FsPath	Destination directory/file to copy	required
force	bool	Force the copy (like -f flag for cp in shell)	True
recursive	bool	Recursive copy (like -r flag for cp in shell)	False
r	bool	alias for recursive	False
f	bool	alias for force	True

Raises:

Type	Description
ValueError	If src is a directory and recursive and r are both False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source directory/file to copy
        dest: Destination directory/file to copy
        force: Force the copy (like -f flag for cp in shell)
        recursive: Recursive copy (like -r flag for cp in shell)
        r: alias for recursive
        f: alias for force

    Raises:
        ValueError: If src is a directory and recursive and r are both `False`

    """
    _recursive = recursive or r
    _force = force or f
    for _src in iglob(_fspath(src), recursive=True):
        _dest = dest
        if (path.exists(dest) and not _force) or _src == dest:
            return
        if path.isdir(_src) and not _recursive:
            raise ValueError("Source ({}) is directory; use r=True")
        if path.isfile(_src) and path.isdir(dest):
            _dest = path.join(dest, path.basename(_src))
        if path.isfile(_src) or path.islink(src):
            copy_file(_src, _dest)
        if path.isdir(_src):
            if not path.exists(dest):
                _makedirs(dest)
            copytree(src, dest, dirs_exist_ok=True)

shellfish.sh.decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str

Return Stdio bytes from stdout/stderr as a string

Args:
    stdio_bytes (bytes): STDOUT/STDERR bytes
    lf (bool): Replace `

line endings with `

Returns:
    str: decoded stdio bytes

Source code in libs/shellfish/shellfish/sh.py

def decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str:
    """Return Stdio bytes from stdout/stderr as a string

    Args:
        stdio_bytes (bytes): STDOUT/STDERR bytes
        lf (bool): Replace `\r\n` line endings with `\n`

    Returns:
        str: decoded stdio bytes

    """
    if isinstance(stdio_bytes, str):
        return stdio_bytes
    if lf:
        return decode_stdio_bytes(stdio_bytes, lf=False).replace("\r\n", "\n")
    try:
        return str(stdio_bytes.decode())
    except AttributeError:
        return ""
    except Exception:
        pass

    try:
        return str(stdio_bytes.decode("utf-8"))
    except UnicodeDecodeError:
        pass
    return str(stdio_bytes.decode("latin-1"))

shellfish.sh.dir_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dir_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isdir"""
    return isdir(fspath)

shellfish.sh.dir_exists_async(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.sh.dirname(fspath: FsPath) -> str

Return dirname/parent-dir of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def dirname(fspath: FsPath) -> str:
    """Return dirname/parent-dir of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.dirname(_fspath(fspath))

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

Yield all dirpaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all dirpaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in dirs_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield directory-paths beneath a dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        dirpath if abspath else str(dirpath).replace(dirpath, "").strip(sep)
        for dirpath in (
            pwd
            for pwd, dirs, files in walk(
                str(dirpath),
                onerror=onerror,
                topdown=topdown,
                followlinks=followlinks,
            )
        )
    )

shellfish.sh.do(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[FsPath] = None, shell: bool = False, check: bool = False, tee: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
tee	bool	Flag to tee the subprocess stdout and stderr to sys.stdout/stderr	False
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check against	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	if args and *popenargs are both given

Source code in libs/shellfish/shellfish/sh.py

def do(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    shell: bool = False,
    check: bool = False,
    tee: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        tee (bool): Flag to tee the subprocess stdout and stderr to sys.stdout/stderr
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check against
        dryrun: Don't run the subprocess

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: if args and *popenargs are both given

    """
    if args and popenargs:
        raise ValueError("Cannot give *popenargs and `args` kwargs")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win():
        args = validate_popen_args_windows(args, env)
    _input = validate_stdin(input)
    return _do(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        check=check,
        verbose=verbose,
        input=_input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
        tee=tee,
    )

shellfish.sh.do_async(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend environment with the current environment (Default value = True)	True
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	If both *popenargs and args are given

Source code in libs/shellfish/shellfish/sh.py

async def do_async(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: If both *popenargs and args are given

    """
    if args and popenargs:
        raise ValueError("Cannot give *args and args-keyword-argument")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win() and sys.version_info < (3, 8):
        done = await do_asyncify(
            args=args,
            env=env,
            extenv=extenv,
            cwd=cwd,
            shell=shell,
            verbose=verbose,
            input=input,
            check=check,
            timeout=timeout,
            ok_code=ok_code,
            dryrun=dryrun,
        )
        done.async_proc = True
        return done
    if not shell and is_win():
        args = validate_popen_args_windows(args, env)
    return await _do_async(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.do_asyncify(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess asynchronously using asyncified version of do

Source code in libs/shellfish/shellfish/sh.py

async def do_asyncify(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess asynchronously using asyncified version of do"""
    done = await _do_asyncify(
        *popenargs,
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )
    done.async_proc = True
    return done

shellfish.sh.doa(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Alias for sh.do_async

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False
extenv	bool	Extend environment with the current environment (Default value = True)	True

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

async def doa(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Alias for sh.do_async

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object
        extenv: Extend environment with the current environment (Default value = True)

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return await do_async(
        *popenargs,
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.echo(*objects: Any, sep: str = ' ', end: str = '\n', file: Optional[IO[str]] = None, flush: bool = False) -> None

Print/echo function

Args:
    *objects: Item(s) to print/echo
    sep: Separator to print with
    end: End of print suffix; defaults to `

` file: File like object to write to if not stdout flush: Flush the file after writing

Examples:
    >>> echo("shellfish")
    shellfish

Source code in libs/shellfish/shellfish/echo.py

def echo(
    *objects: Any,
    sep: str = " ",
    end: str = "\n",
    file: Optional[IO[str]] = None,
    flush: bool = False,
) -> None:
    """Print/echo function

    Args:
        *objects: Item(s) to print/echo
        sep: Separator to print with
        end: End of print suffix; defaults to `\n`
        file: File like object to write to if not stdout
        flush: Flush the file after writing

    Examples:
        >>> echo("shellfish")
        shellfish

    """
    print(*objects, sep=sep, end=end, file=file, flush=flush)

shellfish.sh.exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise"""
    return path.exists(_fspath(fspath))

shellfish.sh.export(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Raises:

Type	Description
ValueError	if unable to parse key/val

Source code in libs/shellfish/shellfish/sh.py

def export(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Raises:
        ValueError: if unable to parse key/val

    """
    if val:
        environ[key] = val
        return (key, val)
    if "=" in key:
        _key = key.split("=")[0]
        return export(_key, key[len(_key) + 1 :])
    raise ValueError(
        f"Unable to parse env variable - key: {str(key)}, value: {str(val)}"
    )

shellfish.sh.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'

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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'

    """
    if period:
        return "".join(Path(fspath).suffixes)
    return "".join(Path(fspath).suffixes).lstrip(".")

shellfish.sh.file_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isfile"""
    return isfile(fspath)

shellfish.sh.file_exists_async(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

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

Yield lines from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	File to yield lines from	required
keepends	bool	Flag to keep the ends of the file lines	True

Yields:

Type	Description
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 wstring
>>> wstring(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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_lines_gen(filepath: FsPath, keepends: bool = True) -> Iterable[str]:
    r"""Yield lines from a given fspath

    Args:
        filepath: File to yield lines from
        keepends: Flag to keep the ends of the file lines

    Yields:
        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 wstring
        >>> wstring(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)


    """
    with open(filepath) as f:
        if keepends:
            yield from (line for line in f)
        else:
            yield from (line.rstrip("\n").rstrip("\r\n") for line in f)

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

Compare 2 files for equality given their filepaths

Parameters:

Name	Type	Description	Default
left	FsPath	Filepath 1	required
right	FsPath	Filepath 2	required
shallow	bool	Check only size and modification time if True	True
blocksize	int	Chunk size to read files	65536

Returns:

Type	Description
bool	True if files are equal, False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool:
    """Compare 2 files for equality given their filepaths

    Args:
        left (FsPath): Filepath 1
        right (FsPath): Filepath 2
        shallow (bool): Check only size and modification time if True
        blocksize (int): Chunk size to read files

    Returns:
        True if files are equal, False otherwise

    """
    left_stat = stat(left)
    right_stat = stat(right)
    if (
        shallow
        and left_stat.st_size == right_stat.st_size
        and left_stat.st_mtime == right_stat.st_mtime
    ):
        return True
    if left_stat.st_size != right_stat.st_size:
        return False
    return not any(
        left_chunk != right_chunk
        for left_chunk, right_chunk in zip(
            rbytes_gen(left, blocksize=blocksize),
            rbytes_gen(right, blocksize=blocksize),
        )
    )

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in files_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.sh.filepath_mtimedelta_sec(filepath: FsPath) -> float

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_mtimedelta_sec(filepath: FsPath) -> float:
    """Return the seconds since the file(path) was last modified"""
    return time() - path.getmtime(_fspath(filepath))

shellfish.sh.files_dirs_gen(dirpath: FsPath = '.', *, abspath: bool = True, topdown: bool = True, onerror: Optional[Callable[[OSError], Any]] = 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:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath is a directory	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Tuple[Iterator[str], Iterator[str]]:
    r"""Return a files_gen() and a dirs_gen() in one swell-foop

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath is a directory

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

    """
    return files_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    ), dirs_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield file-paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        filepath if abspath else str(filepath).replace(dirpath, "").strip(sep)
        for filepath in (
            path.join(pwd, filename)
            for pwd, dirs, files in walk(
                str(dirpath),
                topdown=topdown,
                onerror=onerror,
                followlinks=followlinks,
            )
            for filename in files
        )
    )

shellfish.sh.filesize(fspath: FsPath) -> int

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath as a string or pathlib.Path object	required

Returns:

Name	Type	Description
int	int	size of the fspath in bytes

Source code in libs/shellfish/shellfish/fs/__init__.py

def filesize(fspath: FsPath) -> int:
    """Return the size of the given file(path) in bytes

    Args:
        fspath (FsPath): Filepath as a string or pathlib.Path object

    Returns:
        int: size of the fspath in bytes

    """
    return stat(fspath).st_size

shellfish.sh.filesize_async(fspath: FsPath) -> int async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def 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

    """
    _stat_res = await aios.stat(str(fspath))
    return _stat_res.st_size

shellfish.sh.flatten_args(*args: Union[Any, List[Any]]) -> List[str]

Flatten possibly nested iterables of sequences to a list of strings

Examples:

>>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
['cmd', 'uno', 'dos', 'tres']
>>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
['cmd', 'uno', 'dos', 'tres', '4444', 'five']

Source code in libs/shellfish/shellfish/sh.py

def flatten_args(*args: Union[Any, List[Any]]) -> List[str]:
    """Flatten possibly nested iterables of sequences to a list of strings

    Examples:
        >>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
        ['cmd', 'uno', 'dos', 'tres']
        >>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
        ['cmd', 'uno', 'dos', 'tres', '4444', 'five']

    """
    return list(_flatten_strings(*args))

shellfish.sh.fspath(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def fspath(fspath: FsPath) -> str:
    """Alias for os._fspath; returns fspath string for any type of path"""
    return _fspath(fspath)

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

Return an iterator of fspaths matching the given glob pattern

Parameters:

Name	Type	Description	Default
pattern	str	Glob pattern	required
recursive	bool	Recursively search directories if True	False
r	bool	Recursively search directories if True (Alias for recursive)	False

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def glob(pattern: str, *, recursive: bool = False, r: bool = False) -> Iterator[str]:
    """Return an iterator of fspaths matching the given glob pattern

    Args:
        pattern: Glob pattern
        recursive: Recursively search directories if True
        r: Recursively search directories if True (Alias for recursive)

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

    """
    return iglob(pattern, recursive=recursive or r)

shellfish.sh.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish.sh.is_dir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.sh.is_file(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_file(fspath: FsPath) -> bool:
    """Return True if the given path is a file; alias for isfile"""
    return isfile(fspath)

shellfish.sh.is_file_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.sh.is_link(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_link(fspath: FsPath) -> bool:
    """Return True if the given path is a link; alias for islink"""
    return islink(fspath)

shellfish.sh.is_link_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.sh.isdir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isdir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; False otherwise"""
    return path.isdir(_fspath(fspath))

shellfish.sh.isdir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.sh.isfile(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isfile(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return path.isfile(_fspath(fspath))

shellfish.sh.isfile_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.sh.islink(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def islink(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return path.islink(_fspath(fspath))

shellfish.sh.islink_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.sh.listdir_async(fspath: FsPath) -> List[str] async

Async version of os.listdir

Source code in libs/shellfish/shellfish/fs/_async.py

async def listdir_async(fspath: FsPath) -> List[str]:
    """Async version of `os.listdir`"""
    return await aios.listdir(_fspath(fspath))

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]:
    r"""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

    """
    _attr = "path" if abspath else "name"
    return (
        getattr(el, _attr)
        for el in scandir_gen(
            fspath,
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )
    )

shellfish.sh.ls(dirpath: FsPath = '.', abspath: bool = False) -> List[str]

List files and dirs given a dirpath (defaults to pwd)

Parameters:

Name	Type	Description	Default
dirpath	FsPath	path-string to directory to list	'.'
abspath	bool	Give absolute paths	False

Returns:

Type	Description
List[str]	List of the directory items

Source code in libs/shellfish/shellfish/sh.py

def ls(dirpath: FsPath = ".", abspath: bool = False) -> List[str]:
    """List files and dirs given a dirpath (defaults to pwd)

    Args:
        dirpath (FsPath): path-string to directory to list
        abspath (bool): Give absolute paths

    Returns:
        List of the directory items

    """
    if abspath:
        return [el.path for el in scandir(str(dirpath))]
    return listdir(str(dirpath))

shellfish.sh.ls_async(dirpath: FsPath = '.', abspath: bool = False) -> List[str] async

List files and dirs given a dirpath (defaults to pwd)

Parameters:

Name	Type	Description	Default
dirpath	FsPath	path-string to directory to list	'.'
abspath	bool	Give absolute paths	False

Returns:

Type	Description
List[str]	List of the directory items

Source code in libs/shellfish/shellfish/sh.py

async def ls_async(dirpath: FsPath = ".", abspath: bool = False) -> List[str]:
    """List files and dirs given a dirpath (defaults to pwd)

    Args:
        dirpath (FsPath): path-string to directory to list
        abspath (bool): Give absolute paths

    Returns:
        List of the directory items

    """
    items = await listdir_async(dirpath)
    if abspath:
        return [path.join(dirpath, el) for el in items]
    return items

shellfish.sh.ls_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the directories in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want list directories	'.'
abspath	bool	Return absolute directory paths	False

Returns:

Type	Description
List[str]	List of directories as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_dirs(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the directories in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want list directories
        abspath (bool): Return absolute directory paths

    Returns:
        List of directories as strings

    """
    dirs = (el for el in scandir(str(dirpath)) if el.is_dir())
    if abspath:
        return list(map(lambda el: el.path, dirs))
    return list(map(lambda el: el.name, dirs))

shellfish.sh.ls_files(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the files in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want to list files	'.'
abspath	bool	Return absolute filepaths	False

Returns:

Type	Description
List[str]	List of files as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_files(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the files in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want to list files
        abspath (bool): Return absolute filepaths

    Returns:
        List of files as strings

    """
    files = (el for el in scandir(str(dirpath)) if el.is_file())
    if abspath:
        return list(map(lambda el: el.path, files))
    return list(map(lambda el: el.name, files))

shellfish.sh.ls_files_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> Tuple[List[str], List[str]]

List the files and directories given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to execute on	'.'
abspath	bool	Return absolute file/directory paths	False

Returns:

Type	Description
Tuple[List[str], List[str]]	Two lists of strings; the first is a list of the files and the second is a list of the directories

Source code in libs/shellfish/shellfish/sh.py

def ls_files_dirs(
    dirpath: FsPath = ".", *, abspath: bool = False
) -> Tuple[List[str], List[str]]:
    """List the files and directories given directory path

    Args:
        dirpath (FsPath): Directory path to execute on
        abspath (bool): Return absolute file/directory paths

    Returns:
        Two lists of strings; the first is a list of the files and the second
            is a list of the directories

    """
    dir_items = list(fs.scandir_gen(dirpath, files=True, dirs=True))
    dir_dir_entries = (el for el in dir_items if el.is_dir())
    file_dir_entries = (el for el in dir_items if el.is_file())
    if not abspath:
        return [el.name for el in file_dir_entries], [el.name for el in dir_dir_entries]
    return [el.path for el in file_dir_entries], [el.path for el in dir_dir_entries]

shellfish.sh.lstat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

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

Make directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to create	required
parents	bool	Make parent dirs if True; do not make parent dirs if False	False
p	bool	Make parent dirs if True; do not make parent dirs if False (alias of parents)	False
exist_ok	bool	Throw error if directory exists and exist_ok is False	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdir(
    fspath: FsPath, *, parents: bool = False, p: bool = False, exist_ok: bool = False
) -> None:
    """Make directory at given fspath

    Args:
        fspath (FsPath): Directory path to create
        parents (bool): Make parent dirs if True; do not make parent dirs if False
        p (bool): Make parent dirs if True; do not make parent dirs if False (alias of parents)
        exist_ok (bool): Throw error if directory exists and exist_ok is False

    Returns:
         None

    """
    _parents = parents or p
    if _parents or exist_ok:
        return _makedirs(_fspath(fspath), exist_ok=_parents or exist_ok)
    return _mkdir(_fspath(fspath))

shellfish.sh.mkdirp(fspath: FsPath) -> None

Make directory and parents

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdirp(fspath: FsPath) -> None:
    """Make directory and parents"""
    return mkdir(fspath=fspath, parents=True)

shellfish.sh.move(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def move(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    _dst_str = str(dest)
    for file in iglob(str(src), recursive=True):
        _move(file, _dst_str)

shellfish.sh.mv(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/sh.py

def mv(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    fs.move(src, dest)

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in walk_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.sh.pstderr(proc: CompletedProcess[AnyStr]) -> str

Get the STDERR as a string from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	python subprocess.process object with STDERR	required

Returns:

Type	Description
str	STDERR for the proc as string

Source code in libs/shellfish/shellfish/sh.py

def pstderr(proc: CompletedProcess[AnyStr]) -> str:
    """Get the STDERR as a string from a subprocess

    Args:
        proc: python subprocess.process object with STDERR

    Returns:
        STDERR for the proc as string

    """
    if proc.stderr is None:
        return ""
    return decode_stdio_bytes(proc.stderr)

shellfish.sh.pstdout(proc: CompletedProcess[AnyStr]) -> str

Get the STDOUT as a string from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	python subprocess.process object with stdout	required

Returns:

Type	Description
str	STDOUT for the proc as string

Source code in libs/shellfish/shellfish/sh.py

def pstdout(proc: CompletedProcess[AnyStr]) -> str:
    """Get the STDOUT as a string from a subprocess

    Args:
        proc: python subprocess.process object with stdout

    Returns:
        STDOUT for the proc as string

    """
    if proc.stdout is None:
        return ""
    return decode_stdio_bytes(proc.stdout)

shellfish.sh.pstdout_pstderr(proc: CompletedProcess[AnyStr]) -> Tuple[str, str]

Get the STDOUT and STDERR as strings from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	Completed-subprocess	required

Returns:

Type	Description
Tuple[str, str]	Tuple of two strings: (stdout-string, stderr-string)

Source code in libs/shellfish/shellfish/sh.py

def pstdout_pstderr(proc: CompletedProcess[AnyStr]) -> Tuple[str, str]:
    """Get the STDOUT and STDERR as strings from a subprocess

    Args:
        proc: Completed-subprocess

    Returns:
        Tuple of two strings: (stdout-string, stderr-string)

    """
    return pstdout(proc), pstderr(proc)

shellfish.sh.pwd() -> str

Return present-working-directory path string; alias for os.getcwd

Returns:

Name	Type	Description
str	str	present working directory as string

Examples:

>>> import os
>>> pwd() == os.getcwd()
True

Source code in libs/shellfish/shellfish/sh.py

def pwd() -> str:
    """Return present-working-directory path string; alias for os.getcwd

    Returns:
        str: present working directory as string

    Examples:
        >>> import os
        >>> pwd() == os.getcwd()
        True

    """
    return getcwd()

shellfish.sh.q(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> q("hello world")
"'hello world'"
>>> q("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def q(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> q("hello world")
        "'hello world'"
        >>> q("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.sh.quote(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> quote("hello world")
"'hello world'"
>>> quote("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def quote(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> quote("hello world")
        "'hello world'"
        >>> quote("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.sh.rbytes(filepath: FsPath) -> bytes

Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes(filepath: FsPath) -> bytes:
    """Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    with open(filepath, "rb") as file:
        return bytes(file.read())

shellfish.sh.rbytes_async(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.sh.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]

Yield bytes from a given fspath

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]:
    """Yield bytes from a given fspath"""
    with open(filepath, "rb") as f:
        while True:
            data = f.read(blocksize)
            if not data:
                break
            yield data

shellfish.sh.rbytes_gen_async(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.sh.rjson(filepath: FsPath) -> Any

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def rjson(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)

    """
    return JSON.loads(lstring(filepath=filepath))

shellfish.sh.rjson_async(filepath: FsPath) -> Any async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rjson_async(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    json_string = await rbytes_async(filepath)
    return JSON.loads(json_string)

shellfish.sh.rm(fspath: FsPath, *, force: bool = False, recursive: bool = False, verbose: bool = False, f: bool = False, r: bool = False, v: bool = False, dryrun: bool = False) -> None

Remove files & directories in the style of the shell

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory to remove	required
force	bool	Flag to force removal; ignore missing	False
recursive	bool	Flag to remove recursively (like the -r in rm -r dir)	False
verbose	bool	Flag to be verbose	False
f	bool	alias for force kwarg	False
v	bool	alias for verbose	False
r	bool	alias for recursive kwarg	False
dryrun	bool	Flag to not actually remove anything	False

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/sh.py

def rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    verbose: bool = False,
    f: bool = False,
    r: bool = False,
    v: bool = False,
    dryrun: bool = False,
) -> None:
    """Remove files & directories in the style of the shell

    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Flag to force removal; ignore missing
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        verbose (bool): Flag to be verbose
        f (bool): alias for force kwarg
        v (bool): alias for verbose
        r (bool): alias for recursive kwarg
        dryrun (bool): Flag to not actually remove anything

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if verbose or v:
        echo(f"Removing {fspath}")
    fs.rm(
        fspath,
        force=force or f,
        recursive=recursive or r,
        dryrun=dryrun,
    )

shellfish.sh.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 Args: fspath (FsPath): Path to file or directory to remove force (bool): Force removal of files and directories recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Force removal of files and directories
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if has_magic(str(fspath)):
        if dryrun:
            yield from iglob(_fspath(fspath), recursive=recursive)
        else:
            for _path_str in iglob(str(fspath), recursive=recursive):
                if isfile(_path_str):
                    remove(_path_str)
                elif recursive:
                    rmdir(_path_str, recursive=True, force=force)
                else:
                    raise ValueError(
                        f"{str(_path_str)} (under {str(fspath)}) is a directory -- use r=True or recursive=True"
                    )
    else:
        if isfile(fspath):
            if not dryrun:
                remove(_fspath(fspath))
            yield _fspath(fspath)
        elif recursive:
            if not dryrun:
                rmdir(fspath, force=force, recursive=True)
            yield _fspath(fspath)
        else:
            raise ValueError(
                f"{str(fspath)} is a directory -- use r=True or recursive=True"
            )

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

Remove directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to remove	required
force	bool	Force removal of files and directories	False
recursive	bool	Recursively remove all contents if True	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmdir(fspath: FsPath, *, force: bool = False, recursive: bool = False) -> None:
    """Remove directory at given fspath

    Args:
        fspath (FsPath): Directory path to remove
        force (bool): Force removal of files and directories
        recursive (bool): Recursively remove all contents if True

    Returns:
        None

    """
    if force:
        try:
            return rmdir(fspath, recursive=recursive)
        except FileNotFoundError:
            return
    if recursive:
        return rmtree(_fspath(fspath))
    return _rmdir(_fspath(fspath))

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

Remove a file at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath to remove	required
dryrun	bool	Do not remove file if True	False

Returns:

Type	Description
str	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmfile(fspath: FsPath, *, dryrun: bool = False) -> str:
    """Remove a file at given fspath

    Args:
        fspath (FsPath): Filepath to remove
        dryrun (bool): Do not remove file if True

    Returns:
        None

    """
    if not dryrun:
        remove(_fspath(fspath))
    return _fspath(fspath)

shellfish.sh.rstring(filepath: FsPath, *, encoding: str = 'utf-8') -> str

Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	Encoding to use for reading the file	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rstring(filepath: FsPath, *, encoding: str = "utf-8") -> str:
    r"""Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding: Encoding to use for reading the file

    Returns:
        str: String read from given fspath

    Examples:
        ``` python
        >>> from shellfish.fs import rstring, wstring
        >>> fspath = "lstring.doctest.txt"
        >>> sstring(fspath, r'Check out this string')
        21
        >>> lstring(fspath)
        'Check out this string'
        >>> import os; os.remove(fspath)

        ```

    """
    _bytes = rbytes(filepath=filepath)
    try:
        return _bytes.decode(encoding=encoding)
    except UnicodeDecodeError:  # Catch the unicode decode error
        pass
    return _bytes.decode(encoding="latin2")

shellfish.sh.rstring_async(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.sh.safepath(fspath: FsPath) -> str

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	file-system path; file or directory path string or Path obj	required

Returns:

Name	Type	Description
str	str	file/dir path that does not exist and contains the given path

Source code in libs/shellfish/shellfish/fs/__init__.py

def safepath(fspath: FsPath) -> str:
    """Check if a file/dir path is save/unused; returns an unused path.

    Args:
        fspath: file-system path; file or directory path string or Path obj

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

    """
    path_str = str(fspath)
    if path.exists(path_str):
        f_bn, f_ext = path.splitext(path_str)
        for n in count(1):
            safe_save_path = f"{f_bn}_{str(n).zfill(3)}.{f_ext}"
            if not path.exists(safe_save_path):
                return safe_save_path
    return path_str

shellfish.sh.scandir(dirpath: FsPath = '.') -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir(dirpath: FsPath = ".") -> Iterable[DirEntry[AnyStr]]:
    """Typed version of os.scandir"""
    if not isdir(dirpath):
        raise NotADirectoryError(f"{dirpath} is not a directory")
    return cast("Iterable[DirEntry[AnyStr]]", _scandir(fspath(dirpath)))

shellfish.sh.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:

Name	Type	Description	Default
fspath	FsPath	(FsPath): dirpath to look through	'.'
recursive	bool	recursively scan the directory	False
follow_symlinks	bool	follow symlinks when checking for dirs and files	True
files	bool	include files	True
dirs	bool	include directories	True
symlinks	bool	include symlinks	True
dirs_only	bool	only include directories	False
files_only	bool	only include files	False
symlinks_only	bool	only include symlinks	False

Returns:

Type	Description
Iterator[DirEntry[str]]	Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]]:
    r"""Return an iterator of os.DirEntry objects

    Args:
        fspath: (FsPath): dirpath to look through
        recursive (bool): recursively scan the directory
        follow_symlinks (bool): follow symlinks when checking for dirs and files
        files (bool): include files
        dirs (bool): include directories
        symlinks (bool): include symlinks
        dirs_only (bool): only include directories
        files_only (bool): only include files
        symlinks_only (bool): only include symlinks

    Returns:
        Iterator[DirEntry]: Iterator of os.DirEntry objects

    Raises:
        ValueError: if any of the kwargs (`dirs`, `files` and `symlinks`) are not True

    """
    if not recursive:
        return scandir_gen_filter(
            scandir(fspath),
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )

    return scandir_gen_filter(
        chain(
            scandir(fspath),
            *(
                scandir_gen(
                    el.path,
                    recursive=True,
                    follow_symlinks=follow_symlinks,
                    files=files,
                    dirs=True,
                    symlinks=symlinks,
                    files_only=files_only,
                    dirs_only=dirs_only,
                    symlinks_only=symlinks_only,
                )
                for el in scandir(fspath)
                if el.is_dir(follow_symlinks=follow_symlinks)
            ),
        ),
        follow_symlinks=follow_symlinks,
        files=files,
        dirs=dirs,
        symlinks=symlinks,
        files_only=files_only,
        dirs_only=dirs_only,
        symlinks_only=symlinks_only,
    )

shellfish.sh.scandir_list(dirpath: FsPath = '.') -> List[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Dirpath to scan	'.'

Returns:

Type	Description
List[DirEntry[AnyStr]]	List[DirEntry]: List of os.DirEntry objects

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir_list(dirpath: FsPath = ".") -> List[DirEntry[AnyStr]]:
    """Return a list of os.DirEntry objects

    Args:
        dirpath: Dirpath to scan

    Returns:
        List[DirEntry]: List of os.DirEntry objects

    """
    return list(scandir(dirpath))

shellfish.sh.seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]

Return hr-time Tuple[int, int] (seconds, nanoseconds)

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
Tuple[int, int]	Tuple[int, int]: (seconds, nanoseconds)

Source code in libs/shellfish/shellfish/sh.py

def seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]:
    """Return hr-time Tuple[int, int] (seconds, nanoseconds)

    Args:
        seconds (float): number of seconds

    Returns:
        Tuple[int, int]: (seconds, nanoseconds)

    """
    _sec, _ns = divmod(int(seconds * 1_000_000_000), 1_000_000_000)
    return _sec, _ns

shellfish.sh.sep_join(path_strings: Iterator[str]) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_join(path_strings: Iterator[str]) -> str:
    """Join iterable of strings on the current platform os.path.sep value"""
    return sep.join(path_strings)

shellfish.sh.sep_lstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_lstrip(fspath: FsPath) -> str:
    """Left-strip a string of the current platform's os.path.sep value"""
    return str(fspath).lstrip(sep)

shellfish.sh.sep_rstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_rstrip(fspath: FsPath) -> str:
    """Right-strip a string of the current platform's os.path.sep value"""
    return str(fspath).rstrip(sep)

shellfish.sh.sep_split(fspath: FsPath) -> Tuple[str, ...]

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_split(fspath: FsPath) -> Tuple[str, ...]:
    """Split a string on the current platform os.path.sep value"""
    return tuple(el for el in str(fspath).split(sep) if el != sep and el != "")

shellfish.sh.sep_strip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_strip(fspath: FsPath) -> str:
    """Strip a string of the current platform's os.path.sep value"""
    return str(fspath).strip(sep)

shellfish.sh.setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Returns:

Type	Description
Tuple[str, str]	Tuple[str, str]: environment variable key/value pair

Source code in libs/shellfish/shellfish/sh.py

def setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Returns:
        Tuple[str, str]: environment variable key/value pair

    """
    return export(key=key, val=val)

shellfish.sh.shebang(fspath: FsPath) -> Union[None, str]

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file that might have a shebang	required

Returns:

Type	Description
Union[None, str]	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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def shebang(fspath: FsPath) -> Union[None, str]:
    r"""Get the shebang string given a fspath; Returns None if no shebang

    Args:
        fspath (FsPath): Path to file that might have a shebang

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

    """
    with open(fspath) as f:
        first = f.readline().replace("\r\n", "\n").strip("\n")
        return first if "#!" in first[:2] else None

shellfish.sh.shell(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, shell: bool = True, extenv: bool = True, cwd: Optional[FsPath] = None, check: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously in current shell

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
shell	bool	Run in shell or sub-shell; default is True for shx	True
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check if ok	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

def shell(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    shell: bool = True,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    check: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously in current shell

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        shell: Run in shell or sub-shell; default is True for `shx`
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check if ok
        dryrun: Don't run the subprocess


    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return do(
        *popenargs,
        args=args,
        shell=shell,
        env=env,
        extenv=extenv,
        cwd=cwd,
        check=check,
        verbose=verbose,
        input=input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]

Typed alias for shlex.split

Source code in libs/shellfish/shellfish/sh.py

def shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]:
    """Typed alias for shlex.split"""
    return _shplit(string, comments=comments, posix=posix)

shellfish.sh.source(filepath: FsPath, _globals: bool = True) -> None

Execute/run a python file given a fspath and put globals in globasl

Parameters:

Name	Type	Description	Default
filepath	FsPath	Path to python file	required
_globals	bool	Exec using globals	True

Source code in libs/shellfish/shellfish/sh.py

def source(filepath: FsPath, _globals: bool = True) -> None:  # pragma: nocov
    """Execute/run a python file given a fspath and put globals in globasl

    Args:
        filepath (FsPath): Path to python file
        _globals (bool): Exec using globals

    """
    string = fs.lstring(str(filepath))
    if _globals:
        exec(string, globals())
    else:
        exec(string)

shellfish.sh.stat(fspath: FsPath) -> os_stat_result

Return the os.stat_result object for a given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory	required

Returns:

Type	Description
stat_result	os.stat_result: stat_result object

Source code in libs/shellfish/shellfish/fs/__init__.py

def stat(fspath: FsPath) -> os_stat_result:
    """Return the os.stat_result object for a given fspath

    Args:
        fspath (FsPath): Path to file or directory

    Returns:
        os.stat_result: stat_result object

    """
    return _stat(_fspath(fspath))

shellfish.sh.stat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

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

Create an empty file given a fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path for where to make an empty file	required
mkdirp	bool	Make parent directories if they don't exist	True

Source code in libs/shellfish/shellfish/fs/__init__.py

def touch(fspath: FsPath, *, mkdirp: bool = True) -> None:
    """Create an empty file given a fspath

    Args:
        fspath (FsPath): File-system path for where to make an empty file
        mkdirp (bool): Make parent directories if they don't exist

    """
    if not path.exists(str(fspath)):
        if mkdirp:
            parent_dir = path.dirname(str(fspath))
            if parent_dir:
                _makedirs(parent_dir, exist_ok=True)
        with open(fspath, "a"):
            utime(fspath, None)

shellfish.sh.tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str

Create a directory tree string given a directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory string to make tree for	required
filterfn	Optional[Callable[[str], bool]]	Function to filter sub-directories and sub-files with	None

Returns:

Name	Type	Description
str	str	Directory-tree string

Examples:

>>> tmpdir = 'tree.doctest'
>>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
>>> from pathlib import Path
>>> 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"),
... ]
>>> 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)
...     Path(fspath).touch()
>>> print(tree(tmpdir))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── file1.txt
    ├── file2.txt
    └── file3.txt
>>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   └── file3.txt
    ├── file1.txt
    └── file3.txt
>>> from shutil import rmtree
>>> rmtree(tmpdir)

Source code in libs/shellfish/shellfish/sh.py

def tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str:
    """Create a directory tree string given a directory path

    Args:
        dirpath (FsPath): Directory string to make tree for
        filterfn: Function to filter sub-directories and sub-files with

    Returns:
        str: Directory-tree string

    Examples:
        >>> tmpdir = 'tree.doctest'
        >>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
        >>> from pathlib import Path
        >>> 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"),
        ... ]
        >>> 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)
        ...     Path(fspath).touch()
        >>> print(tree(tmpdir))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── file1.txt
            ├── file2.txt
            └── file3.txt
        >>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   └── file3.txt
            ├── file1.txt
            └── file3.txt
        >>> from shutil import rmtree
        >>> rmtree(tmpdir)

    """
    return "\n".join(
        p.displayable() for p in _DirTree.make_tree(Path(dirpath), filterfn=filterfn)
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield all paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        (
            str(path_string)
            if abspath
            else str(path_string).replace(dirpath, "").strip(sep)
        )
        for path_string in chain.from_iterable(
            (
                pwd,
                *(path.join(pwd, _file) for _file in files),
            )
            for pwd, dirs, files in walk(
                dirpath,
                topdown=topdown,
                followlinks=followlinks,
                onerror=onerror,
            )
        )
    )

shellfish.sh.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = 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:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        filepath: fspath to write to
        bites: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

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

    """
    _write_mode = "ab" if append else "wb"
    with open(filepath, _write_mode) as fd:
        nbytes = fd.write(bites)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes

shellfish.sh.wbytes_async(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.sh.wbytes_gen(filepath: FsPath, bytes_gen: Iterable[bytes], append: bool = False, chmod: Optional[int] = None) -> int

Write/Save bytes to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Iterable[bytes]	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

>>> from shellfish.fs import rbytes, wbytes
>>> 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!')
>>> wbytes_gen(fspath, (b for b in bites_to_save))
35
>>> rbytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/Save bytes to a fspath

    Args:
        filepath: fspath to write to
        bytes_gen: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

    Examples:
        >>> from shellfish.fs import rbytes, wbytes
        >>> 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!')
        >>> wbytes_gen(fspath, (b for b in bites_to_save))
        35
        >>> rbytes(fspath)
        b'These are some bytes... more bytes!'
        >>> import os; os.remove(fspath)

    """
    _mode = const.ab if append else const.wb
    with open(filepath, mode=_mode) as fd:
        nbytes_written = sum(fd.write(chunk) for chunk in bytes_gen)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes_written

shellfish.sh.wbytes_gen_async(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.sh.where(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which; alias of shellfish.sh.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def where(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`; alias of shellfish.sh.which

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

shellfish.sh.which(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def which(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return _which(cmd, path=path)

shellfish.sh.which_lru(cmd: str, path: Optional[str] = None) -> Optional[str] cached

Return the result of shutil.which and cache the results

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

@lru_cache(maxsize=128)
def which_lru(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which` and cache the results

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

shellfish.sh.wjson(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, chmod: Optional[int] = None, append: bool = False, **kwargs: Any) -> int

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Append a newline to the end of the file	False
default	Optional[Callable[[Any], Any]]	default function hook	None
chmod	Optional[int]	Optional chmod to set on file	None
append	bool	Append to the file if True, overwrite otherwise; default	False
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dumpb	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wjson(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    chmod: Optional[int] = None,
    append: bool = False,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Append a newline to the end of the file
        default: default function hook
        chmod (Optional[int]): Optional chmod to set on file
        append (bool): Append to the file if True, overwrite otherwise; default
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dumpb

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)


    """
    return wbytes(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        chmod=chmod,
        append=append,
    )

shellfish.sh.wjson_async(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, append: bool = False, chmod: Optional[int] = None, **kwargs: Any) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Sort the data keys if the data is a dictionary.	False
default	Optional[Callable[[Any], Any]]	default function hook	None
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dump	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wjson_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    append: bool = False,
    chmod: Optional[int] = None,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Sort the data keys if the data is a dictionary.
        default: default function hook
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dump

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "wjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    return await wbytes_async(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        append=append,
        chmod=chmod,
    )

shellfish.sh.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int

Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	String encoding to write file with	'utf-8'
append	bool	Flag to append to file; default = False	False
chmod	Optional[int]	Optional chmod to set on file	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wstring(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding: String encoding to write file with
        append (bool): Flag to append to file; default = False
        chmod (Optional[int]): Optional chmod to set on file

    Returns:
        None

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

    """
    return wbytes(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.sh.wstring_async(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

Modules

shellfish.sp

Classes

shellfish.sp.ProcessDt(ti: float, tf: float, dt: float, __slots__=('ti', 'tf', 'dt')) dataclass

Process time delta dataclass

Examples:

>>> from shellfish.sp import ProcessDt
>>> ti = 0
>>> tf = 1
>>> dt = ProcessDt.from_titf(ti=ti, tf=tf)
>>> dt
ProcessDt(ti=0, tf=1, dt=1)

Functions

shellfish.sp.completed_process_dict(completed_process: CompletedProcess[str]) -> CompletedProcessDict

Convert CompletedProcess to CompletedProcessObj (typed dict)

Parameters:

Name	Type	Description	Default
completed_process	CompletedProcess[str]	CompletedProcess object	required

Returns:

Type	Description
CompletedProcessDict	CompletedProcessObj typed dict

Examples:

>>> from subprocess import CompletedProcess
>>> from shellfish.sp import completed_process_dict
>>> cp = CompletedProcess(
...     args=['some', 'args'],
...     stdout="stdout string",
...     stderr="stderr string",
...     returncode=0
... )
>>> from pprint import pprint
>>> cp_typed_dict = completed_process_dict(completed_process=cp)
>>> pprint(cp_typed_dict)
{'args': ['some', 'args'],
 'returncode': 0,
 'stderr': 'stderr string',
 'stdout': 'stdout string'}

Source code in libs/shellfish/shellfish/sp.py

def completed_process_dict(
    completed_process: CompletedProcess[str],
) -> CompletedProcessDict:
    """Convert CompletedProcess to CompletedProcessObj (typed dict)

    Args:
        completed_process: CompletedProcess object

    Returns:
        CompletedProcessObj typed dict

    Examples:
        >>> from subprocess import CompletedProcess
        >>> from shellfish.sp import completed_process_dict
        >>> cp = CompletedProcess(
        ...     args=['some', 'args'],
        ...     stdout="stdout string",
        ...     stderr="stderr string",
        ...     returncode=0
        ... )
        >>> from pprint import pprint
        >>> cp_typed_dict = completed_process_dict(completed_process=cp)
        >>> pprint(cp_typed_dict)
        {'args': ['some', 'args'],
         'returncode': 0,
         'stderr': 'stderr string',
         'stdout': 'stdout string'}

    """
    if not isinstance(completed_process, CompletedProcess):  # pragma: nocov
        raise TypeError(
            f"completed_process must be CompletedProcess object, not {type(completed_process)}"
        )
    return CompletedProcessDict(
        args=completed_process.args,
        stdout=completed_process.stdout,
        stderr=completed_process.stderr,
        returncode=completed_process.returncode,
    )

shellfish.sp.pcheck(process: CompletedProcess[Any], ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0) -> None

Parameters:

Name	Type	Description	Default
process	CompletedProcess[Any]	CompletedProcess object	required
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	OK code or sequence of codes, default is 0	0

Returns:

Type	Description
None	None

Raises:

Type	Description
CompletedProcessError	if process.returncode not in ok_code

Source code in libs/shellfish/shellfish/sp.py

def pcheck(
    process: CompletedProcess[Any],
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
) -> None:
    """

    Args:
        process: CompletedProcess object
        ok_code: OK code or sequence of codes, default is 0

    Returns:
        None

    Raises:
        CompletedProcessError: if process.returncode not in ok_code

    """
    if isinstance(ok_code, int):
        if process.returncode != ok_code:
            raise CalledProcessError(
                process.returncode,
                process.args,
                output=process.stdout,
                stderr=process.stderr,
            )
    else:
        if process.returncode not in ok_code:
            raise CalledProcessError(
                process.returncode,
                process.args,
                output=process.stdout,
                stderr=process.stderr,
            )

shellfish.sp.runs(args: PopenArgs, *, executable: Optional[str] = None, stdin: Optional[Union[IO[Any], int]] = None, input: Optional[str] = None, stdout: Optional[Union[IO[Any], int]] = None, stderr: Optional[Union[IO[Any], int]] = None, shell: bool = False, cwd: Optional[FsPath] = None, timeout: Optional[float] = None, capture_output: bool = False, check: bool = False, env: Optional[Mapping[str, str]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, **other_popen_kwargs: Any) -> CompletedProcess[str]

Run command with txt output

Source code in libs/shellfish/shellfish/sp.py

def runs(
    args: PopenArgs,
    *,
    executable: Optional[str] = None,
    stdin: Optional[Union[IO[Any], int]] = None,
    input: Optional[str] = None,
    stdout: Optional[Union[IO[Any], int]] = None,
    stderr: Optional[Union[IO[Any], int]] = None,
    shell: bool = False,
    cwd: Optional[FsPath] = None,
    timeout: Optional[float] = None,
    capture_output: bool = False,
    check: bool = False,
    env: Optional[Mapping[str, str]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    **other_popen_kwargs: Any,
) -> CompletedProcess[str]:
    """Run command with txt output"""
    process = run(
        args=args,
        input=input,
        executable=executable,
        stdin=stdin,
        stdout=stdout,
        stderr=stderr,
        shell=shell,
        cwd=cwd,
        timeout=timeout,
        env=env,
        capture_output=capture_output,
        text=True,
        **other_popen_kwargs,
    )
    if check:
        pcheck(process=process, ok_code=ok_code)
    return process

shellfish.stdio

stdio utils

Classes

shellfish.stdio.Stdio

Bases: IntEnum

Standard-io enum object

shellfish.testing

Functions

shellfish.testing.mk_random_dirtree(dest: Optional[str] = None, n_subdirectories: int = 8, max_subdirectory_files: int = 4, max_file_string_len: int = 100) -> Dict[str, List[str]]

Make a random directory tree full of dummy files at a given dirpath

Source code in libs/shellfish/shellfish/testing.py

def mk_random_dirtree(
    dest: Optional[str] = None,
    n_subdirectories: int = 8,
    max_subdirectory_files: int = 4,
    max_file_string_len: int = 100,
) -> Dict[str, List[str]]:
    """Make a random directory tree full of dummy files at a given dirpath"""
    dest = dest or getcwd()
    dirpaths = [random_directory_path() for i in range(n_subdirectories)]
    all_dirpaths = []
    for dp in dirpaths:
        all_dirpaths.append(dp)
        split_dp = dp.split(sep)
        for ix, _ in enumerate(split_dp, start=1):
            sub_dp = sep.join(split_dp[:ix])
            all_dirpaths.append(sub_dp)
    all_dirpaths = [path.join(dest, dp) for dp in all_dirpaths]
    all_filepaths = []
    for dp in all_dirpaths:
        makedirs(dp, exist_ok=True)
        for _i in range(randint(1, max_subdirectory_files)):
            file_string = random_string(randint(10, max_file_string_len))
            file_name = random_string(5) + ".txt"
            file_path = path.join(dp, file_name)
            all_filepaths.append(file_path)
            wstring(file_path, file_string)
    return {"dirpaths": all_dirpaths, "filepaths": all_filepaths}

shellfish.testing.random_directory_path(depth: int = 4) -> str

Return a random directory path with a given depth (defaults to 4)

Examples:

>>> from os import sep
>>> dirpath = random_directory_path(4)
>>> len(dirpath.split(sep)) == 4
True

Source code in libs/shellfish/shellfish/testing.py

def random_directory_path(depth: int = 4) -> str:
    """Return a random directory path with a given depth (defaults to 4)

    Examples:
        >>> from os import sep
        >>> dirpath = random_directory_path(4)
        >>> len(dirpath.split(sep)) == 4
        True

    """
    return str(path.join(*(random_string(randint(1, 5)) for s in range(depth))))

shellfish.testing.random_string(length: int = 10) -> str

Return a random string of a given length (defaults to 10)

Examples:

>>> string = random_string(10)
>>> len(string) == 10
True

Source code in libs/shellfish/shellfish/testing.py

def random_string(length: int = 10) -> str:
    """Return a random string of a given length (defaults to 10)

    Examples:
        >>> string = random_string(10)
        >>> len(string) == 10
        True

    """
    return "".join(
        rand_choice(string.ascii_letters + string.digits) for _ in range(length)
    )

shellfish.tests

shellfish dist tests

Modules

shellfish.tests.test_fs

Testing shelfish.fs

Functions

shellfish.tests.test_fs.test_is_file_dir_link(tmp_path: Path) -> None

Test is_file

Source code in libs/shellfish/shellfish/tests/test_fs.py

def test_is_file_dir_link(tmp_path: Path) -> None:
    """Test is_file"""
    sh.cd(tmp_path)
    test_filename = "file1.txt"
    test_dirname = "dir1"
    assert not sh.dir_exists(test_filename)
    assert not sh.exists(test_filename)
    assert not sh.file_exists(test_filename)
    assert not sh.is_dir(test_filename)
    assert not sh.is_file(test_filename)
    assert not sh.is_link(test_filename)
    assert not sh.isdir(test_filename)
    assert not sh.isfile(test_filename)
    assert not sh.islink(test_filename)

    # make dir and file
    sh.mkdir(test_dirname)
    sh.touch(test_filename)

    assert sh.is_file(test_filename)
    assert sh.isfile(test_filename)
    assert sh.is_dir(test_dirname)
    assert sh.isdir(test_dirname)
    assert sh.exists(test_dirname)
    assert sh.exists(test_filename)

    assert not sh.is_dir(test_filename)
    assert not sh.is_file(test_dirname)
    assert not sh.is_link(test_dirname)
    assert not sh.is_link(test_filename)
    assert not sh.isdir(test_filename)
    assert not sh.isfile(test_dirname)
    assert not sh.islink(test_dirname)
    assert not sh.islink(test_filename)

shellfish.tests.test_fs.test_is_file_dir_link_async(tmp_path: Path) -> None async

Test is_file

Source code in libs/shellfish/shellfish/tests/test_fs.py

@pytest.mark.asyncio
async def test_is_file_dir_link_async(tmp_path: Path) -> None:
    """Test is_file"""
    sh.cd(tmp_path)
    _filename = "file1.txt"
    _dirname = "dir1"
    assert not await sh.exists_async(_filename)
    assert not await sh.dir_exists_async(_filename)
    assert not await sh.file_exists_async(_filename)
    assert not await sh.is_file_async(_filename)
    assert not await sh.is_link_async(_filename)
    assert not await sh.is_dir_async(_filename)
    assert not await sh.isfile_async(_filename)
    assert not await sh.islink_async(_filename)
    assert not await sh.isdir_async(_filename)

    # make dir and file
    sh.mkdir(_dirname)
    sh.touch(_filename)

    assert await sh.is_file_async(_filename)
    assert await sh.isfile_async(_filename)
    assert await sh.is_dir_async(_dirname)
    assert await sh.isdir_async(_dirname)

    assert not sh.is_dir(_filename)
    assert not sh.is_file(_dirname)
    assert not sh.is_link(_dirname)
    assert not sh.is_link(_filename)
    assert not sh.isdir(_filename)
    assert not sh.isfile(_dirname)
    assert not sh.islink(_dirname)
    assert not sh.islink(_filename)

    stat_res = await sh.stat_async(_filename)
    assert stat_res.st_size == 0

Modules

---

shellfish.fs

file-system utils

Classes

shellfish.fs.Stdio

Bases: IntEnum

Standard-io enum object

Functions

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

Change the access permissions of a file

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file to chmod	required
mode	int	Permissions mode as an int	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def chmod(fspath: FsPath, mode: int) -> None:
    """Change the access permissions of a file

    Args:
        fspath (FsPath): Path to file to chmod
        mode (int): Permissions mode as an int

    """
    return _chmod(path=str(fspath), mode=mode)

shellfish.fs.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:

Name	Type	Description	Default
src	str	Source fspath	required
dest	str	Destination fspath	required
dryrun	bool	Do not copy file if True just return the src and dest	False
mkdirp	bool	Create parent directories if they do not exist	False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source fspath
        dest (str): Destination fspath
        dryrun (bool): Do not copy file if True just return the src and dest
        mkdirp (bool): Create parent directories if they do not exist

    """
    _dest = Path(dest)
    if not dryrun and mkdirp:
        _dest.parent.mkdir(parents=mkdirp, exist_ok=True)
    elif not _dest.parent.exists() or not _dest.parent.is_dir():
        raise FileNotFoundError(f"Destination directory {_dest.parent} does not exist")
    if not dryrun:
        wbytes_gen(dest, lbytes_gen(src, blocksize=2**18))
        _copystat(src, dest, follow_symlinks=True)
    return (str(src), str(dest))

shellfish.fs.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:

Name	Type	Description	Default
src	str	Source directory/file to copy	required
dest	FsPath	Destination directory/file to copy	required
force	bool	Force the copy (like -f flag for cp in shell)	True
recursive	bool	Recursive copy (like -r flag for cp in shell)	False
r	bool	alias for recursive	False
f	bool	alias for force	True

Raises:

Type	Description
ValueError	If src is a directory and recursive and r are both False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source directory/file to copy
        dest: Destination directory/file to copy
        force: Force the copy (like -f flag for cp in shell)
        recursive: Recursive copy (like -r flag for cp in shell)
        r: alias for recursive
        f: alias for force

    Raises:
        ValueError: If src is a directory and recursive and r are both `False`

    """
    _recursive = recursive or r
    _force = force or f
    for _src in iglob(_fspath(src), recursive=True):
        _dest = dest
        if (path.exists(dest) and not _force) or _src == dest:
            return
        if path.isdir(_src) and not _recursive:
            raise ValueError("Source ({}) is directory; use r=True")
        if path.isfile(_src) and path.isdir(dest):
            _dest = path.join(dest, path.basename(_src))
        if path.isfile(_src) or path.islink(src):
            copy_file(_src, _dest)
        if path.isdir(_src):
            if not path.exists(dest):
                _makedirs(dest)
            copytree(src, dest, dirs_exist_ok=True)

shellfish.fs.dir_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dir_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isdir"""
    return isdir(fspath)

shellfish.fs.dir_exists_async(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

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

Yield all dirpaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all dirpaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in dirs_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield directory-paths beneath a dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        dirpath if abspath else str(dirpath).replace(dirpath, "").strip(sep)
        for dirpath in (
            pwd
            for pwd, dirs, files in walk(
                str(dirpath),
                onerror=onerror,
                topdown=topdown,
                followlinks=followlinks,
            )
        )
    )

shellfish.fs.exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise"""
    return path.exists(_fspath(fspath))

shellfish.fs.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'

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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'

    """
    if period:
        return "".join(Path(fspath).suffixes)
    return "".join(Path(fspath).suffixes).lstrip(".")

shellfish.fs.file_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isfile"""
    return isfile(fspath)

shellfish.fs.file_exists_async(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

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

Yield lines from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	File to yield lines from	required
keepends	bool	Flag to keep the ends of the file lines	True

Yields:

Type	Description
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 wstring
>>> wstring(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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_lines_gen(filepath: FsPath, keepends: bool = True) -> Iterable[str]:
    r"""Yield lines from a given fspath

    Args:
        filepath: File to yield lines from
        keepends: Flag to keep the ends of the file lines

    Yields:
        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 wstring
        >>> wstring(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)


    """
    with open(filepath) as f:
        if keepends:
            yield from (line for line in f)
        else:
            yield from (line.rstrip("\n").rstrip("\r\n") for line in f)

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

Compare 2 files for equality given their filepaths

Parameters:

Name	Type	Description	Default
left	FsPath	Filepath 1	required
right	FsPath	Filepath 2	required
shallow	bool	Check only size and modification time if True	True
blocksize	int	Chunk size to read files	65536

Returns:

Type	Description
bool	True if files are equal, False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool:
    """Compare 2 files for equality given their filepaths

    Args:
        left (FsPath): Filepath 1
        right (FsPath): Filepath 2
        shallow (bool): Check only size and modification time if True
        blocksize (int): Chunk size to read files

    Returns:
        True if files are equal, False otherwise

    """
    left_stat = stat(left)
    right_stat = stat(right)
    if (
        shallow
        and left_stat.st_size == right_stat.st_size
        and left_stat.st_mtime == right_stat.st_mtime
    ):
        return True
    if left_stat.st_size != right_stat.st_size:
        return False
    return not any(
        left_chunk != right_chunk
        for left_chunk, right_chunk in zip(
            rbytes_gen(left, blocksize=blocksize),
            rbytes_gen(right, blocksize=blocksize),
        )
    )

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in files_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.fs.filepath_mtimedelta_sec(filepath: FsPath) -> float

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_mtimedelta_sec(filepath: FsPath) -> float:
    """Return the seconds since the file(path) was last modified"""
    return time() - path.getmtime(_fspath(filepath))

shellfish.fs.files_dirs_gen(dirpath: FsPath = '.', *, abspath: bool = True, topdown: bool = True, onerror: Optional[Callable[[OSError], Any]] = 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:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath is a directory	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Tuple[Iterator[str], Iterator[str]]:
    r"""Return a files_gen() and a dirs_gen() in one swell-foop

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath is a directory

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

    """
    return files_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    ), dirs_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield file-paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        filepath if abspath else str(filepath).replace(dirpath, "").strip(sep)
        for filepath in (
            path.join(pwd, filename)
            for pwd, dirs, files in walk(
                str(dirpath),
                topdown=topdown,
                onerror=onerror,
                followlinks=followlinks,
            )
            for filename in files
        )
    )

shellfish.fs.filesize(fspath: FsPath) -> int

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath as a string or pathlib.Path object	required

Returns:

Name	Type	Description
int	int	size of the fspath in bytes

Source code in libs/shellfish/shellfish/fs/__init__.py

def filesize(fspath: FsPath) -> int:
    """Return the size of the given file(path) in bytes

    Args:
        fspath (FsPath): Filepath as a string or pathlib.Path object

    Returns:
        int: size of the fspath in bytes

    """
    return stat(fspath).st_size

shellfish.fs.filesize_async(fspath: FsPath) -> int async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def 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

    """
    _stat_res = await aios.stat(str(fspath))
    return _stat_res.st_size

shellfish.fs.fspath(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def fspath(fspath: FsPath) -> str:
    """Alias for os._fspath; returns fspath string for any type of path"""
    return _fspath(fspath)

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

Return an iterator of fspaths matching the given glob pattern

Parameters:

Name	Type	Description	Default
pattern	str	Glob pattern	required
recursive	bool	Recursively search directories if True	False
r	bool	Recursively search directories if True (Alias for recursive)	False

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def glob(pattern: str, *, recursive: bool = False, r: bool = False) -> Iterator[str]:
    """Return an iterator of fspaths matching the given glob pattern

    Args:
        pattern: Glob pattern
        recursive: Recursively search directories if True
        r: Recursively search directories if True (Alias for recursive)

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

    """
    return iglob(pattern, recursive=recursive or r)

shellfish.fs.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish.fs.is_dir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.fs.is_file(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_file(fspath: FsPath) -> bool:
    """Return True if the given path is a file; alias for isfile"""
    return isfile(fspath)

shellfish.fs.is_file_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.fs.is_link(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_link(fspath: FsPath) -> bool:
    """Return True if the given path is a link; alias for islink"""
    return islink(fspath)

shellfish.fs.is_link_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.fs.isdir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isdir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; False otherwise"""
    return path.isdir(_fspath(fspath))

shellfish.fs.isdir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.isfile(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isfile(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return path.isfile(_fspath(fspath))

shellfish.fs.isfile_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.islink(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def islink(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return path.islink(_fspath(fspath))

shellfish.fs.islink_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.fs.listdir_async(fspath: FsPath) -> List[str] async

Async version of os.listdir

Source code in libs/shellfish/shellfish/fs/_async.py

async def listdir_async(fspath: FsPath) -> List[str]:
    """Async version of `os.listdir`"""
    return await aios.listdir(_fspath(fspath))

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]:
    r"""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

    """
    _attr = "path" if abspath else "name"
    return (
        getattr(el, _attr)
        for el in scandir_gen(
            fspath,
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )
    )

shellfish.fs.lstat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

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

Make directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to create	required
parents	bool	Make parent dirs if True; do not make parent dirs if False	False
p	bool	Make parent dirs if True; do not make parent dirs if False (alias of parents)	False
exist_ok	bool	Throw error if directory exists and exist_ok is False	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdir(
    fspath: FsPath, *, parents: bool = False, p: bool = False, exist_ok: bool = False
) -> None:
    """Make directory at given fspath

    Args:
        fspath (FsPath): Directory path to create
        parents (bool): Make parent dirs if True; do not make parent dirs if False
        p (bool): Make parent dirs if True; do not make parent dirs if False (alias of parents)
        exist_ok (bool): Throw error if directory exists and exist_ok is False

    Returns:
         None

    """
    _parents = parents or p
    if _parents or exist_ok:
        return _makedirs(_fspath(fspath), exist_ok=_parents or exist_ok)
    return _mkdir(_fspath(fspath))

shellfish.fs.mkdirp(fspath: FsPath) -> None

Make directory and parents

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdirp(fspath: FsPath) -> None:
    """Make directory and parents"""
    return mkdir(fspath=fspath, parents=True)

shellfish.fs.move(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def move(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    _dst_str = str(dest)
    for file in iglob(str(src), recursive=True):
        _move(file, _dst_str)

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in walk_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.fs.rbytes(filepath: FsPath) -> bytes

Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes(filepath: FsPath) -> bytes:
    """Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    with open(filepath, "rb") as file:
        return bytes(file.read())

shellfish.fs.rbytes_async(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.fs.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]

Yield bytes from a given fspath

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]:
    """Yield bytes from a given fspath"""
    with open(filepath, "rb") as f:
        while True:
            data = f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.rbytes_gen_async(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.rjson(filepath: FsPath) -> Any

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def rjson(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)

    """
    return JSON.loads(lstring(filepath=filepath))

shellfish.fs.rjson_async(filepath: FsPath) -> Any async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rjson_async(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    json_string = await rbytes_async(filepath)
    return JSON.loads(json_string)

shellfish.fs.rm(fspath: FsPath, *, force: bool = False, recursive: bool = False, dryrun: bool = False, verbose: bool = False) -> Union[List[str], None]

Remove files & directories in the style of the shell Args: fspath (FsPath): Path to file or directory to remove force (bool): ignore errors and missing files/dirs; default is False recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    dryrun: bool = False,
    verbose: bool = False,
) -> Union[List[str], None]:
    """Remove files & directories in the style of the shell
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): ignore errors and missing files/dirs; default is False
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if verbose:
        return list(
            rm_gen(fspath=fspath, force=force, recursive=recursive, dryrun=dryrun)
        )
    else:
        exhaust(rm_gen(fspath=fspath, force=force, recursive=recursive, dryrun=dryrun))
        return None

shellfish.fs.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 Args: fspath (FsPath): Path to file or directory to remove force (bool): Force removal of files and directories recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Force removal of files and directories
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if has_magic(str(fspath)):
        if dryrun:
            yield from iglob(_fspath(fspath), recursive=recursive)
        else:
            for _path_str in iglob(str(fspath), recursive=recursive):
                if isfile(_path_str):
                    remove(_path_str)
                elif recursive:
                    rmdir(_path_str, recursive=True, force=force)
                else:
                    raise ValueError(
                        f"{str(_path_str)} (under {str(fspath)}) is a directory -- use r=True or recursive=True"
                    )
    else:
        if isfile(fspath):
            if not dryrun:
                remove(_fspath(fspath))
            yield _fspath(fspath)
        elif recursive:
            if not dryrun:
                rmdir(fspath, force=force, recursive=True)
            yield _fspath(fspath)
        else:
            raise ValueError(
                f"{str(fspath)} is a directory -- use r=True or recursive=True"
            )

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

Remove directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to remove	required
force	bool	Force removal of files and directories	False
recursive	bool	Recursively remove all contents if True	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmdir(fspath: FsPath, *, force: bool = False, recursive: bool = False) -> None:
    """Remove directory at given fspath

    Args:
        fspath (FsPath): Directory path to remove
        force (bool): Force removal of files and directories
        recursive (bool): Recursively remove all contents if True

    Returns:
        None

    """
    if force:
        try:
            return rmdir(fspath, recursive=recursive)
        except FileNotFoundError:
            return
    if recursive:
        return rmtree(_fspath(fspath))
    return _rmdir(_fspath(fspath))

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

Remove a file at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath to remove	required
dryrun	bool	Do not remove file if True	False

Returns:

Type	Description
str	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmfile(fspath: FsPath, *, dryrun: bool = False) -> str:
    """Remove a file at given fspath

    Args:
        fspath (FsPath): Filepath to remove
        dryrun (bool): Do not remove file if True

    Returns:
        None

    """
    if not dryrun:
        remove(_fspath(fspath))
    return _fspath(fspath)

shellfish.fs.rstring(filepath: FsPath, *, encoding: str = 'utf-8') -> str

Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	Encoding to use for reading the file	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rstring(filepath: FsPath, *, encoding: str = "utf-8") -> str:
    r"""Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding: Encoding to use for reading the file

    Returns:
        str: String read from given fspath

    Examples:
        ``` python
        >>> from shellfish.fs import rstring, wstring
        >>> fspath = "lstring.doctest.txt"
        >>> sstring(fspath, r'Check out this string')
        21
        >>> lstring(fspath)
        'Check out this string'
        >>> import os; os.remove(fspath)

        ```

    """
    _bytes = rbytes(filepath=filepath)
    try:
        return _bytes.decode(encoding=encoding)
    except UnicodeDecodeError:  # Catch the unicode decode error
        pass
    return _bytes.decode(encoding="latin2")

shellfish.fs.rstring_async(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.fs.safepath(fspath: FsPath) -> str

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	file-system path; file or directory path string or Path obj	required

Returns:

Name	Type	Description
str	str	file/dir path that does not exist and contains the given path

Source code in libs/shellfish/shellfish/fs/__init__.py

def safepath(fspath: FsPath) -> str:
    """Check if a file/dir path is save/unused; returns an unused path.

    Args:
        fspath: file-system path; file or directory path string or Path obj

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

    """
    path_str = str(fspath)
    if path.exists(path_str):
        f_bn, f_ext = path.splitext(path_str)
        for n in count(1):
            safe_save_path = f"{f_bn}_{str(n).zfill(3)}.{f_ext}"
            if not path.exists(safe_save_path):
                return safe_save_path
    return path_str

shellfish.fs.scandir(dirpath: FsPath = '.') -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir(dirpath: FsPath = ".") -> Iterable[DirEntry[AnyStr]]:
    """Typed version of os.scandir"""
    if not isdir(dirpath):
        raise NotADirectoryError(f"{dirpath} is not a directory")
    return cast("Iterable[DirEntry[AnyStr]]", _scandir(fspath(dirpath)))

shellfish.fs.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:

Name	Type	Description	Default
fspath	FsPath	(FsPath): dirpath to look through	'.'
recursive	bool	recursively scan the directory	False
follow_symlinks	bool	follow symlinks when checking for dirs and files	True
files	bool	include files	True
dirs	bool	include directories	True
symlinks	bool	include symlinks	True
dirs_only	bool	only include directories	False
files_only	bool	only include files	False
symlinks_only	bool	only include symlinks	False

Returns:

Type	Description
Iterator[DirEntry[str]]	Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]]:
    r"""Return an iterator of os.DirEntry objects

    Args:
        fspath: (FsPath): dirpath to look through
        recursive (bool): recursively scan the directory
        follow_symlinks (bool): follow symlinks when checking for dirs and files
        files (bool): include files
        dirs (bool): include directories
        symlinks (bool): include symlinks
        dirs_only (bool): only include directories
        files_only (bool): only include files
        symlinks_only (bool): only include symlinks

    Returns:
        Iterator[DirEntry]: Iterator of os.DirEntry objects

    Raises:
        ValueError: if any of the kwargs (`dirs`, `files` and `symlinks`) are not True

    """
    if not recursive:
        return scandir_gen_filter(
            scandir(fspath),
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )

    return scandir_gen_filter(
        chain(
            scandir(fspath),
            *(
                scandir_gen(
                    el.path,
                    recursive=True,
                    follow_symlinks=follow_symlinks,
                    files=files,
                    dirs=True,
                    symlinks=symlinks,
                    files_only=files_only,
                    dirs_only=dirs_only,
                    symlinks_only=symlinks_only,
                )
                for el in scandir(fspath)
                if el.is_dir(follow_symlinks=follow_symlinks)
            ),
        ),
        follow_symlinks=follow_symlinks,
        files=files,
        dirs=dirs,
        symlinks=symlinks,
        files_only=files_only,
        dirs_only=dirs_only,
        symlinks_only=symlinks_only,
    )

shellfish.fs.scandir_list(dirpath: FsPath = '.') -> List[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Dirpath to scan	'.'

Returns:

Type	Description
List[DirEntry[AnyStr]]	List[DirEntry]: List of os.DirEntry objects

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir_list(dirpath: FsPath = ".") -> List[DirEntry[AnyStr]]:
    """Return a list of os.DirEntry objects

    Args:
        dirpath: Dirpath to scan

    Returns:
        List[DirEntry]: List of os.DirEntry objects

    """
    return list(scandir(dirpath))

shellfish.fs.sep_join(path_strings: Iterator[str]) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_join(path_strings: Iterator[str]) -> str:
    """Join iterable of strings on the current platform os.path.sep value"""
    return sep.join(path_strings)

shellfish.fs.sep_lstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_lstrip(fspath: FsPath) -> str:
    """Left-strip a string of the current platform's os.path.sep value"""
    return str(fspath).lstrip(sep)

shellfish.fs.sep_rstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_rstrip(fspath: FsPath) -> str:
    """Right-strip a string of the current platform's os.path.sep value"""
    return str(fspath).rstrip(sep)

shellfish.fs.sep_split(fspath: FsPath) -> Tuple[str, ...]

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_split(fspath: FsPath) -> Tuple[str, ...]:
    """Split a string on the current platform os.path.sep value"""
    return tuple(el for el in str(fspath).split(sep) if el != sep and el != "")

shellfish.fs.sep_strip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_strip(fspath: FsPath) -> str:
    """Strip a string of the current platform's os.path.sep value"""
    return str(fspath).strip(sep)

shellfish.fs.shebang(fspath: FsPath) -> Union[None, str]

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file that might have a shebang	required

Returns:

Type	Description
Union[None, str]	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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def shebang(fspath: FsPath) -> Union[None, str]:
    r"""Get the shebang string given a fspath; Returns None if no shebang

    Args:
        fspath (FsPath): Path to file that might have a shebang

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

    """
    with open(fspath) as f:
        first = f.readline().replace("\r\n", "\n").strip("\n")
        return first if "#!" in first[:2] else None

shellfish.fs.stat(fspath: FsPath) -> os_stat_result

Return the os.stat_result object for a given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory	required

Returns:

Type	Description
stat_result	os.stat_result: stat_result object

Source code in libs/shellfish/shellfish/fs/__init__.py

def stat(fspath: FsPath) -> os_stat_result:
    """Return the os.stat_result object for a given fspath

    Args:
        fspath (FsPath): Path to file or directory

    Returns:
        os.stat_result: stat_result object

    """
    return _stat(_fspath(fspath))

shellfish.fs.stat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

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

Create an empty file given a fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path for where to make an empty file	required
mkdirp	bool	Make parent directories if they don't exist	True

Source code in libs/shellfish/shellfish/fs/__init__.py

def touch(fspath: FsPath, *, mkdirp: bool = True) -> None:
    """Create an empty file given a fspath

    Args:
        fspath (FsPath): File-system path for where to make an empty file
        mkdirp (bool): Make parent directories if they don't exist

    """
    if not path.exists(str(fspath)):
        if mkdirp:
            parent_dir = path.dirname(str(fspath))
            if parent_dir:
                _makedirs(parent_dir, exist_ok=True)
        with open(fspath, "a"):
            utime(fspath, None)

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield all paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        (
            str(path_string)
            if abspath
            else str(path_string).replace(dirpath, "").strip(sep)
        )
        for path_string in chain.from_iterable(
            (
                pwd,
                *(path.join(pwd, _file) for _file in files),
            )
            for pwd, dirs, files in walk(
                dirpath,
                topdown=topdown,
                followlinks=followlinks,
                onerror=onerror,
            )
        )
    )

shellfish.fs.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = 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:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        filepath: fspath to write to
        bites: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

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

    """
    _write_mode = "ab" if append else "wb"
    with open(filepath, _write_mode) as fd:
        nbytes = fd.write(bites)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes

shellfish.fs.wbytes_async(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.fs.wbytes_gen(filepath: FsPath, bytes_gen: Iterable[bytes], append: bool = False, chmod: Optional[int] = None) -> int

Write/Save bytes to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Iterable[bytes]	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

>>> from shellfish.fs import rbytes, wbytes
>>> 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!')
>>> wbytes_gen(fspath, (b for b in bites_to_save))
35
>>> rbytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/Save bytes to a fspath

    Args:
        filepath: fspath to write to
        bytes_gen: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

    Examples:
        >>> from shellfish.fs import rbytes, wbytes
        >>> 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!')
        >>> wbytes_gen(fspath, (b for b in bites_to_save))
        35
        >>> rbytes(fspath)
        b'These are some bytes... more bytes!'
        >>> import os; os.remove(fspath)

    """
    _mode = const.ab if append else const.wb
    with open(filepath, mode=_mode) as fd:
        nbytes_written = sum(fd.write(chunk) for chunk in bytes_gen)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes_written

shellfish.fs.wbytes_gen_async(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.fs.wjson(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, chmod: Optional[int] = None, append: bool = False, **kwargs: Any) -> int

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Append a newline to the end of the file	False
default	Optional[Callable[[Any], Any]]	default function hook	None
chmod	Optional[int]	Optional chmod to set on file	None
append	bool	Append to the file if True, overwrite otherwise; default	False
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dumpb	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wjson(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    chmod: Optional[int] = None,
    append: bool = False,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Append a newline to the end of the file
        default: default function hook
        chmod (Optional[int]): Optional chmod to set on file
        append (bool): Append to the file if True, overwrite otherwise; default
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dumpb

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)


    """
    return wbytes(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        chmod=chmod,
        append=append,
    )

shellfish.fs.wjson_async(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, append: bool = False, chmod: Optional[int] = None, **kwargs: Any) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Sort the data keys if the data is a dictionary.	False
default	Optional[Callable[[Any], Any]]	default function hook	None
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dump	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wjson_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    append: bool = False,
    chmod: Optional[int] = None,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Sort the data keys if the data is a dictionary.
        default: default function hook
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dump

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "wjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    return await wbytes_async(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        append=append,
        chmod=chmod,
    )

shellfish.fs.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int

Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	String encoding to write file with	'utf-8'
append	bool	Flag to append to file; default = False	False
chmod	Optional[int]	Optional chmod to set on file	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wstring(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding: String encoding to write file with
        append (bool): Flag to append to file; default = False
        chmod (Optional[int]): Optional chmod to set on file

    Returns:
        None

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

    """
    return wbytes(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.fs.wstring_async(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

Modules

shellfish.fs.promises

shellfish.fs.promises

Functions

shellfish.fs.promises.dir_exists(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.promises.file_exists(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.promises.is_dir(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.fs.promises.is_file(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.fs.promises.is_link(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.fs.promises.isdir(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.fs.promises.isfile(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.fs.promises.islink(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.fs.promises.lstat(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

shellfish.fs.promises.rbytes(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.fs.promises.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.fs.promises.rstring(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.fs.promises.stat(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

shellfish.fs.promises.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.fs.promises.wbytes_gen(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.fs.promises.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.sh

shell utils

Classes

shellfish.sh.Done(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

PRun => 'ProcessRun' for finished processes

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.sh.Done.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.sh.Done.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.sh.Done.__ge__(filepath: FsPath) -> 'Done'

Operator overload for writing stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __ge__(self, filepath: FsPath) -> "Done":
    """Operator overload for writing stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath)
    return self

shellfish.sh.Done.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.sh.Done.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.sh.Done.__gt__(filepath: FsPath) -> None

Operator overload for writing a stdout to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __gt__(self, filepath: FsPath) -> None:
    """Operator overload for writing a stdout to a fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath)

shellfish.sh.Done.__irshift__(filepath: FsPath) -> 'Done'

Operator overload for appending stderr to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required

Returns:

Type	Description
'Done'	Done object; self

Source code in libs/shellfish/shellfish/sh.py

def __irshift__(self, filepath: FsPath) -> "Done":
    """Operator overload for appending stderr to fspath

    Args:
        filepath: Filepath of location to write stderr

    Returns:
        Done object; self

    """
    self.write_stderr(filepath, append=True)
    return self

shellfish.sh.Done.__post_init__() -> None

Write the stdout/stdout to sys.stdout/sys.stderr post object init

Source code in libs/shellfish/shellfish/sh.py

def __post_init__(self) -> None:
    """Write the stdout/stdout to sys.stdout/sys.stderr post object init"""
    if self.verbose:
        self.sys_print()

shellfish.sh.Done.__rshift__(filepath: FsPath) -> None

Operator overload for appending stdout to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required

Source code in libs/shellfish/shellfish/sh.py

def __rshift__(self, filepath: FsPath) -> None:
    """Operator overload for appending stdout to fspath

    Args:
        filepath: Filepath to write stdout to

    """
    self.write_stdout(filepath, append=True)

shellfish.sh.Done.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.sh.Done.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.sh.Done.check(ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0) -> None

Check returncode and stderr

Raises:

Type	Description
DoneError	If return code is non-zero and stderr is not None

Source code in libs/shellfish/shellfish/sh.py

def check(
    self,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
) -> None:
    """Check returncode and stderr

    Raises:
        DoneError: If return code is non-zero and stderr is not None

    """
    if isinstance(ok_code, int):
        if self.returncode != ok_code and self.stderr:
            raise DoneError(done=self)
    else:
        if self.returncode not in ok_code:
            raise DoneError(done=self)

shellfish.sh.Done.completed_process() -> CompletedProcess[str]

Return subprocess.CompletedProcess object

Source code in libs/shellfish/shellfish/sh.py

def completed_process(self) -> CompletedProcess[str]:
    """Return subprocess.CompletedProcess object"""
    return CompletedProcess(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
    )

shellfish.sh.Done.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.sh.Done.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.sh.Done.done_dict() -> DoneDict

Return Done object as typed-dict

Source code in libs/shellfish/shellfish/sh.py

def done_dict(self) -> DoneDict:
    """Return Done object as typed-dict"""
    return DoneDict(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_dict(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.sh.Done.done_obj() -> DoneObj

Return Done object typed dict

Source code in libs/shellfish/shellfish/sh.py

def done_obj(self) -> DoneObj:
    """Return Done object typed dict"""
    return DoneObj(
        args=self.args,
        returncode=self.returncode,
        stdout=self.stdout,
        stderr=self.stderr,
        ti=self.ti,
        tf=self.tf,
        dt=self.dt,
        hrdt=self.hrdt_obj(),
        stdin=self.stdin,
        async_proc=self.async_proc,
        verbose=self.verbose,
    )

shellfish.sh.Done.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.Done.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.sh.Done.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.Done.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.sh.Done.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.sh.Done.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.sh.Done.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.sh.Done.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.sh.Done.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.sh.Done.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.sh.Done.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.sh.Done.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.sh.Done.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.sh.Done.grep(string: str) -> List[str]

Return lines in stdout that have

Parameters:

Name	Type	Description	Default
string	str	String to search for	required

Returns:

Type	Description
List[str]	List[str]: List of strings of stdout lines containing the given search string

Source code in libs/shellfish/shellfish/sh.py

def grep(self, string: str) -> List[str]:
    """Return lines in stdout that have

    Args:
        string (str): String to search for

    Returns:
        List[str]: List of strings of stdout lines containing the given
            search string

    """
    return [
        line for line in self.stdout.splitlines(keepends=False) if string in line
    ]

shellfish.sh.Done.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.sh.Done.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.sh.Done.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.sh.Done.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.sh.Done.json_parse(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout"""
    return (
        self.json_parse_stdout(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
        if not stderr
        else self.json_parse_stderr(jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)
    )

shellfish.sh.Done.json_parse_stderr(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stderr

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stderr(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stderr"""
    return JSON.loads(self.stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.json_parse_stdout(jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout

Source code in libs/shellfish/shellfish/sh.py

def json_parse_stdout(
    self, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False
) -> Any:
    """Return json parsed stdout"""
    return JSON.loads(self.stdout, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.sh.Done.parse_json(stderr: bool = False, jsonc: bool = False, jsonl: bool = False, ndjson: bool = False) -> Any

Return json parsed stdout (alias bc I keep flip-flopping the fn name)

Source code in libs/shellfish/shellfish/sh.py

def parse_json(
    self,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any:
    """Return json parsed stdout (alias bc I keep flip-flopping the fn name)"""
    return self.json_parse(stderr=stderr, jsonc=jsonc, jsonl=jsonl, ndjson=ndjson)

shellfish.sh.Done.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.sh.Done.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.Done.sys_print() -> None

Write self.stdout to sys.stdout and self.stderr to sys.stderr

Source code in libs/shellfish/shellfish/sh.py

def sys_print(self) -> None:
    """Write self.stdout to sys.stdout and self.stderr to sys.stderr"""
    sys.stdout.write(self.stdout)
    sys.stderr.write(self.stderr)

shellfish.sh.Done.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.sh.Done.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.sh.Done.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.sh.Done.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.Done.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.sh.Done.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.sh.Done.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.sh.Done.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.sh.Done.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.sh.Done.write_stderr(filepath: FsPath, *, append: bool = False) -> None

Write stderr as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath of location to write stderr	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stderr(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stderr as a string to a fspath

    Args:
        filepath: Filepath of location to write stderr
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stderr, append=append)

shellfish.sh.Done.write_stdout(filepath: FsPath, *, append: bool = False) -> None

Write stdout as a string to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to write stdout to	required
append	bool	Flag to append to file or plain write to file	False

Source code in libs/shellfish/shellfish/sh.py

def write_stdout(self, filepath: FsPath, *, append: bool = False) -> None:
    """Write stdout as a string to a fspath

    Args:
        filepath: Filepath to write stdout to
        append (bool): Flag to append to file or plain write to file

    """
    fs.wstring(Path(filepath), self.stdout, append=append)

shellfish.sh.DoneError(done: Done)

Bases: SubprocessError

Raised when run() is called with check=True and the process returns a non-zero exit status.

Attributes:

Name	Type	Description
cmd	str	command that was run
returncode	int	exit status of the process
stdout	str	standard output (stdout) of the process
stderr	str	standard error (stderr) of the process

Source code in libs/shellfish/shellfish/sh.py

def __init__(self, done: Done) -> None:
    self.returncode = done.returncode
    self.cmd = done.args
    self.stderr = done.stderr
    self.stdout = done.stdout
    self.cmd = done.args
    self.done = done

shellfish.sh.DoneObj

Bases: TypedDict

Todo

deprecate this in favor of DoneDict

shellfish.sh.Flag

Flag obj

Examples:

>>> Flag.__help
'--help'
>>> Flag._v
'-v'

shellfish.sh.FlagMeta

Bases: type

Meta class

Functions

shellfish.sh.FlagMeta.attr2flag(string: str) -> str cached staticmethod

Convert and return attr to string

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
@lru_cache(maxsize=None)
def attr2flag(string: str) -> str:
    """Convert and return attr to string"""
    return string.replace("_", "-")

shellfish.sh.HrTime(*args: Any, **kwargs: _VT)

Bases: JsonBaseModel

High resolution time

Source code in libs/jsonbourne/jsonbourne/core.py

def __init__(
    self,
    *args: Any,
    **kwargs: _VT,
) -> None:
    """Use the object dict"""
    _data = dict(*args, **kwargs)
    super().__setattr__("_data", _data)
    if not all(isinstance(k, str) for k in self._data):
        d = {k: v for k, v in self._data.items() if not isinstance(k, str)}  # type: ignore[redundant-expr]
        raise ValueError(f"JsonObj keys MUST be strings! Bad key values: {str(d)}")
    self.recurse()
    self.__post_init__()

Attributes

shellfish.sh.HrTime.__property_fields__: Set[str] property

Returns a set of property names for the class that have a setter

Functions

shellfish.sh.HrTime.__contains__(key: _KT) -> bool

Check if a key or dot-key is contained within the JsonObj object

Parameters:

Name	Type	Description	Default
key	_KT	root level key or a dot-key	required

Returns:

Name	Type	Description
bool	bool	True if the key/dot-key is in the JsonObj; False otherwise

Examples:

>>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
>>> d = JsonObj(d)
>>> d
JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
>>> 'uno' in d
True
>>> 'this_key_is_not_in_d' in d
False
>>> 'sub.a' in d
True
>>> 'sub.d.a' in d
False

Source code in libs/jsonbourne/jsonbourne/core.py

def __contains__(self, key: _KT) -> bool:  # type: ignore[override]
    """Check if a key or dot-key is contained within the JsonObj object

    Args:
        key (_KT): root level key or a dot-key

    Returns:
        bool: True if the key/dot-key is in the JsonObj; False otherwise

    Examples:
        >>> d = {"uno": 1, "dos": 2, "tres": 3, "sub": {"a": 1, "b": 2, "c": [3, 4, 5, 6], "d": "a_string"}}
        >>> d = JsonObj(d)
        >>> d
        JsonObj(**{'uno': 1, 'dos': 2, 'tres': 3, 'sub': {'a': 1, 'b': 2, 'c': [3, 4, 5, 6], 'd': 'a_string'}})
        >>> 'uno' in d
        True
        >>> 'this_key_is_not_in_d' in d
        False
        >>> 'sub.a' in d
        True
        >>> 'sub.d.a' in d
        False

    """
    if "." in key:
        first_key, _, rest = key.partition(".")
        val = self._data.get(first_key)
        return isinstance(val, MutableMapping) and val.__contains__(rest)
    return key in self._data

shellfish.sh.HrTime.__get_type_validator__(source_type: Any, handler: GetCoreSchemaHandler) -> Iterator[Callable[[Any], Any]] classmethod

Return the JsonObj validator functions

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def __get_type_validator__(
    cls, source_type: Any, handler: GetCoreSchemaHandler
) -> Iterator[Callable[[Any], Any]]:
    """Return the JsonObj validator functions"""
    yield cls.validate_type

shellfish.sh.HrTime.__getattr__(item: _KT) -> Any

Return an attr

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> d.__getattr__('b')
2
>>> d.b
2

Source code in libs/jsonbourne/jsonbourne/core.py

def __getattr__(self, item: _KT) -> Any:
    """Return an attr

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> d.__getattr__('b')
        2
        >>> d.b
        2

    """
    if item == "_data":
        try:
            return object.__getattribute__(self, "_data")
        except AttributeError:
            return self.__dict__
    if item in _JsonObjMutableMapping_attrs or item in self._cls_protected_attrs():
        return object.__getattribute__(self, item)
    try:
        return jsonify(self.__getitem__(str(item)))
    except KeyError:
        pass
    return object.__getattribute__(self, item)

shellfish.sh.HrTime.__post_init__() -> Any

Function place holder that is called after object initialization

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def __post_init__(self) -> Any:
    """Function place holder that is called after object initialization"""

shellfish.sh.HrTime.__setitem__(key: _KT, value: _VT) -> None

Set JsonObj item with 'key' to 'value'

Parameters:

Name	Type	Description	Default
key	_KT	Key/item to set	required
value	_VT	Value to set	required

Returns:

Type	Description
None	None

Raises:

Type	Description
ValueError	If given a key that is not a valid python keyword/identifier

Examples:

>>> d = JsonObj()
>>> d.a = 123
>>> d['b'] = 321
>>> d
JsonObj(**{'a': 123, 'b': 321})
>>> d[123] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
>>> d['456'] = 'a'
>>> d
JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

Source code in libs/jsonbourne/jsonbourne/core.py

def __setitem__(self, key: _KT, value: _VT) -> None:
    """Set JsonObj item with 'key' to 'value'

    Args:
        key (_KT): Key/item to set
        value: Value to set

    Returns:
        None

    Raises:
        ValueError: If given a key that is not a valid python keyword/identifier

    Examples:
        >>> d = JsonObj()
        >>> d.a = 123
        >>> d['b'] = 321
        >>> d
        JsonObj(**{'a': 123, 'b': 321})
        >>> d[123] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a'})
        >>> d['456'] = 'a'
        >>> d
        JsonObj(**{'a': 123, 'b': 321, '123': 'a', '456': 'a'})

    """
    self.__setitem(key, value, identifier=False)

shellfish.sh.HrTime.asdict() -> Dict[_KT, Any]

Return the JsonObj object (and children) as a python dictionary

Source code in libs/jsonbourne/jsonbourne/core.py

def asdict(self) -> Dict[_KT, Any]:
    """Return the JsonObj object (and children) as a python dictionary"""
    return self.eject()

shellfish.sh.HrTime.defaults_dict() -> Dict[str, Any] classmethod

Return a dictionary of non-required keys -> default value(s)

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: Dictionary of non-required keys -> default value

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})
>>> t.defaults_dict()
{'a': 1, 'b': 'herm'}

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def defaults_dict(cls) -> Dict[str, Any]:
    """Return a dictionary of non-required keys -> default value(s)

    Returns:
        Dict[str, Any]: Dictionary of non-required keys -> default value

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})
        >>> t.defaults_dict()
        {'a': 1, 'b': 'herm'}

    """
    return {
        k: v.default for k, v in cls.model_fields.items() if not v.is_required()
    }

shellfish.sh.HrTime.dict(*args: Any, **kwargs: Any) -> Dict[str, Any]

Alias for model_dump

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def dict(self, *args: Any, **kwargs: Any) -> Dict[str, Any]:
    """Alias for `model_dump`"""
    return self.model_dump(*args, **kwargs)

shellfish.sh.HrTime.dot_items() -> Iterator[Tuple[Tuple[str, ...], _VT]]

Yield tuples of the form (dot-key, value)

OG-version

def dot_items(self) -> Iterator[Tuple[str, Any]]: return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

Readable-version

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj) or hasattr(value, 'dot_items'): yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items()) else: yield k, value

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items(self) -> Iterator[Tuple[Tuple[str, ...], _VT]]:
    """Yield tuples of the form (dot-key, value)

    OG-version:
        def dot_items(self) -> Iterator[Tuple[str, Any]]:
            return ((dk, self.dot_lookup(dk)) for dk in self.dot_keys())

    Readable-version:
        for k, value in self.items():
            value = jsonify(value)
            if isinstance(value, JsonObj) or hasattr(value, 'dot_items'):
                yield from ((f"{k}.{dk}", dv) for dk, dv in value.dot_items())
            else:
                yield k, value
    """

    return chain.from_iterable(
        (
            (
                (
                    *(
                        (
                            (
                                str(k),
                                *dk,
                            ),
                            dv,
                        )
                        for dk, dv in as_json_obj(v).dot_items()
                    ),
                )
                if isinstance(v, (JsonObj, dict))
                else (((str(k),), v),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.HrTime.dot_items_list() -> List[Tuple[Tuple[str, ...], Any]]

Return list of tuples of the form (dot-key, value)

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_items_list(self) -> List[Tuple[Tuple[str, ...], Any]]:
    """Return list of tuples of the form (dot-key, value)"""
    return list(self.dot_items())

shellfish.sh.HrTime.dot_keys() -> Iterable[Tuple[str, ...]]

Yield the JsonObj's dot-notation keys

Returns:

Type	Description
Iterable[Tuple[str, ...]]	Iterable[str]: List of the dot-notation friendly keys

The Non-chain version (shown below) is very slightly slower than the itertools.chain version.

NON-CHAIN VERSION:

for k, value in self.items(): value = jsonify(value) if isinstance(value, JsonObj): yield from (f"{k}.{dk}" for dk in value.dot_keys()) else: yield k

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys(self) -> Iterable[Tuple[str, ...]]:
    """Yield the JsonObj's dot-notation keys

    Returns:
        Iterable[str]: List of the dot-notation friendly keys


    The Non-chain version (shown below) is very slightly slower than the
    `itertools.chain` version.

    NON-CHAIN VERSION:

    for k, value in self.items():
        value = jsonify(value)
        if isinstance(value, JsonObj):
            yield from (f"{k}.{dk}" for dk in value.dot_keys())
        else:
            yield k

    """
    return chain(
        *(
            (
                ((str(k),),)
                if not isinstance(v, JsonObj)
                else (*((str(k), *dk) for dk in jsonify(v).dot_keys()),)
            )
            for k, v in self.items()
        )
    )

shellfish.sh.HrTime.dot_keys_list(sort_keys: bool = False) -> List[Tuple[str, ...]]

Return a list of the JsonObj's dot-notation friendly keys

Parameters:

Name	Type	Description	Default
sort_keys	bool	Flag to have the dot-keys be returned sorted	False

Returns:

Type	Description
List[Tuple[str, ...]]	List[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_list(self, sort_keys: bool = False) -> List[Tuple[str, ...]]:
    """Return a list of the JsonObj's dot-notation friendly keys

    Args:
        sort_keys (bool): Flag to have the dot-keys be returned sorted

    Returns:
        List[str]: List of the dot-notation friendly keys

    """
    if sort_keys:
        return sorted(self.dot_keys_list())
    return list(self.dot_keys())

shellfish.sh.HrTime.dot_keys_set() -> Set[Tuple[str, ...]]

Return a set of the JsonObj's dot-notation friendly keys

Returns:

Type	Description
Set[Tuple[str, ...]]	Set[str]: List of the dot-notation friendly keys

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_keys_set(self) -> Set[Tuple[str, ...]]:
    """Return a set of the JsonObj's dot-notation friendly keys

    Returns:
        Set[str]: List of the dot-notation friendly keys

    """
    return set(self.dot_keys())

shellfish.sh.HrTime.dot_lookup(key: Union[str, Tuple[str, ...], List[str]]) -> Any

Look up JsonObj keys using dot notation as a string

Parameters:

Name	Type	Description	Default
key	str	dot-notation key to look up ('key1.key2.third_key')	required

Returns:

Type	Description
Any	The result of the dot-notation key look up

Raises:

Type	Description
KeyError	Raised if the dot-key is not in in the object
ValueError	Raised if key is not a str/Tuple[str, ...]/List[str]

Source code in libs/jsonbourne/jsonbourne/core.py

def dot_lookup(self, key: Union[str, Tuple[str, ...], List[str]]) -> Any:
    """Look up JsonObj keys using dot notation as a string

    Args:
        key (str): dot-notation key to look up ('key1.key2.third_key')

    Returns:
        The result of the dot-notation key look up

    Raises:
        KeyError: Raised if the dot-key is not in in the object
        ValueError: Raised if key is not a str/Tuple[str, ...]/List[str]

    """
    if not isinstance(key, (str, list, tuple)):
        raise ValueError(
            "".join(
                (
                    "dot_key arg must be string or sequence of strings; ",
                    "strings will be split on '.'",
                )
            )
        )
    parts = key.split(".") if isinstance(key, str) else list(key)
    root_val: Any = self._data[parts[0]]
    cur_val = root_val
    for ix, part in enumerate(parts[1:], start=1):
        try:
            cur_val = cur_val[part]
        except TypeError as e:
            reached = ".".join(parts[:ix])
            err_msg = f"Invalid DotKey: {key} -- Lookup reached: {reached} => {str(cur_val)}"
            if isinstance(key, str):
                err_msg += "".join(
                    (
                        f"\nNOTE!!! lookup performed with string ('{key}') ",
                        "PREFER lookup using List[str] or Tuple[str, ...]",
                    )
                )
            raise KeyError(err_msg) from e
    return cur_val

shellfish.sh.HrTime.eject() -> Dict[_KT, _VT]

Eject to python-builtin dictionary object

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/core.py

def eject(self) -> Dict[_KT, _VT]:
    """Eject to python-builtin dictionary object

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    try:
        return {k: unjsonify(v) for k, v in self._data.items()}
    except RecursionError as re:
        raise ValueError(
            "JSON.stringify recursion err; cycle/circular-refs detected"
        ) from re

shellfish.sh.HrTime.entries() -> ItemsView[_KT, _VT]

Alias for items

Source code in libs/jsonbourne/jsonbourne/core.py

def entries(self) -> ItemsView[_KT, _VT]:
    """Alias for items"""
    return self.items()

shellfish.sh.HrTime.filter_false(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recurse into sub JsonObjs and dictionaries	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_false())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False}
})
>>> print(d.filter_false(recursive=True))
JsonObj(**{
    'b': 2, 'c': {'d': 'herm'}
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_false(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is false-y

    Args:
        recursive (bool): Recurse into sub JsonObjs and dictionaries

    Returns:
        JsonObj that has been filtered

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_false())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False}
        })
        >>> print(d.filter_false(recursive=True))
        JsonObj(**{
            'b': 2, 'c': {'d': 'herm'}
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_false(recursive=True)
                    )
                    for k, v in self.items()
                    if v
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v})

shellfish.sh.HrTime.filter_none(recursive: bool = False) -> JsonObj[_VT]

Filter key-values where the value is None but not false-y

Parameters:

Name	Type	Description	Default
recursive	bool	Recursively filter out None values	False

Returns:

Type	Description
JsonObj[_VT]	JsonObj that has been filtered of None values

Examples:

>>> d = {
...     'falsey_dict': {},
...     'falsey_list': [],
...     'falsey_string': '',
...     'is_false': False,
...     'a': None,
...     'b': 2,
...     'c': {
...         'd': 'herm',
...         'e': None,
...         'falsey_dict': {},
...         'falsey_list': [],
...         'falsey_string': '',
...         'is_false': False,
...     },
...     }
...
>>> d = JsonObj(d)
>>> print(d)
JsonObj(**{
    'a': None,
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> print(d.filter_none())
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'e': None,
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})
>>> from pprint import pprint
>>> print(d.filter_none(recursive=True))
JsonObj(**{
    'b': 2,
    'c': {'d': 'herm',
          'falsey_dict': {},
          'falsey_list': [],
          'falsey_string': '',
          'is_false': False},
    'falsey_dict': {},
    'falsey_list': [],
    'falsey_string': '',
    'is_false': False
})

Source code in libs/jsonbourne/jsonbourne/core.py

def filter_none(self, recursive: bool = False) -> JsonObj[_VT]:
    """Filter key-values where the value is `None` but not false-y

    Args:
        recursive (bool): Recursively filter out None values

    Returns:
        JsonObj that has been filtered of None values

    Examples:
        >>> d = {
        ...     'falsey_dict': {},
        ...     'falsey_list': [],
        ...     'falsey_string': '',
        ...     'is_false': False,
        ...     'a': None,
        ...     'b': 2,
        ...     'c': {
        ...         'd': 'herm',
        ...         'e': None,
        ...         'falsey_dict': {},
        ...         'falsey_list': [],
        ...         'falsey_string': '',
        ...         'is_false': False,
        ...     },
        ...     }
        ...
        >>> d = JsonObj(d)
        >>> print(d)
        JsonObj(**{
            'a': None,
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> print(d.filter_none())
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'e': None,
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })
        >>> from pprint import pprint
        >>> print(d.filter_none(recursive=True))
        JsonObj(**{
            'b': 2,
            'c': {'d': 'herm',
                  'falsey_dict': {},
                  'falsey_list': [],
                  'falsey_string': '',
                  'is_false': False},
            'falsey_dict': {},
            'falsey_list': [],
            'falsey_string': '',
            'is_false': False
        })

    """
    if recursive:
        return JsonObj(
            cast(
                Dict[str, _VT],
                {
                    k: (
                        v
                        if not isinstance(v, (dict, JsonObj))
                        else JsonObj(v).filter_none(recursive=True)
                    )
                    for k, v in self.items()
                    if v is not None  # type: ignore[redundant-expr]
                },
            )
        )
    return JsonObj({k: v for k, v in self.items() if v is not None})  # type: ignore[redundant-expr]

shellfish.sh.HrTime.from_dict(data: Dict[_KT, _VT]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a dictionary of data

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_dict(cls: Type[JsonObj[_VT]], data: Dict[_KT, _VT]) -> JsonObj[_VT]:
    """Return a JsonObj object from a dictionary of data"""
    return cls(**data)

shellfish.sh.HrTime.from_dict_filtered(dictionary: Dict[str, Any]) -> JsonBaseModelT classmethod

Create class from dict filtering keys not in (sub)class' fields

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def from_dict_filtered(
    cls: Type[JsonBaseModelT], dictionary: Dict[str, Any]
) -> JsonBaseModelT:
    """Create class from dict filtering keys not in (sub)class' fields"""
    attr_names: Set[str] = set(cls._cls_field_names())
    return cls(**{k: v for k, v in dictionary.items() if k in attr_names})

shellfish.sh.HrTime.from_json(json_string: Union[bytes, str]) -> JsonObj[_VT] classmethod

Return a JsonObj object from a json string

Parameters:

Name	Type	Description	Default
json_string	str	JSON string to convert to a JsonObj	required

Returns:

Name	Type	Description
JsonObjT	JsonObj[_VT]	JsonObj object for the given JSON string

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def from_json(
    cls: Type[JsonObj[_VT]], json_string: Union[bytes, str]
) -> JsonObj[_VT]:
    """Return a JsonObj object from a json string

    Args:
        json_string (str): JSON string to convert to a JsonObj

    Returns:
        JsonObjT: JsonObj object for the given JSON string

    """
    return cls._from_json(json_string)

shellfish.sh.HrTime.from_seconds(seconds: float) -> 'HrTime' classmethod

Return HrTime object from seconds

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
'HrTime'	HrTime object

Source code in libs/shellfish/shellfish/sh.py

@classmethod
def from_seconds(cls, seconds: float) -> "HrTime":
    """Return HrTime object from seconds

    Args:
        seconds (float): number of seconds

    Returns:
        HrTime object

    """
    _sec, _ns = seconds2hrtime(seconds)
    return cls(sec=_sec, ns=_ns)

shellfish.sh.HrTime.has_required_fields() -> bool classmethod

Return True/False if the (sub)class has any fields that are required

Returns:

Name	Type	Description
bool	bool	True if any fields for a (sub)class are required

Source code in libs/jsonbourne/jsonbourne/pydantic.py

@classmethod
def has_required_fields(cls) -> bool:
    """Return True/False if the (sub)class has any fields that are required

    Returns:
        bool: True if any fields for a (sub)class are required

    """
    return any(val.is_required() for val in cls.model_fields.values())

shellfish.sh.HrTime.is_default() -> bool

Check if the object is equal to the default value for its fields

Returns:

Type	Description
bool	True if object is equal to the default value for all fields; False otherwise

Examples:

>>> class Thing(JsonBaseModel):
...    a: int = 1
...    b: str = 'b'
...
>>> t = Thing()
>>> t.is_default()
True
>>> t = Thing(a=2)
>>> t.is_default()
False

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def is_default(self) -> bool:
    """Check if the object is equal to the default value for its fields

    Returns:
        True if object is equal to the default value for all fields; False otherwise

    Examples:
        >>> class Thing(JsonBaseModel):
        ...    a: int = 1
        ...    b: str = 'b'
        ...
        >>> t = Thing()
        >>> t.is_default()
        True
        >>> t = Thing(a=2)
        >>> t.is_default()
        False

    """
    if self.has_required_fields():
        return False
    return all(
        mfield.default == self[fname] for fname, mfield in self.model_fields.items()
    )

shellfish.sh.HrTime.items() -> ItemsView[_KT, _VT]

Return an items view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def items(self) -> ItemsView[_KT, _VT]:
    """Return an items view of the JsonObj object"""
    return self._data.items()

shellfish.sh.HrTime.json(*args: Any, **kwargs: Any) -> str

Alias for model_dumps

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def json(self, *args: Any, **kwargs: Any) -> str:
    """Alias for `model_dumps`"""
    return self.model_dump_json(*args, **kwargs)

shellfish.sh.HrTime.keys() -> KeysView[_KT]

Return the keys view of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def keys(self) -> KeysView[_KT]:
    """Return the keys view of the JsonObj object"""
    return self._data.keys()

shellfish.sh.HrTime.recurse() -> None

Recursively convert all sub dictionaries to JsonObj objects

Source code in libs/jsonbourne/jsonbourne/core.py

def recurse(self) -> None:
    """Recursively convert all sub dictionaries to JsonObj objects"""
    self._data.update({k: jsonify(v) for k, v in self._data.items()})

shellfish.sh.HrTime.stringify(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def stringify(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.HrTime.to_dict() -> Dict[str, Any]

Eject and return object as plain jane dictionary

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict(self) -> Dict[str, Any]:
    """Eject and return object as plain jane dictionary"""
    return self.eject()

shellfish.sh.HrTime.to_dict_filter_defaults() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm')
>>> t.to_dict_filter_defaults()
{}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{})
>>> t = Thing(a=123)
>>> t
Thing(a=123, b='herm')
>>> t.to_dict_filter_defaults()
{'a': 123}
>>> t.to_json_obj_filter_defaults()
JsonObj(**{'a': 123})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_defaults(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm')
        >>> t.to_dict_filter_defaults()
        {}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{})
        >>> t = Thing(a=123)
        >>> t
        Thing(a=123, b='herm')
        >>> t.to_dict_filter_defaults()
        {'a': 123}
        >>> t.to_json_obj_filter_defaults()
        JsonObj(**{'a': 123})

    """
    defaults = self.defaults_dict()
    return {
        k: v
        for k, v in self.model_dump().items()
        if k not in defaults or v != defaults[k]
    }

shellfish.sh.HrTime.to_dict_filter_none() -> Dict[str, Any]

Eject object and filter key-values equal to (sub)class' default

Examples:

>>> from typing import Optional
>>> class Thing(JsonBaseModel):
...     a: int = 1
...     b: str = "herm"
...     c: Optional[str] = None
...
>>> t = Thing()
>>> t
Thing(a=1, b='herm', c=None)
>>> t.to_dict_filter_none()
{'a': 1, 'b': 'herm'}
>>> t.to_json_obj_filter_none()
JsonObj(**{'a': 1, 'b': 'herm'})

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_dict_filter_none(self) -> Dict[str, Any]:
    """Eject object and filter key-values equal to (sub)class' default

    Examples:
        >>> from typing import Optional
        >>> class Thing(JsonBaseModel):
        ...     a: int = 1
        ...     b: str = "herm"
        ...     c: Optional[str] = None
        ...
        >>> t = Thing()
        >>> t
        Thing(a=1, b='herm', c=None)
        >>> t.to_dict_filter_none()
        {'a': 1, 'b': 'herm'}
        >>> t.to_json_obj_filter_none()
        JsonObj(**{'a': 1, 'b': 'herm'})

    """
    return {k: v for k, v in self.model_dump().items() if v is not None}

shellfish.sh.HrTime.to_json(fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, **kwargs: Any) -> str

Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '

' to JSON string if True default: default function hook for JSON serialization **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

def to_json(
    self,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    **kwargs: Any,
) -> str:
    """Return JSON string of the JsonObj object (and children)

    Args:
        fmt (bool): If True, return a JSON string with newlines and indentation
        pretty (bool): If True, return a JSON string with newlines and indentation
        sort_keys (bool): Sort dictionary keys if True
        append_newline (bool): Append a newline '\n' to JSON string if True
        default: default function hook for JSON serialization
        **kwargs (Any): additional kwargs to be passed down to jsonlib.dumps

    Returns:
        str: JSON string of the JsonObj object

    """
    return self._to_json(
        fmt=fmt,
        pretty=pretty,
        sort_keys=sort_keys,
        append_newline=append_newline,
        default=default,
        **kwargs,
    )

shellfish.sh.HrTime.to_json_dict() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_dict(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return self.to_json_obj()

shellfish.sh.HrTime.to_json_obj() -> JsonObj[Any]

Eject object and sub-objects to jsonbourne.JsonObj

Examples:

>>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> d
JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
>>> plain_ol_dict = d.eject()
>>> plain_ol_dict
{'uno': 'ONE', 'tres': 3, 'dos': 2}
>>> type(plain_ol_dict)
<class 'dict'>

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj(self) -> JsonObj[Any]:
    """Eject object and sub-objects to `jsonbourne.JsonObj`

    Examples:
        >>> d = JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> d
        JsonObj(**{'uno': 'ONE', 'tres': 3, 'dos': 2})
        >>> plain_ol_dict = d.eject()
        >>> plain_ol_dict
        {'uno': 'ONE', 'tres': 3, 'dos': 2}
        >>> type(plain_ol_dict)
        <class 'dict'>

    """
    return JsonObj(
        {
            k: v if not isinstance(v, JsonBaseModel) else v.to_json_dict()
            for k, v in self.__dict__.items()
        }
    )

shellfish.sh.HrTime.to_json_obj_filter_defaults() -> JsonObj[Any]

Eject to JsonObj and filter key-values equal to (sub)class' default

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_defaults(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values equal to (sub)class' default"""
    return JsonObj(self.to_dict_filter_defaults())

shellfish.sh.HrTime.to_json_obj_filter_none() -> JsonObj[Any]

Eject to JsonObj and filter key-values where the value is None

Source code in libs/jsonbourne/jsonbourne/pydantic.py

def to_json_obj_filter_none(self) -> JsonObj[Any]:
    """Eject to JsonObj and filter key-values where the value is None"""
    return JsonObj(self.to_dict_filter_none())

shellfish.sh.HrTime.validate_type(val: Any) -> JsonObj[_VT] classmethod

Validate and convert a value to a JsonObj object

Source code in libs/jsonbourne/jsonbourne/core.py

@classmethod
def validate_type(cls: Type[JsonObj[_VT]], val: Any) -> JsonObj[_VT]:
    """Validate and convert a value to a JsonObj object"""
    return cls(val)

shellfish.sh.HrTimeDict

Bases: TypedDict

High resolution time

shellfish.sh.HrTimeObj

Bases: TypedDict

Todo

deprecate this in favor of HrTimeDict

shellfish.sh.LIN

Bases: LIN

Linux (and Mac) shell commands/methods container

Functions

shellfish.sh.LIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	str	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (str): Allow link to exist

    """
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.sh.LIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	Allow link to exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): Allow link to exist

    """
    for link, target in link_target_tuples:
        LIN.link_dir(link, target, exist_ok=exist_ok)

shellfish.sh.LIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	Allow links to already exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): Allow links to already exist

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath)
    except FileExistsError as fee:
        if not exist_ok:
            raise fee

shellfish.sh.LIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
exist_ok	bool	Allow links to already exist	False
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        exist_ok (bool): Allow links to already exist
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.

    """
    for link, target in link_target_tuples:
        LIN.link_file(link, target, exist_ok=exist_ok)

shellfish.sh.LIN.rsync(src: str, dest: str, delete: bool = False, mkdirs: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> Done staticmethod

Run an rsync subprocess

Parameters:

Name	Type	Description	Default
mkdirs	bool	Make destination directories if they do not already exist; defaults to False.	False
src	str	Source directory path	required
dest	str	Destination directory path	required
delete	bool	Delete files/directories in destination if they do exist in source	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Name	Type	Description
Done	Done	Done object containing the info for the rsync run

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync(
    src: str,
    dest: str,
    delete: bool = False,
    mkdirs: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> Done:
    """Run an `rsync` subprocess

    Args:
        mkdirs (bool): Make destination directories if they do not already
            exist; defaults to False.
        src (str): Source directory path
        dest (str): Destination directory path
        delete (bool): Delete files/directories in destination if they do
            exist in source
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        Done: Done object containing the info for the rsync run

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection

    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    rsync_args = LIN.rsync_args(
        src, dest, delete=delete, exclude=exclude, include=include, dry_run=dry_run
    )

    done = do(args=list(filter(None, rsync_args)))
    return done

shellfish.sh.LIN.rsync_args(src: str, dest: str, delete: bool = False, dry_run: bool = False, exclude: Optional[IterableStr] = None, include: Optional[IterableStr] = None) -> List[str] staticmethod

Return args for rsync command on linux/mac

Parameters:

Name	Type	Description	Default
src	str	path to remote (raid) tdir	required
dest	str	path to local tdir	required
delete	bool	Flag that will do a 'hard sync'	False
exclude	Optional[IterableStr]	Strings/patterns to exclude	None
include	Optional[IterableStr]	Strings/patterns to include	None
dry_run	bool	Perform operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from rsync

Rsync return codes::

- 0 == Success
- 1 == Syntax or usage error
- 2 == Protocol incompatibility
- 3 == Errors selecting input/output files, dirs
- 4 == Requested  action not supported: an attempt was made to
  manipulate 64-bit files on a platform that cannot support them;
  or an option was specified that is supported by the client and
  not the server.
- 5 == Error starting client-server protocol
- 6 == Daemon unable to append to log-file
- 10 == Error in socket I/O
- 11 == Error in file I/O
- 12 == Error in rsync protocol data stream
- 13 == Errors with program diagnostics
- 14 == Error in IPC code
- 20 == Received SIGUSR1 or SIGINT
- 21 == Some error returned by waitpid()
- 22 == Error allocating core memory buffers
- 23 == Partial transfer due to error
- 24 == Partial transfer due to vanished source files
- 25 == The --max-delete limit stopped deletions
- 30 == Timeout in data send2viewserver/receive
- 35 == Timeout waiting for daemon connection

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def rsync_args(
    src: str,
    dest: str,
    delete: bool = False,
    dry_run: bool = False,
    exclude: Optional[IterableStr] = None,
    include: Optional[IterableStr] = None,
) -> List[str]:
    """Return args for rsync command on linux/mac

    Args:
        src: path to remote (raid) tdir
        dest: path to local tdir
        delete: Flag that will do a 'hard sync'
        exclude: Strings/patterns to exclude
        include: Strings/patterns to include
        dry_run (bool): Perform operation as a dry run

    Returns:
        subprocess return code from rsync

    Rsync return codes::

        - 0 == Success
        - 1 == Syntax or usage error
        - 2 == Protocol incompatibility
        - 3 == Errors selecting input/output files, dirs
        - 4 == Requested  action not supported: an attempt was made to
          manipulate 64-bit files on a platform that cannot support them;
          or an option was specified that is supported by the client and
          not the server.
        - 5 == Error starting client-server protocol
        - 6 == Daemon unable to append to log-file
        - 10 == Error in socket I/O
        - 11 == Error in file I/O
        - 12 == Error in rsync protocol data stream
        - 13 == Errors with program diagnostics
        - 14 == Error in IPC code
        - 20 == Received SIGUSR1 or SIGINT
        - 21 == Some error returned by waitpid()
        - 22 == Error allocating core memory buffers
        - 23 == Partial transfer due to error
        - 24 == Partial transfer due to vanished source files
        - 25 == The --max-delete limit stopped deletions
        - 30 == Timeout in data send2viewserver/receive
        - 35 == Timeout waiting for daemon connection


    """
    if exclude is None:
        exclude = []
    if include is None:
        include = []

    if not dest.endswith("/"):
        dest = f"{dest}/"
    if not src.endswith("/"):
        src = f"{src}/"
    _args: List[Union[str, None]] = [
        "rsync",
        "-a",
        "-O",
        "--no-o",
        "--no-g",
        "--no-p",
        "--delete" if delete else None,
        *(f'--exclude="{pattern}"' for pattern in exclude),
        *(f'--include="{pattern}"' for pattern in include),
        *(("--dry-run", "-i") if dry_run else (None,)),
        src,
        dest,
    ]
    return list(filter(None, _args))

shellfish.sh.LIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.sh.LIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_dir(link)

shellfish.sh.LIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    unlink(str(link))

shellfish.sh.LIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    for link in links:
        LIN.unlink_file(link)

shellfish.sh.Stdio

Bases: IntEnum

Standard-io enum object

shellfish.sh.WIN

Bases: WIN

Windows shell commands/methods container

Functions

shellfish.sh.WIN.link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a directory symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, do not raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dir(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a directory symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, do not raise an exception if the link exists

    """
    makedirs(path.split(linkpath)[0], exist_ok=True)
    try:
        symlink(targetpath, linkpath, target_is_directory=True)
    except OSError:
        batman.MKLINK(
            linkpath,
            targetpath,
            D=True,
        )

shellfish.sh.WIN.link_dirs(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple directory symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, do not raise an exception if the link(s) exist	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_dirs(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple directory symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, do not raise an exception if the link(s) exist

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_dir(link, target, exist_ok=exist_ok)
    except OSError:
        args = [
            batman.MKLINK_ARGS(link, target, D=True)
            for link, target in link_target_tuples
            if WIN._check_link_target_dirs(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in args])

shellfish.sh.WIN.link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None staticmethod

Make a file symlink

Parameters:

Name	Type	Description	Default
linkpath	str	Path to the link to be made	required
targetpath	str	Path to the target of the link to be made	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_file(linkpath: str, targetpath: str, *, exist_ok: bool = False) -> None:
    """Make a file symlink

    Args:
        linkpath (str): Path to the link to be made
        targetpath (str): Path to the target of the link to be made
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        symlink(targetpath, linkpath)
    except OSError:
        makedirs(path.split(linkpath)[0], exist_ok=True)
        batman.MKLINK(
            linkpath,
            targetpath,
        )

shellfish.sh.WIN.link_files(link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False) -> None staticmethod

Make multiple file symlinks

Parameters:

Name	Type	Description	Default
link_target_tuples	List[Tuple[str, str]]	Iterable of tuples of the form: (link, target) or a dictionary mapping with key => value pairs of the form link => target.	required
exist_ok	bool	If True, don't raise an exception if the link exists	False

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def link_files(
    link_target_tuples: List[Tuple[str, str]], *, exist_ok: bool = False
) -> None:
    """Make multiple file symlinks

    Args:
        link_target_tuples: Iterable of tuples of the form: (link, target)
            or a dictionary mapping with key => value pairs of the form
            link => target.
        exist_ok (bool): If True, don't raise an exception if the link exists

    """
    try:
        for link, target in link_target_tuples:
            WIN.link_file(link, target, exist_ok=exist_ok)
    except OSError:
        link_target_tuples = list(link_target_tuples)
        _args = [
            batman.MKLINK_ARGS(link, target, D=False)
            for link, target in link_target_tuples
            if WIN._check_link_target_files(link, target)
        ]
        batman.run_cmds_as_bat_file(commands=[" ".join(el) for el in _args])

shellfish.sh.WIN.robocopy(src: str, dest: str, *, mkdirs: bool = True, delete: bool = False, exclude_files: Optional[Iterable[str]] = None, exclude_dirs: Optional[Iterable[str]] = None, dry_run: bool = False) -> Done staticmethod

Robocopy wrapper function (crude in that it opens a subprocess)

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[Iterable[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[Iterable[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False
mkdirs	bool	Flag to make destinaation directories if they do not already exist	True

Returns:

Type	Description
Done	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy(
    src: str,
    dest: str,
    *,
    mkdirs: bool = True,
    delete: bool = False,
    exclude_files: Optional[Iterable[str]] = None,
    exclude_dirs: Optional[Iterable[str]] = None,
    dry_run: bool = False,
) -> Done:  # pragma: nocov
    """Robocopy wrapper function (crude in that it opens a subprocess)

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run
        mkdirs (bool): Flag to make destinaation directories if they do
            not already exist

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    _exclude_files = [] if exclude_files is None else list(exclude_files)
    _exclude_dirs = [] if exclude_dirs is None else list(exclude_dirs)
    if mkdirs and not dry_run:
        makedirs(dest, exist_ok=True)
    _args = WIN.robocopy_args(
        src=src,
        dest=dest,
        delete=delete,
        exclude_files=_exclude_files,
        exclude_dirs=_exclude_dirs,
        dry_run=dry_run,
    )
    return do(args=_args)

shellfish.sh.WIN.robocopy_args(src: str, dest: str, *, delete: bool = False, exclude_files: Optional[List[str]] = None, exclude_dirs: Optional[List[str]] = None, dry_run: bool = False) -> List[str] staticmethod

Return list of robocopy command args

Parameters:

Name	Type	Description	Default
src	str	path to source directory	required
dest	str	path to destination directory	required
delete	bool	Delete files in the destination directory if they do not exist in the source directory	False
exclude_files	Optional[List[str]]	Strings/patterns with which to exclude files	None
exclude_dirs	Optional[List[str]]	Strings/patterns with which to exclude directories	None
dry_run	bool	Do the operation as a dry run	False

Returns:

Type	Description
List[str]	subprocess return code from robocopy

Robocopy return codes::

0. No files were copied. No failure was encountered. No files were
   mismatched. The files already exist in the destination
   directory; therefore, the copy operation was skipped.
1. All files were copied successfully.
2. There are some additional files in the destination directory
   that are not present in the source directory. No files were
   copied.
3. Some files were copied. Additional files were present. No
   failure was encountered.
5. Some files were copied. Some files were mismatched. No failure
   was encountered.
6. Additional files and mismatched files exist. No files were
   copied and no failures were encountered. This means that the
   files already exist in the destination directory.
7. Files were copied, a file mismatch was present, and additional
   files were present.
8. Several files did not copy.

Source code in libs/shellfish/shellfish/sh.py

@staticmethod
def robocopy_args(
    src: str,
    dest: str,
    *,
    delete: bool = False,
    exclude_files: Optional[List[str]] = None,
    exclude_dirs: Optional[List[str]] = None,
    dry_run: bool = False,
) -> List[str]:
    """Return list of robocopy command args

    Args:
        src (str): path to source directory
        dest (str): path to destination directory
        delete (bool): Delete files in the destination directory if they do
            not exist in the source directory
        exclude_files: Strings/patterns with which to exclude files
        exclude_dirs: Strings/patterns with which to exclude directories
        dry_run (bool): Do the operation as a dry run

    Returns:
        subprocess return code from robocopy

    Robocopy return codes::

        0. No files were copied. No failure was encountered. No files were
           mismatched. The files already exist in the destination
           directory; therefore, the copy operation was skipped.
        1. All files were copied successfully.
        2. There are some additional files in the destination directory
           that are not present in the source directory. No files were
           copied.
        3. Some files were copied. Additional files were present. No
           failure was encountered.
        5. Some files were copied. Some files were mismatched. No failure
           was encountered.
        6. Additional files and mismatched files exist. No files were
           copied and no failures were encountered. This means that the
           files already exist in the destination directory.
        7. Files were copied, a file mismatch was present, and additional
           files were present.
        8. Several files did not copy.

    """
    if exclude_files is None:
        exclude_files = []
    if exclude_dirs is None:
        exclude_dirs = []
    _args = [
        "robocopy",
        src,
        dest,
        "/MIR" if delete else "/E",
        "/mt",
        "/W:1",
        "/R:1",
    ]
    if exclude_dirs:
        _args.extend(["/XD", *exclude_dirs])
    if exclude_files:
        _args.extend(["/XF", *exclude_files])
    if dry_run:
        _args.append("/L")
    return list(filter(None, _args))

shellfish.sh.WIN.unlink_dir(link: str) -> None staticmethod

Unlink a directory symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dir(link: str) -> None:
    """Unlink a directory symlink given a path to the symlink

    Args:
        link: path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.RD(link)

shellfish.sh.WIN.unlink_dirs(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_dirs(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_dir(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            commands=[batman.RD_ARGS(link) for link in links]
        )

shellfish.sh.WIN.unlink_file(link: str) -> None staticmethod

Unlink a file symlink given a path to the symlink

Parameters:

Name	Type	Description	Default
link	str	path to the symlink	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_file(link: str) -> None:
    """Unlink a file symlink given a path to the symlink

    Args:
        link (str): path to the symlink

    """
    try:
        unlink(link)
    except OSError:
        batman.DEL(link)

shellfish.sh.WIN.unlink_files(links: IterableStr) -> None staticmethod

Unlink directory symlinks given the paths the links

Parameters:

Name	Type	Description	Default
links	IterableStr	Iterable of paths to links	required

Source code in libs/shellfish/shellfish/osfs.py

@staticmethod
def unlink_files(links: IterableStr) -> None:
    """Unlink directory symlinks given the paths the links

    Args:
        links: Iterable of paths to links

    """
    try:
        for link in links:
            WIN.unlink_file(link)
    except OSError:
        batman.run_cmds_as_bat_file(
            [batman.DEL_ARGS(link) for link in links],
        )

Functions

shellfish.sh.basename(fspath: FsPath) -> str

Return the basename of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def basename(fspath: FsPath) -> str:
    """Return the basename of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.basename(str(fspath))

shellfish.sh.cd(dirpath: FsPath) -> None

Change directory to given dirpath; alias for os.chdir

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory fspath	required

Source code in libs/shellfish/shellfish/sh.py

def cd(dirpath: FsPath) -> None:
    """Change directory to given dirpath; alias for `os.chdir`

    Args:
        dirpath: Directory fspath

    """
    chdir(str(dirpath))

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

Change the access permissions of a file

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file to chmod	required
mode	int	Permissions mode as an int	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def chmod(fspath: FsPath, mode: int) -> None:
    """Change the access permissions of a file

    Args:
        fspath (FsPath): Path to file to chmod
        mode (int): Permissions mode as an int

    """
    return _chmod(path=str(fspath), mode=mode)

shellfish.sh.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:

Name	Type	Description	Default
src	str	Source fspath	required
dest	str	Destination fspath	required
dryrun	bool	Do not copy file if True just return the src and dest	False
mkdirp	bool	Create parent directories if they do not exist	False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source fspath
        dest (str): Destination fspath
        dryrun (bool): Do not copy file if True just return the src and dest
        mkdirp (bool): Create parent directories if they do not exist

    """
    _dest = Path(dest)
    if not dryrun and mkdirp:
        _dest.parent.mkdir(parents=mkdirp, exist_ok=True)
    elif not _dest.parent.exists() or not _dest.parent.is_dir():
        raise FileNotFoundError(f"Destination directory {_dest.parent} does not exist")
    if not dryrun:
        wbytes_gen(dest, lbytes_gen(src, blocksize=2**18))
        _copystat(src, dest, follow_symlinks=True)
    return (str(src), str(dest))

shellfish.sh.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:

Name	Type	Description	Default
src	str	Source directory/file to copy	required
dest	FsPath	Destination directory/file to copy	required
force	bool	Force the copy (like -f flag for cp in shell)	True
recursive	bool	Recursive copy (like -r flag for cp in shell)	False
r	bool	alias for recursive	False
f	bool	alias for force	True

Raises:

Type	Description
ValueError	If src is a directory and recursive and r are both False

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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

    Args:
        src (str): Source directory/file to copy
        dest: Destination directory/file to copy
        force: Force the copy (like -f flag for cp in shell)
        recursive: Recursive copy (like -r flag for cp in shell)
        r: alias for recursive
        f: alias for force

    Raises:
        ValueError: If src is a directory and recursive and r are both `False`

    """
    _recursive = recursive or r
    _force = force or f
    for _src in iglob(_fspath(src), recursive=True):
        _dest = dest
        if (path.exists(dest) and not _force) or _src == dest:
            return
        if path.isdir(_src) and not _recursive:
            raise ValueError("Source ({}) is directory; use r=True")
        if path.isfile(_src) and path.isdir(dest):
            _dest = path.join(dest, path.basename(_src))
        if path.isfile(_src) or path.islink(src):
            copy_file(_src, _dest)
        if path.isdir(_src):
            if not path.exists(dest):
                _makedirs(dest)
            copytree(src, dest, dirs_exist_ok=True)

shellfish.sh.decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str

Return Stdio bytes from stdout/stderr as a string

Args:
    stdio_bytes (bytes): STDOUT/STDERR bytes
    lf (bool): Replace `

line endings with `

Returns:
    str: decoded stdio bytes

Source code in libs/shellfish/shellfish/sh.py

def decode_stdio_bytes(stdio_bytes: Union[str, bytes], lf: bool = True) -> str:
    """Return Stdio bytes from stdout/stderr as a string

    Args:
        stdio_bytes (bytes): STDOUT/STDERR bytes
        lf (bool): Replace `\r\n` line endings with `\n`

    Returns:
        str: decoded stdio bytes

    """
    if isinstance(stdio_bytes, str):
        return stdio_bytes
    if lf:
        return decode_stdio_bytes(stdio_bytes, lf=False).replace("\r\n", "\n")
    try:
        return str(stdio_bytes.decode())
    except AttributeError:
        return ""
    except Exception:
        pass

    try:
        return str(stdio_bytes.decode("utf-8"))
    except UnicodeDecodeError:
        pass
    return str(stdio_bytes.decode("latin-1"))

shellfish.sh.dir_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dir_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isdir"""
    return isdir(fspath)

shellfish.sh.dir_exists_async(fspath: FsPath) -> bool async

Return True if the directory exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def dir_exists_async(fspath: FsPath) -> bool:
    """Return True if the directory exists; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.sh.dirname(fspath: FsPath) -> str

Return dirname/parent-dir of given path; alias of os.path.dirname

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path	required

Returns:

Name	Type	Description
str	str	basename of path

Source code in libs/shellfish/shellfish/sh.py

def dirname(fspath: FsPath) -> str:
    """Return dirname/parent-dir of given path; alias of os.path.dirname

    Args:
        fspath: File-system path

    Returns:
        str: basename of path

    """
    return path.dirname(_fspath(fspath))

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

Yield all dirpaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirpath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all dirpaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in dirs_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield directory-paths beneath a dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        dirpath if abspath else str(dirpath).replace(dirpath, "").strip(sep)
        for dirpath in (
            pwd
            for pwd, dirs, files in walk(
                str(dirpath),
                onerror=onerror,
                topdown=topdown,
                followlinks=followlinks,
            )
        )
    )

shellfish.sh.do(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[FsPath] = None, shell: bool = False, check: bool = False, tee: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
tee	bool	Flag to tee the subprocess stdout and stderr to sys.stdout/stderr	False
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check against	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	if args and *popenargs are both given

Source code in libs/shellfish/shellfish/sh.py

def do(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    shell: bool = False,
    check: bool = False,
    tee: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        tee (bool): Flag to tee the subprocess stdout and stderr to sys.stdout/stderr
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check against
        dryrun: Don't run the subprocess

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: if args and *popenargs are both given

    """
    if args and popenargs:
        raise ValueError("Cannot give *popenargs and `args` kwargs")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win():
        args = validate_popen_args_windows(args, env)
    _input = validate_stdin(input)
    return _do(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        check=check,
        verbose=verbose,
        input=_input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
        tee=tee,
    )

shellfish.sh.do_async(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
extenv	bool	Extend environment with the current environment (Default value = True)	True
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Raises:

Type	Description
ValueError	If both *popenargs and args are given

Source code in libs/shellfish/shellfish/sh.py

async def do_async(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        extenv: Extend environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    Raises:
        ValueError: If both *popenargs and args are given

    """
    if args and popenargs:
        raise ValueError("Cannot give *args and args-keyword-argument")
    args = validate_popen_args([*args]) if args else validate_popen_args(popenargs)
    if is_win() and sys.version_info < (3, 8):
        done = await do_asyncify(
            args=args,
            env=env,
            extenv=extenv,
            cwd=cwd,
            shell=shell,
            verbose=verbose,
            input=input,
            check=check,
            timeout=timeout,
            ok_code=ok_code,
            dryrun=dryrun,
        )
        done.async_proc = True
        return done
    if not shell and is_win():
        args = validate_popen_args_windows(args, env)
    return await _do_async(
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.do_asyncify(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess asynchronously using asyncified version of do

Source code in libs/shellfish/shellfish/sh.py

async def do_asyncify(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess asynchronously using asyncified version of do"""
    done = await _do_asyncify(
        *popenargs,
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )
    done.async_proc = True
    return done

shellfish.sh.doa(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, extenv: bool = True, cwd: Optional[str] = None, shell: bool = False, verbose: bool = False, input: STDIN = None, check: bool = False, timeout: Optional[float] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done async

Run a subprocess and await its completion

Alias for sh.do_async

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
check	bool	Check the result returncode	False
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
cwd	Optional[str]	Current working directory (Default value = None)	None
shell	bool	Run in shell or sub-shell	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) that are considered OK (Default value = 0)	0
dryrun	bool	Flag to not run the subprocess but return a Done object	False
extenv	bool	Extend environment with the current environment (Default value = True)	True

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

async def doa(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    extenv: bool = True,
    cwd: Optional[str] = None,
    shell: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    check: bool = False,
    timeout: Optional[float] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess and await its completion

    Alias for sh.do_async

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        check (bool): Check the result returncode
        env: Environment variables as a dictionary (Default value = None)
        cwd: Current working directory (Default value = None)
        shell: Run in shell or sub-shell
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) that are considered OK (Default value = 0)
        dryrun (bool): Flag to not run the subprocess but return a Done object
        extenv: Extend environment with the current environment (Default value = True)

    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return await do_async(
        *popenargs,
        args=args,
        env=env,
        extenv=extenv,
        cwd=cwd,
        shell=shell,
        verbose=verbose,
        input=input,
        check=check,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.echo(*objects: Any, sep: str = ' ', end: str = '\n', file: Optional[IO[str]] = None, flush: bool = False) -> None

Print/echo function

Args:
    *objects: Item(s) to print/echo
    sep: Separator to print with
    end: End of print suffix; defaults to `

` file: File like object to write to if not stdout flush: Flush the file after writing

Examples:
    >>> echo("shellfish")
    shellfish

Source code in libs/shellfish/shellfish/echo.py

def echo(
    *objects: Any,
    sep: str = " ",
    end: str = "\n",
    file: Optional[IO[str]] = None,
    flush: bool = False,
) -> None:
    """Print/echo function

    Args:
        *objects: Item(s) to print/echo
        sep: Separator to print with
        end: End of print suffix; defaults to `\n`
        file: File like object to write to if not stdout
        flush: Flush the file after writing

    Examples:
        >>> echo("shellfish")
        shellfish

    """
    print(*objects, sep=sep, end=end, file=file, flush=flush)

shellfish.sh.exists(fspath: FsPath) -> bool

Return True if the given path exists; False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise"""
    return path.exists(_fspath(fspath))

shellfish.sh.export(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Raises:

Type	Description
ValueError	if unable to parse key/val

Source code in libs/shellfish/shellfish/sh.py

def export(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Raises:
        ValueError: if unable to parse key/val

    """
    if val:
        environ[key] = val
        return (key, val)
    if "=" in key:
        _key = key.split("=")[0]
        return export(_key, key[len(_key) + 1 :])
    raise ValueError(
        f"Unable to parse env variable - key: {str(key)}, value: {str(val)}"
    )

shellfish.sh.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'

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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'

    """
    if period:
        return "".join(Path(fspath).suffixes)
    return "".join(Path(fspath).suffixes).lstrip(".")

shellfish.sh.file_exists(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_exists(fspath: FsPath) -> bool:
    """Return True if the given path exists; False otherwise; alias for isfile"""
    return isfile(fspath)

shellfish.sh.file_exists_async(fspath: FsPath) -> bool async

Return True if the file exists; False otherwise

Source code in libs/shellfish/shellfish/fs/_async.py

async def file_exists_async(fspath: FsPath) -> bool:
    """Return True if the file exists; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

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

Yield lines from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	File to yield lines from	required
keepends	bool	Flag to keep the ends of the file lines	True

Yields:

Type	Description
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 wstring
>>> wstring(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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def file_lines_gen(filepath: FsPath, keepends: bool = True) -> Iterable[str]:
    r"""Yield lines from a given fspath

    Args:
        filepath: File to yield lines from
        keepends: Flag to keep the ends of the file lines

    Yields:
        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 wstring
        >>> wstring(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)


    """
    with open(filepath) as f:
        if keepends:
            yield from (line for line in f)
        else:
            yield from (line.rstrip("\n").rstrip("\r\n") for line in f)

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

Compare 2 files for equality given their filepaths

Parameters:

Name	Type	Description	Default
left	FsPath	Filepath 1	required
right	FsPath	Filepath 2	required
shallow	bool	Check only size and modification time if True	True
blocksize	int	Chunk size to read files	65536

Returns:

Type	Description
bool	True if files are equal, False otherwise

Source code in libs/shellfish/shellfish/fs/__init__.py

def filecmp(
    left: FsPath,
    right: FsPath,
    *,
    shallow: bool = True,
    blocksize: int = 65536,
) -> bool:
    """Compare 2 files for equality given their filepaths

    Args:
        left (FsPath): Filepath 1
        right (FsPath): Filepath 2
        shallow (bool): Check only size and modification time if True
        blocksize (int): Chunk size to read files

    Returns:
        True if files are equal, False otherwise

    """
    left_stat = stat(left)
    right_stat = stat(right)
    if (
        shallow
        and left_stat.st_size == right_stat.st_size
        and left_stat.st_mtime == right_stat.st_mtime
    ):
        return True
    if left_stat.st_size != right_stat.st_size:
        return False
    return not any(
        left_chunk != right_chunk
        for left_chunk, right_chunk in zip(
            rbytes_gen(left, blocksize=blocksize),
            rbytes_gen(right, blocksize=blocksize),
        )
    )

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in files_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.sh.filepath_mtimedelta_sec(filepath: FsPath) -> float

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def filepath_mtimedelta_sec(filepath: FsPath) -> float:
    """Return the seconds since the file(path) was last modified"""
    return time() - path.getmtime(_fspath(filepath))

shellfish.sh.files_dirs_gen(dirpath: FsPath = '.', *, abspath: bool = True, topdown: bool = True, onerror: Optional[Callable[[OSError], Any]] = 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:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath is a directory	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_dirs_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Tuple[Iterator[str], Iterator[str]]:
    r"""Return a files_gen() and a dirs_gen() in one swell-foop

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath is a directory

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

    """
    return files_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    ), dirs_gen(
        dirpath,
        abspath=abspath,
        followlinks=followlinks,
        onerror=onerror,
        topdown=topdown,
        check=check,
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check that dir exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def files_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield file-paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check that dir exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        filepath if abspath else str(filepath).replace(dirpath, "").strip(sep)
        for filepath in (
            path.join(pwd, filename)
            for pwd, dirs, files in walk(
                str(dirpath),
                topdown=topdown,
                onerror=onerror,
                followlinks=followlinks,
            )
            for filename in files
        )
    )

shellfish.sh.filesize(fspath: FsPath) -> int

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath as a string or pathlib.Path object	required

Returns:

Name	Type	Description
int	int	size of the fspath in bytes

Source code in libs/shellfish/shellfish/fs/__init__.py

def filesize(fspath: FsPath) -> int:
    """Return the size of the given file(path) in bytes

    Args:
        fspath (FsPath): Filepath as a string or pathlib.Path object

    Returns:
        int: size of the fspath in bytes

    """
    return stat(fspath).st_size

shellfish.sh.filesize_async(fspath: FsPath) -> int async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def 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

    """
    _stat_res = await aios.stat(str(fspath))
    return _stat_res.st_size

shellfish.sh.flatten_args(*args: Union[Any, List[Any]]) -> List[str]

Flatten possibly nested iterables of sequences to a list of strings

Examples:

>>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
['cmd', 'uno', 'dos', 'tres']
>>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
['cmd', 'uno', 'dos', 'tres', '4444', 'five']

Source code in libs/shellfish/shellfish/sh.py

def flatten_args(*args: Union[Any, List[Any]]) -> List[str]:
    """Flatten possibly nested iterables of sequences to a list of strings

    Examples:
        >>> list(flatten_args("cmd", ["uno", "dos", "tres"]))
        ['cmd', 'uno', 'dos', 'tres']
        >>> list(flatten_args("cmd", ["uno", "dos", "tres", ["4444", "five"]]))
        ['cmd', 'uno', 'dos', 'tres', '4444', 'five']

    """
    return list(_flatten_strings(*args))

shellfish.sh.fspath(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def fspath(fspath: FsPath) -> str:
    """Alias for os._fspath; returns fspath string for any type of path"""
    return _fspath(fspath)

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

Return an iterator of fspaths matching the given glob pattern

Parameters:

Name	Type	Description	Default
pattern	str	Glob pattern	required
recursive	bool	Recursively search directories if True	False
r	bool	Recursively search directories if True (Alias for recursive)	False

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def glob(pattern: str, *, recursive: bool = False, r: bool = False) -> Iterator[str]:
    """Return an iterator of fspaths matching the given glob pattern

    Args:
        pattern: Glob pattern
        recursive: Recursively search directories if True
        r: Recursively search directories if True (Alias for recursive)

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

    """
    return iglob(pattern, recursive=recursive or r)

shellfish.sh.is_dir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_dir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; alias for isdir"""
    return isdir(fspath)

shellfish.sh.is_dir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_dir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isdir_async(fspath)

shellfish.sh.is_file(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_file(fspath: FsPath) -> bool:
    """Return True if the given path is a file; alias for isfile"""
    return isfile(fspath)

shellfish.sh.is_file_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_file_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await isfile_async(fspath)

shellfish.sh.is_link(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def is_link(fspath: FsPath) -> bool:
    """Return True if the given path is a link; alias for islink"""
    return islink(fspath)

shellfish.sh.is_link_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def is_link_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await islink_async(fspath)

shellfish.sh.isdir(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isdir(fspath: FsPath) -> bool:
    """Return True if the given path is a directory; False otherwise"""
    return path.isdir(_fspath(fspath))

shellfish.sh.isdir_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isdir_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isdir(_fspath(fspath))

shellfish.sh.isfile(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def isfile(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return path.isfile(_fspath(fspath))

shellfish.sh.isfile_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def isfile_async(fspath: FsPath) -> bool:
    """Return True if the given path is a file; False otherwise"""
    return await aios.path.isfile(_fspath(fspath))

shellfish.sh.islink(fspath: FsPath) -> bool

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def islink(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return path.islink(_fspath(fspath))

shellfish.sh.islink_async(fspath: FsPath) -> bool async

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def islink_async(fspath: FsPath) -> bool:
    """Return True if the given path is a link; False otherwise"""
    return await aios.path.islink(_fspath(fspath))

shellfish.sh.listdir_async(fspath: FsPath) -> List[str] async

Async version of os.listdir

Source code in libs/shellfish/shellfish/fs/_async.py

async def listdir_async(fspath: FsPath) -> List[str]:
    """Async version of `os.listdir`"""
    return await aios.listdir(_fspath(fspath))

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]:
    r"""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

    """
    _attr = "path" if abspath else "name"
    return (
        getattr(el, _attr)
        for el in scandir_gen(
            fspath,
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )
    )

shellfish.sh.ls(dirpath: FsPath = '.', abspath: bool = False) -> List[str]

List files and dirs given a dirpath (defaults to pwd)

Parameters:

Name	Type	Description	Default
dirpath	FsPath	path-string to directory to list	'.'
abspath	bool	Give absolute paths	False

Returns:

Type	Description
List[str]	List of the directory items

Source code in libs/shellfish/shellfish/sh.py

def ls(dirpath: FsPath = ".", abspath: bool = False) -> List[str]:
    """List files and dirs given a dirpath (defaults to pwd)

    Args:
        dirpath (FsPath): path-string to directory to list
        abspath (bool): Give absolute paths

    Returns:
        List of the directory items

    """
    if abspath:
        return [el.path for el in scandir(str(dirpath))]
    return listdir(str(dirpath))

shellfish.sh.ls_async(dirpath: FsPath = '.', abspath: bool = False) -> List[str] async

List files and dirs given a dirpath (defaults to pwd)

Parameters:

Name	Type	Description	Default
dirpath	FsPath	path-string to directory to list	'.'
abspath	bool	Give absolute paths	False

Returns:

Type	Description
List[str]	List of the directory items

Source code in libs/shellfish/shellfish/sh.py

async def ls_async(dirpath: FsPath = ".", abspath: bool = False) -> List[str]:
    """List files and dirs given a dirpath (defaults to pwd)

    Args:
        dirpath (FsPath): path-string to directory to list
        abspath (bool): Give absolute paths

    Returns:
        List of the directory items

    """
    items = await listdir_async(dirpath)
    if abspath:
        return [path.join(dirpath, el) for el in items]
    return items

shellfish.sh.ls_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the directories in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want list directories	'.'
abspath	bool	Return absolute directory paths	False

Returns:

Type	Description
List[str]	List of directories as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_dirs(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the directories in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want list directories
        abspath (bool): Return absolute directory paths

    Returns:
        List of directories as strings

    """
    dirs = (el for el in scandir(str(dirpath)) if el.is_dir())
    if abspath:
        return list(map(lambda el: el.path, dirs))
    return list(map(lambda el: el.name, dirs))

shellfish.sh.ls_files(dirpath: FsPath = '.', *, abspath: bool = False) -> List[str]

List the files in a given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path for which one might want to list files	'.'
abspath	bool	Return absolute filepaths	False

Returns:

Type	Description
List[str]	List of files as strings

Source code in libs/shellfish/shellfish/sh.py

def ls_files(dirpath: FsPath = ".", *, abspath: bool = False) -> List[str]:
    """List the files in a given directory path

    Args:
        dirpath (FsPath): Directory path for which one might want to list files
        abspath (bool): Return absolute filepaths

    Returns:
        List of files as strings

    """
    files = (el for el in scandir(str(dirpath)) if el.is_file())
    if abspath:
        return list(map(lambda el: el.path, files))
    return list(map(lambda el: el.name, files))

shellfish.sh.ls_files_dirs(dirpath: FsPath = '.', *, abspath: bool = False) -> Tuple[List[str], List[str]]

List the files and directories given directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to execute on	'.'
abspath	bool	Return absolute file/directory paths	False

Returns:

Type	Description
Tuple[List[str], List[str]]	Two lists of strings; the first is a list of the files and the second is a list of the directories

Source code in libs/shellfish/shellfish/sh.py

def ls_files_dirs(
    dirpath: FsPath = ".", *, abspath: bool = False
) -> Tuple[List[str], List[str]]:
    """List the files and directories given directory path

    Args:
        dirpath (FsPath): Directory path to execute on
        abspath (bool): Return absolute file/directory paths

    Returns:
        Two lists of strings; the first is a list of the files and the second
            is a list of the directories

    """
    dir_items = list(fs.scandir_gen(dirpath, files=True, dirs=True))
    dir_dir_entries = (el for el in dir_items if el.is_dir())
    file_dir_entries = (el for el in dir_items if el.is_file())
    if not abspath:
        return [el.name for el in file_dir_entries], [el.name for el in dir_dir_entries]
    return [el.path for el in file_dir_entries], [el.path for el in dir_dir_entries]

shellfish.sh.lstat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def lstat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.lstat(str(fspath))

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

Make directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to create	required
parents	bool	Make parent dirs if True; do not make parent dirs if False	False
p	bool	Make parent dirs if True; do not make parent dirs if False (alias of parents)	False
exist_ok	bool	Throw error if directory exists and exist_ok is False	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdir(
    fspath: FsPath, *, parents: bool = False, p: bool = False, exist_ok: bool = False
) -> None:
    """Make directory at given fspath

    Args:
        fspath (FsPath): Directory path to create
        parents (bool): Make parent dirs if True; do not make parent dirs if False
        p (bool): Make parent dirs if True; do not make parent dirs if False (alias of parents)
        exist_ok (bool): Throw error if directory exists and exist_ok is False

    Returns:
         None

    """
    _parents = parents or p
    if _parents or exist_ok:
        return _makedirs(_fspath(fspath), exist_ok=_parents or exist_ok)
    return _mkdir(_fspath(fspath))

shellfish.sh.mkdirp(fspath: FsPath) -> None

Make directory and parents

Source code in libs/shellfish/shellfish/fs/__init__.py

def mkdirp(fspath: FsPath) -> None:
    """Make directory and parents"""
    return mkdir(fspath=fspath, parents=True)

shellfish.sh.move(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/fs/__init__.py

def move(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    _dst_str = str(dest)
    for file in iglob(str(src), recursive=True):
        _move(file, _dst_str)

shellfish.sh.mv(src: FsPath, dest: FsPath) -> None

Move file(s) like on the command line

Parameters:

Name	Type	Description	Default
src	FsPath	source file(s)	required
dest	FsPath	destination path	required

Source code in libs/shellfish/shellfish/sh.py

def mv(src: FsPath, dest: FsPath) -> None:
    """Move file(s) like on the command line

    Args:
        src (FsPath): source file(s)
        dest (FsPath): destination path

    """
    fs.move(src, dest)

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

Yield all filepaths as pathlib.Path objects beneath a dirpath

Source code in libs/shellfish/shellfish/fs/__init__.py

def path_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = False,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[Path]:
    r"""Yield all filepaths as pathlib.Path objects beneath a dirpath"""
    return (
        Path(el)
        for el in walk_gen(
            dirpath=dirpath,
            abspath=abspath,
            topdown=topdown,
            onerror=onerror,
            followlinks=followlinks,
            check=check,
        )
    )

shellfish.sh.pstderr(proc: CompletedProcess[AnyStr]) -> str

Get the STDERR as a string from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	python subprocess.process object with STDERR	required

Returns:

Type	Description
str	STDERR for the proc as string

Source code in libs/shellfish/shellfish/sh.py

def pstderr(proc: CompletedProcess[AnyStr]) -> str:
    """Get the STDERR as a string from a subprocess

    Args:
        proc: python subprocess.process object with STDERR

    Returns:
        STDERR for the proc as string

    """
    if proc.stderr is None:
        return ""
    return decode_stdio_bytes(proc.stderr)

shellfish.sh.pstdout(proc: CompletedProcess[AnyStr]) -> str

Get the STDOUT as a string from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	python subprocess.process object with stdout	required

Returns:

Type	Description
str	STDOUT for the proc as string

Source code in libs/shellfish/shellfish/sh.py

def pstdout(proc: CompletedProcess[AnyStr]) -> str:
    """Get the STDOUT as a string from a subprocess

    Args:
        proc: python subprocess.process object with stdout

    Returns:
        STDOUT for the proc as string

    """
    if proc.stdout is None:
        return ""
    return decode_stdio_bytes(proc.stdout)

shellfish.sh.pstdout_pstderr(proc: CompletedProcess[AnyStr]) -> Tuple[str, str]

Get the STDOUT and STDERR as strings from a subprocess

Parameters:

Name	Type	Description	Default
proc	CompletedProcess[AnyStr]	Completed-subprocess	required

Returns:

Type	Description
Tuple[str, str]	Tuple of two strings: (stdout-string, stderr-string)

Source code in libs/shellfish/shellfish/sh.py

def pstdout_pstderr(proc: CompletedProcess[AnyStr]) -> Tuple[str, str]:
    """Get the STDOUT and STDERR as strings from a subprocess

    Args:
        proc: Completed-subprocess

    Returns:
        Tuple of two strings: (stdout-string, stderr-string)

    """
    return pstdout(proc), pstderr(proc)

shellfish.sh.pwd() -> str

Return present-working-directory path string; alias for os.getcwd

Returns:

Name	Type	Description
str	str	present working directory as string

Examples:

>>> import os
>>> pwd() == os.getcwd()
True

Source code in libs/shellfish/shellfish/sh.py

def pwd() -> str:
    """Return present-working-directory path string; alias for os.getcwd

    Returns:
        str: present working directory as string

    Examples:
        >>> import os
        >>> pwd() == os.getcwd()
        True

    """
    return getcwd()

shellfish.sh.q(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> q("hello world")
"'hello world'"
>>> q("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def q(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> q("hello world")
        "'hello world'"
        >>> q("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.sh.quote(string: str) -> str

Typed alias for shlex.quote

Parameters:

Name	Type	Description	Default
string	str	string to quote	required

Returns:

Name	Type	Description
str	str	quoted string

Examples:

>>> quote("hello world")
"'hello world'"
>>> quote("hello 'world'")
'\'hello \'"\'"\'world\'"\'"\'\''

Source code in libs/shellfish/shellfish/sh.py

def quote(string: str) -> str:
    """Typed alias for shlex.quote

    Args:
        string (str): string to quote

    Returns:
        str: quoted string

    Examples:
        >>> quote("hello world")
        "'hello world'"
        >>> quote("hello 'world'")
        '\\'hello \\'"\\'"\\'world\\'"\\'"\\'\\''

    """
    return _quote(string)

shellfish.sh.rbytes(filepath: FsPath) -> bytes

Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes(filepath: FsPath) -> bytes:
    """Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    with open(filepath, "rb") as file:
        return bytes(file.read())

shellfish.sh.rbytes_async(filepath: FsPath) -> bytes async

(ASYNC) Load/Read bytes from a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath read as bytes	required

Returns:

Type	Description
bytes	bytes from the fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_async(filepath: FsPath) -> bytes:
    """(ASYNC) Load/Read bytes from a fspath

    Args:
        filepath: fspath read as bytes

    Returns:
        bytes from the fspath

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

    """
    async with aiopen(filepath, "rb") as file:
        b = await file.read()
    return bytes(b)

shellfish.sh.rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]

Yield bytes from a given fspath

Source code in libs/shellfish/shellfish/fs/__init__.py

def rbytes_gen(filepath: FsPath, blocksize: int = 65536) -> Iterable[bytes]:
    """Yield bytes from a given fspath"""
    with open(filepath, "rb") as f:
        while True:
            data = f.read(blocksize)
            if not data:
                break
            yield data

shellfish.sh.rbytes_gen_async(filepath: FsPath, blocksize: int = 65536) -> AsyncIterable[Union[bytes, str]] async

Yield (asynchronously) bytes from a given fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to read from	required
blocksize	int	size of the block to read	65536

Yields:

Type	Description
AsyncIterable[Union[bytes, str]]	bytes from AsyncIterable[bytes] of the file bytes

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def rbytes_gen_async(
    filepath: FsPath, blocksize: int = 65536
) -> AsyncIterable[Union[bytes, str]]:
    """Yield (asynchronously) bytes from a given fspath

    Args:
        filepath: fspath to read from
        blocksize (int): size of the block to read

    Yields:
        bytes from AsyncIterable[bytes] of the file bytes

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)

    """
    async with aiopen(filepath, "rb") as f:
        while True:
            data = await f.read(blocksize)
            if not data:
                break
            yield data

shellfish.sh.rjson(filepath: FsPath) -> Any

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def rjson(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)

    """
    return JSON.loads(lstring(filepath=filepath))

shellfish.sh.rjson_async(filepath: FsPath) -> Any async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath to load/read data from	required

Returns:

Type	Description
Any	Parsed JSON data

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def rjson_async(filepath: FsPath) -> Any:
    """Load/Read-&-parse json data given a fspath

    Args:
        filepath: Filepath to load/read data from

    Returns:
        Parsed JSON data

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    json_string = await rbytes_async(filepath)
    return JSON.loads(json_string)

shellfish.sh.rm(fspath: FsPath, *, force: bool = False, recursive: bool = False, verbose: bool = False, f: bool = False, r: bool = False, v: bool = False, dryrun: bool = False) -> None

Remove files & directories in the style of the shell

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory to remove	required
force	bool	Flag to force removal; ignore missing	False
recursive	bool	Flag to remove recursively (like the -r in rm -r dir)	False
verbose	bool	Flag to be verbose	False
f	bool	alias for force kwarg	False
v	bool	alias for verbose	False
r	bool	alias for recursive kwarg	False
dryrun	bool	Flag to not actually remove anything	False

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/sh.py

def rm(
    fspath: FsPath,
    *,
    force: bool = False,
    recursive: bool = False,
    verbose: bool = False,
    f: bool = False,
    r: bool = False,
    v: bool = False,
    dryrun: bool = False,
) -> None:
    """Remove files & directories in the style of the shell

    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Flag to force removal; ignore missing
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        verbose (bool): Flag to be verbose
        f (bool): alias for force kwarg
        v (bool): alias for verbose
        r (bool): alias for recursive kwarg
        dryrun (bool): Flag to not actually remove anything

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if verbose or v:
        echo(f"Removing {fspath}")
    fs.rm(
        fspath,
        force=force or f,
        recursive=recursive or r,
        dryrun=dryrun,
    )

shellfish.sh.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 Args: fspath (FsPath): Path to file or directory to remove force (bool): Force removal of files and directories recursive (bool): Flag to remove recursively (like the -r in rm -r dir) dryrun (bool): Do not remove file if True

Raises:

Type	Description
ValueError	If recursive and r are False and fspath is a directory

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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
    Args:
        fspath (FsPath): Path to file or directory to remove
        force (bool): Force removal of files and directories
        recursive (bool): Flag to remove recursively (like the `-r` in `rm -r dir`)
        dryrun (bool): Do not remove file if True

    Raises:
        ValueError: If recursive and r are `False` and fspath is a directory

    """
    if has_magic(str(fspath)):
        if dryrun:
            yield from iglob(_fspath(fspath), recursive=recursive)
        else:
            for _path_str in iglob(str(fspath), recursive=recursive):
                if isfile(_path_str):
                    remove(_path_str)
                elif recursive:
                    rmdir(_path_str, recursive=True, force=force)
                else:
                    raise ValueError(
                        f"{str(_path_str)} (under {str(fspath)}) is a directory -- use r=True or recursive=True"
                    )
    else:
        if isfile(fspath):
            if not dryrun:
                remove(_fspath(fspath))
            yield _fspath(fspath)
        elif recursive:
            if not dryrun:
                rmdir(fspath, force=force, recursive=True)
            yield _fspath(fspath)
        else:
            raise ValueError(
                f"{str(fspath)} is a directory -- use r=True or recursive=True"
            )

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

Remove directory at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Directory path to remove	required
force	bool	Force removal of files and directories	False
recursive	bool	Recursively remove all contents if True	False

Returns:

Type	Description
None	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmdir(fspath: FsPath, *, force: bool = False, recursive: bool = False) -> None:
    """Remove directory at given fspath

    Args:
        fspath (FsPath): Directory path to remove
        force (bool): Force removal of files and directories
        recursive (bool): Recursively remove all contents if True

    Returns:
        None

    """
    if force:
        try:
            return rmdir(fspath, recursive=recursive)
        except FileNotFoundError:
            return
    if recursive:
        return rmtree(_fspath(fspath))
    return _rmdir(_fspath(fspath))

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

Remove a file at given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Filepath to remove	required
dryrun	bool	Do not remove file if True	False

Returns:

Type	Description
str	None

Source code in libs/shellfish/shellfish/fs/__init__.py

def rmfile(fspath: FsPath, *, dryrun: bool = False) -> str:
    """Remove a file at given fspath

    Args:
        fspath (FsPath): Filepath to remove
        dryrun (bool): Do not remove file if True

    Returns:
        None

    """
    if not dryrun:
        remove(_fspath(fspath))
    return _fspath(fspath)

shellfish.sh.rstring(filepath: FsPath, *, encoding: str = 'utf-8') -> str

Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	Encoding to use for reading the file	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def rstring(filepath: FsPath, *, encoding: str = "utf-8") -> str:
    r"""Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding: Encoding to use for reading the file

    Returns:
        str: String read from given fspath

    Examples:
        ``` python
        >>> from shellfish.fs import rstring, wstring
        >>> fspath = "lstring.doctest.txt"
        >>> sstring(fspath, r'Check out this string')
        21
        >>> lstring(fspath)
        'Check out this string'
        >>> import os; os.remove(fspath)

        ```

    """
    _bytes = rbytes(filepath=filepath)
    try:
        return _bytes.decode(encoding=encoding)
    except UnicodeDecodeError:  # Catch the unicode decode error
        pass
    return _bytes.decode(encoding="latin2")

shellfish.sh.rstring_async(filepath: FsPath, encoding: str = 'utf-8') -> str async

(ASYNC) Load/Read a string given a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	Filepath for file to read	required
encoding	str	File encoding (Default='utf-8')	'utf-8'

Returns:

Name	Type	Description
str	str	String read from given fspath

Source code in libs/shellfish/shellfish/fs/_async.py

async def rstring_async(filepath: FsPath, encoding: str = "utf-8") -> str:
    r"""(ASYNC) Load/Read a string given a fspath

    Args:
        filepath: Filepath for file to read
        encoding (str): File encoding (Default='utf-8')

    Returns:
        str: String read from given fspath

    """
    return (await rbytes_async(filepath)).decode(encoding=encoding)

shellfish.sh.safepath(fspath: FsPath) -> str

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	file-system path; file or directory path string or Path obj	required

Returns:

Name	Type	Description
str	str	file/dir path that does not exist and contains the given path

Source code in libs/shellfish/shellfish/fs/__init__.py

def safepath(fspath: FsPath) -> str:
    """Check if a file/dir path is save/unused; returns an unused path.

    Args:
        fspath: file-system path; file or directory path string or Path obj

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

    """
    path_str = str(fspath)
    if path.exists(path_str):
        f_bn, f_ext = path.splitext(path_str)
        for n in count(1):
            safe_save_path = f"{f_bn}_{str(n).zfill(3)}.{f_ext}"
            if not path.exists(safe_save_path):
                return safe_save_path
    return path_str

shellfish.sh.scandir(dirpath: FsPath = '.') -> Iterable[DirEntry[AnyStr]]

Typed version of os.scandir

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir(dirpath: FsPath = ".") -> Iterable[DirEntry[AnyStr]]:
    """Typed version of os.scandir"""
    if not isdir(dirpath):
        raise NotADirectoryError(f"{dirpath} is not a directory")
    return cast("Iterable[DirEntry[AnyStr]]", _scandir(fspath(dirpath)))

shellfish.sh.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:

Name	Type	Description	Default
fspath	FsPath	(FsPath): dirpath to look through	'.'
recursive	bool	recursively scan the directory	False
follow_symlinks	bool	follow symlinks when checking for dirs and files	True
files	bool	include files	True
dirs	bool	include directories	True
symlinks	bool	include symlinks	True
dirs_only	bool	only include directories	False
files_only	bool	only include files	False
symlinks_only	bool	only include symlinks	False

Returns:

Type	Description
Iterator[DirEntry[str]]	Iterator[DirEntry]: Iterator of os.DirEntry objects

Raises:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def 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]]:
    r"""Return an iterator of os.DirEntry objects

    Args:
        fspath: (FsPath): dirpath to look through
        recursive (bool): recursively scan the directory
        follow_symlinks (bool): follow symlinks when checking for dirs and files
        files (bool): include files
        dirs (bool): include directories
        symlinks (bool): include symlinks
        dirs_only (bool): only include directories
        files_only (bool): only include files
        symlinks_only (bool): only include symlinks

    Returns:
        Iterator[DirEntry]: Iterator of os.DirEntry objects

    Raises:
        ValueError: if any of the kwargs (`dirs`, `files` and `symlinks`) are not True

    """
    if not recursive:
        return scandir_gen_filter(
            scandir(fspath),
            follow_symlinks=follow_symlinks,
            files=files,
            dirs=dirs,
            symlinks=symlinks,
            files_only=files_only,
            dirs_only=dirs_only,
            symlinks_only=symlinks_only,
        )

    return scandir_gen_filter(
        chain(
            scandir(fspath),
            *(
                scandir_gen(
                    el.path,
                    recursive=True,
                    follow_symlinks=follow_symlinks,
                    files=files,
                    dirs=True,
                    symlinks=symlinks,
                    files_only=files_only,
                    dirs_only=dirs_only,
                    symlinks_only=symlinks_only,
                )
                for el in scandir(fspath)
                if el.is_dir(follow_symlinks=follow_symlinks)
            ),
        ),
        follow_symlinks=follow_symlinks,
        files=files,
        dirs=dirs,
        symlinks=symlinks,
        files_only=files_only,
        dirs_only=dirs_only,
        symlinks_only=symlinks_only,
    )

shellfish.sh.scandir_list(dirpath: FsPath = '.') -> List[DirEntry[AnyStr]]

Return a list of os.DirEntry objects

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Dirpath to scan	'.'

Returns:

Type	Description
List[DirEntry[AnyStr]]	List[DirEntry]: List of os.DirEntry objects

Source code in libs/shellfish/shellfish/fs/__init__.py

def scandir_list(dirpath: FsPath = ".") -> List[DirEntry[AnyStr]]:
    """Return a list of os.DirEntry objects

    Args:
        dirpath: Dirpath to scan

    Returns:
        List[DirEntry]: List of os.DirEntry objects

    """
    return list(scandir(dirpath))

shellfish.sh.seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]

Return hr-time Tuple[int, int] (seconds, nanoseconds)

Parameters:

Name	Type	Description	Default
seconds	float	number of seconds	required

Returns:

Type	Description
Tuple[int, int]	Tuple[int, int]: (seconds, nanoseconds)

Source code in libs/shellfish/shellfish/sh.py

def seconds2hrtime(seconds: Union[float, int]) -> Tuple[int, int]:
    """Return hr-time Tuple[int, int] (seconds, nanoseconds)

    Args:
        seconds (float): number of seconds

    Returns:
        Tuple[int, int]: (seconds, nanoseconds)

    """
    _sec, _ns = divmod(int(seconds * 1_000_000_000), 1_000_000_000)
    return _sec, _ns

shellfish.sh.sep_join(path_strings: Iterator[str]) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_join(path_strings: Iterator[str]) -> str:
    """Join iterable of strings on the current platform os.path.sep value"""
    return sep.join(path_strings)

shellfish.sh.sep_lstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_lstrip(fspath: FsPath) -> str:
    """Left-strip a string of the current platform's os.path.sep value"""
    return str(fspath).lstrip(sep)

shellfish.sh.sep_rstrip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_rstrip(fspath: FsPath) -> str:
    """Right-strip a string of the current platform's os.path.sep value"""
    return str(fspath).rstrip(sep)

shellfish.sh.sep_split(fspath: FsPath) -> Tuple[str, ...]

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_split(fspath: FsPath) -> Tuple[str, ...]:
    """Split a string on the current platform os.path.sep value"""
    return tuple(el for el in str(fspath).split(sep) if el != sep and el != "")

shellfish.sh.sep_strip(fspath: FsPath) -> str

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def sep_strip(fspath: FsPath) -> str:
    """Strip a string of the current platform's os.path.sep value"""
    return str(fspath).strip(sep)

shellfish.sh.setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]

Export/Set an environment variable

Parameters:

Name	Type	Description	Default
key	str	environment variable name/key	required
val	str	environment variable value	None

Returns:

Type	Description
Tuple[str, str]	Tuple[str, str]: environment variable key/value pair

Source code in libs/shellfish/shellfish/sh.py

def setenv(key: str, val: Optional[str] = None) -> Tuple[str, str]:
    """Export/Set an environment variable

    Args:
        key (str): environment variable name/key
        val (str): environment variable value

    Returns:
        Tuple[str, str]: environment variable key/value pair

    """
    return export(key=key, val=val)

shellfish.sh.shebang(fspath: FsPath) -> Union[None, str]

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

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file that might have a shebang	required

Returns:

Type	Description
Union[None, str]	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)

Source code in libs/shellfish/shellfish/fs/__init__.py

def shebang(fspath: FsPath) -> Union[None, str]:
    r"""Get the shebang string given a fspath; Returns None if no shebang

    Args:
        fspath (FsPath): Path to file that might have a shebang

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

    """
    with open(fspath) as f:
        first = f.readline().replace("\r\n", "\n").strip("\n")
        return first if "#!" in first[:2] else None

shellfish.sh.shell(*popenargs: PopenArgs, args: Optional[PopenArgs] = None, env: Optional[Dict[str, str]] = None, shell: bool = True, extenv: bool = True, cwd: Optional[FsPath] = None, check: bool = False, verbose: bool = False, input: STDIN = None, timeout: Optional[Union[float, int]] = None, ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0, dryrun: bool = False) -> Done

Run a subprocess synchronously in current shell

Parameters:

Name	Type	Description	Default
*popenargs	PopenArgs	Args given as *args; Cannot use both *popenargs and args	()
args	Optional[PopenArgs]	Args as strings for the subprocess	None
env	Optional[Dict[str, str]]	Environment variables as a dictionary (Default value = None)	None
shell	bool	Run in shell or sub-shell; default is True for shx	True
extenv	bool	Extend the environment with the current environment (Default value = True)	True
cwd	Optional[FsPath]	Current working directory (Default value = None)	None
check	bool	Check the outputs (generally useless)	False
input	STDIN	Stdin to give to the subprocess	None
verbose	bool	Flag to write the subprocess stdout and stderr to sys.stdout and sys.stderr	False
timeout	Optional[int]	Timeout in seconds for the process if not None	None
ok_code	Union[int, List[int], Tuple[int, ...], Set[int]]	Return code(s) to check if ok	0
dryrun	bool	Don't run the subprocess	False

Returns:

Type	Description
Done	Finished PRun object which is a dictionary, so a dictionary

Source code in libs/shellfish/shellfish/sh.py

def shell(
    *popenargs: PopenArgs,
    args: Optional[PopenArgs] = None,
    env: Optional[Dict[str, str]] = None,
    shell: bool = True,
    extenv: bool = True,
    cwd: Optional[FsPath] = None,
    check: bool = False,
    verbose: bool = False,
    input: STDIN = None,
    timeout: Optional[Union[float, int]] = None,
    ok_code: Union[int, List[int], Tuple[int, ...], Set[int]] = 0,
    dryrun: bool = False,
) -> Done:
    """Run a subprocess synchronously in current shell

    Args:
        *popenargs: Args given as `*args`; Cannot use both *popenargs and args
        args: Args as strings for the subprocess
        env: Environment variables as a dictionary (Default value = None)
        shell: Run in shell or sub-shell; default is True for `shx`
        extenv: Extend the environment with the current environment (Default value = True)
        cwd: Current working directory (Default value = None)
        check: Check the outputs (generally useless)
        input: Stdin to give to the subprocess
        verbose (bool): Flag to write the subprocess stdout and stderr to
            sys.stdout and sys.stderr
        timeout (Optional[int]): Timeout in seconds for the process if not None
        ok_code: Return code(s) to check if ok
        dryrun: Don't run the subprocess


    Returns:
        Finished PRun object which is a dictionary, so a dictionary

    """
    return do(
        *popenargs,
        args=args,
        shell=shell,
        env=env,
        extenv=extenv,
        cwd=cwd,
        check=check,
        verbose=verbose,
        input=input,
        timeout=timeout,
        ok_code=ok_code,
        dryrun=dryrun,
    )

shellfish.sh.shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]

Typed alias for shlex.split

Source code in libs/shellfish/shellfish/sh.py

def shplit(string: str, comments: bool = False, posix: bool = True) -> List[str]:
    """Typed alias for shlex.split"""
    return _shplit(string, comments=comments, posix=posix)

shellfish.sh.source(filepath: FsPath, _globals: bool = True) -> None

Execute/run a python file given a fspath and put globals in globasl

Parameters:

Name	Type	Description	Default
filepath	FsPath	Path to python file	required
_globals	bool	Exec using globals	True

Source code in libs/shellfish/shellfish/sh.py

def source(filepath: FsPath, _globals: bool = True) -> None:  # pragma: nocov
    """Execute/run a python file given a fspath and put globals in globasl

    Args:
        filepath (FsPath): Path to python file
        _globals (bool): Exec using globals

    """
    string = fs.lstring(str(filepath))
    if _globals:
        exec(string, globals())
    else:
        exec(string)

shellfish.sh.stat(fspath: FsPath) -> os_stat_result

Return the os.stat_result object for a given fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	Path to file or directory	required

Returns:

Type	Description
stat_result	os.stat_result: stat_result object

Source code in libs/shellfish/shellfish/fs/__init__.py

def stat(fspath: FsPath) -> os_stat_result:
    """Return the os.stat_result object for a given fspath

    Args:
        fspath (FsPath): Path to file or directory

    Returns:
        os.stat_result: stat_result object

    """
    return _stat(_fspath(fspath))

shellfish.sh.stat_async(fspath: FsPath) -> os.stat_result async

Async version of os.lstat

Source code in libs/shellfish/shellfish/fs/_async.py

async def stat_async(fspath: FsPath) -> os.stat_result:
    """Async version of `os.lstat`"""
    return await aios.stat(str(fspath))

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

Create an empty file given a fspath

Parameters:

Name	Type	Description	Default
fspath	FsPath	File-system path for where to make an empty file	required
mkdirp	bool	Make parent directories if they don't exist	True

Source code in libs/shellfish/shellfish/fs/__init__.py

def touch(fspath: FsPath, *, mkdirp: bool = True) -> None:
    """Create an empty file given a fspath

    Args:
        fspath (FsPath): File-system path for where to make an empty file
        mkdirp (bool): Make parent directories if they don't exist

    """
    if not path.exists(str(fspath)):
        if mkdirp:
            parent_dir = path.dirname(str(fspath))
            if parent_dir:
                _makedirs(parent_dir, exist_ok=True)
        with open(fspath, "a"):
            utime(fspath, None)

shellfish.sh.tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str

Create a directory tree string given a directory path

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory string to make tree for	required
filterfn	Optional[Callable[[str], bool]]	Function to filter sub-directories and sub-files with	None

Returns:

Name	Type	Description
str	str	Directory-tree string

Examples:

>>> tmpdir = 'tree.doctest'
>>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
>>> from pathlib import Path
>>> 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"),
... ]
>>> 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)
...     Path(fspath).touch()
>>> print(tree(tmpdir))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   ├── file2.txt
    │   └── file3.txt
    ├── file1.txt
    ├── file2.txt
    └── file3.txt
>>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
tree.doctest/
└── dir/
    ├── dir2/
    │   ├── file1.txt
    │   └── file3.txt
    ├── dir2a/
    │   ├── file1.txt
    │   └── file3.txt
    ├── file1.txt
    └── file3.txt
>>> from shutil import rmtree
>>> rmtree(tmpdir)

Source code in libs/shellfish/shellfish/sh.py

def tree(dirpath: FsPath, filterfn: Optional[Callable[[str], bool]] = None) -> str:
    """Create a directory tree string given a directory path

    Args:
        dirpath (FsPath): Directory string to make tree for
        filterfn: Function to filter sub-directories and sub-files with

    Returns:
        str: Directory-tree string

    Examples:
        >>> tmpdir = 'tree.doctest'
        >>> from os import makedirs; makedirs(tmpdir, exist_ok=True)
        >>> from pathlib import Path
        >>> 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"),
        ... ]
        >>> 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)
        ...     Path(fspath).touch()
        >>> print(tree(tmpdir))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   ├── file2.txt
            │   └── file3.txt
            ├── file1.txt
            ├── file2.txt
            └── file3.txt
        >>> print(tree(tmpdir, lambda s: _DirTree._default_filter(s) and not "file2" in s))
        tree.doctest/
        └── dir/
            ├── dir2/
            │   ├── file1.txt
            │   └── file3.txt
            ├── dir2a/
            │   ├── file1.txt
            │   └── file3.txt
            ├── file1.txt
            └── file3.txt
        >>> from shutil import rmtree
        >>> rmtree(tmpdir)

    """
    return "\n".join(
        p.displayable() for p in _DirTree.make_tree(Path(dirpath), filterfn=filterfn)
    )

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

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

Parameters:

Name	Type	Description	Default
dirpath	FsPath	Directory path to walk down/through.	'.'
abspath	bool	Yield the absolute path	True
onerror	Optional[Callable[[OSError], Any]]	Function called on OSError	None
topdown	bool	Not applicable	True
followlinks	bool	Follow links	False
check	bool	Check if dirpath exists	True

Returns:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def walk_gen(
    dirpath: FsPath = ".",
    *,
    abspath: bool = True,
    topdown: bool = True,
    onerror: Optional[Callable[[OSError], Any]] = None,
    followlinks: bool = False,
    check: bool = True,
) -> Iterator[str]:
    r"""Yield all paths beneath a given dirpath (defaults to os.getcwd())

    Args:
        dirpath: Directory path to walk down/through.
        abspath (bool): Yield the absolute path
        onerror: Function called on OSError
        topdown: Not applicable
        followlinks: Follow links
        check: Check if dirpath exists

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

    """
    dirpath = str(dirpath)
    if check and not isdir(dirpath):
        raise NotADirectoryError(dirpath)
    return (
        (
            str(path_string)
            if abspath
            else str(path_string).replace(dirpath, "").strip(sep)
        )
        for path_string in chain.from_iterable(
            (
                pwd,
                *(path.join(pwd, _file) for _file in files),
            )
            for pwd, dirs, files in walk(
                dirpath,
                topdown=topdown,
                followlinks=followlinks,
                onerror=onerror,
            )
        )
    )

shellfish.sh.wbytes(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = 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:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        filepath: fspath to write to
        bites: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

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

    """
    _write_mode = "ab" if append else "wb"
    with open(filepath, _write_mode) as fd:
        nbytes = fd.write(bites)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes

shellfish.sh.wbytes_async(filepath: FsPath, bites: bytes, *, append: bool = False, chmod: Optional[int] = None) -> int async

(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:

Name	Type	Description	Default
append	bool	Append to the fspath if True; otherwise overwrite	False
filepath	FsPath	fspath to write to	required
bites	bytes	Bytes to be written	required
chmod	Optional[int]	chmod the fspath to this mode after writing	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_async(
    filepath: FsPath,
    bites: bytes,
    *,
    append: bool = False,
    chmod: Optional[int] = 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.

    Args:
        append (bool): Append to the fspath if True; otherwise overwrite
        filepath: fspath to write to
        bites: Bytes to be written
        chmod: chmod the fspath to this mode after writing

    Returns:
        None

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

    """
    _write_mode = "ab" if append else "wb"
    async with aiopen(filepath, _write_mode) as fd:
        nbytes = await fd.write(bites)
    if chmod is not None:
        await aios.chmod(str(filepath), chmod)
    return int(nbytes)

shellfish.sh.wbytes_gen(filepath: FsPath, bytes_gen: Iterable[bytes], append: bool = False, chmod: Optional[int] = None) -> int

Write/Save bytes to a fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Iterable[bytes]	Bytes to be written	required
append	bool	Append to the file if True, overwrite otherwise; default is False	False
chmod	Optional[int]	chmod the file after writing; default is None	None

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

>>> from shellfish.fs import rbytes, wbytes
>>> 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!')
>>> wbytes_gen(fspath, (b for b in bites_to_save))
35
>>> rbytes(fspath)
b'These are some bytes... more bytes!'
>>> import os; os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wbytes_gen(
    filepath: FsPath,
    bytes_gen: Iterable[bytes],
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/Save bytes to a fspath

    Args:
        filepath: fspath to write to
        bytes_gen: Bytes to be written
        append (bool): Append to the file if True, overwrite otherwise; default
            is False
        chmod (Optional[int]): chmod the file after writing; default is None

    Returns:
        int: Number of bytes written

    Examples:
        >>> from shellfish.fs import rbytes, wbytes
        >>> 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!')
        >>> wbytes_gen(fspath, (b for b in bites_to_save))
        35
        >>> rbytes(fspath)
        b'These are some bytes... more bytes!'
        >>> import os; os.remove(fspath)

    """
    _mode = const.ab if append else const.wb
    with open(filepath, mode=_mode) as fd:
        nbytes_written = sum(fd.write(chunk) for chunk in bytes_gen)
    if chmod is not None:
        _chmod(filepath, chmod)
    return nbytes_written

shellfish.sh.wbytes_gen_async(filepath: FsPath, bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]], *, append: bool = False, chmod: Optional[int] = None) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
bytes_gen	Union[Iterable[bytes], AsyncIterable[bytes]]	AsyncIterable/Iterator of bytes to write	required
append	bool	Append to the fspath if True; otherwise overwrite	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Examples:

>>> from os import remove
>>> from asyncio import run
>>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
35
>>> async def read():
...     async for b in rbytes_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(wbytes_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(wbytes_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)

Source code in libs/shellfish/shellfish/fs/_async.py

async def wbytes_gen_async(
    filepath: FsPath,
    bytes_gen: Union[Iterable[bytes], AsyncIterable[bytes]],
    *,
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Write/save bytes to a filepath from an (async)iterable/iterator of bytes

    Args:
        filepath: fspath to write to
        bytes_gen: AsyncIterable/Iterator of bytes to write
        append: Append to the fspath if True; otherwise overwrite
        chmod: chmod the fspath if not None

    Returns:
        int: number of bytes written

    Examples:
        >>> from os import remove
        >>> from asyncio import run
        >>> from shellfish.fs._async import wbytes_gen_async, rbytes_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(wbytes_gen_async(fspath, bites_to_save))
        35
        >>> async def read():
        ...     async for b in rbytes_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(wbytes_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(wbytes_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)


    """
    _bytes_written = 0
    async with aiopen(filepath, "ab" if append else "wb") as f:
        if isinstance(bytes_gen, AsyncIterator):
            async for b in bytes_gen:
                _bytes_written += await f.write(b)
        elif isinstance(bytes_gen, AsyncIterable):
            async for b in bytes_gen.__aiter__():
                _bytes_written += await f.write(b)
        else:
            for b in bytes_gen:
                _bytes_written += await f.write(b)
    if chmod is not None:  # pragma: nocov
        await aios.chmod(filepath, chmod)
    return _bytes_written

shellfish.sh.where(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which; alias of shellfish.sh.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def where(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`; alias of shellfish.sh.which

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

shellfish.sh.which(cmd: str, path: Optional[str] = None) -> Optional[str]

Return the result of shutil.which

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

def which(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which`

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return _which(cmd, path=path)

shellfish.sh.which_lru(cmd: str, path: Optional[str] = None) -> Optional[str] cached

Return the result of shutil.which and cache the results

Parameters:

Name	Type	Description	Default
cmd	str	Command/exe to find path of	required
path	str	System path to use	None

Returns:

Type	Description
Optional[str]	Optional[str]: path to command/exe

Source code in libs/shellfish/shellfish/sh.py

@lru_cache(maxsize=128)
def which_lru(cmd: str, path: Optional[str] = None) -> Optional[str]:
    """Return the result of `shutil.which` and cache the results

    Args:
        cmd (str): Command/exe to find path of
        path (str): System path to use

    Returns:
        Optional[str]: path to command/exe

    """
    return which(cmd, path=path)

shellfish.sh.wjson(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, chmod: Optional[int] = None, append: bool = False, **kwargs: Any) -> int

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Append a newline to the end of the file	False
default	Optional[Callable[[Any], Any]]	default function hook	None
chmod	Optional[int]	Optional chmod to set on file	None
append	bool	Append to the file if True, overwrite otherwise; default	False
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dumpb	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from shellfish.fs import rjson, wjson

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "rjson_dict.doctest.json"
>>> wjson(fspath, data)
19
>>> rjson(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"
>>> wjson(fspath, data)
25
>>> rjson(fspath)
[['a', 1], ['b', 2], ['c', 3]]
>>> os.remove(fspath)

Source code in libs/shellfish/shellfish/fs/__init__.py

def wjson(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    chmod: Optional[int] = None,
    append: bool = False,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Append a newline to the end of the file
        default: default function hook
        chmod (Optional[int]): Optional chmod to set on file
        append (bool): Append to the file if True, overwrite otherwise; default
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dumpb

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from shellfish.fs import rjson, wjson

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "rjson_dict.doctest.json"
        >>> wjson(fspath, data)
        19
        >>> rjson(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"
        >>> wjson(fspath, data)
        25
        >>> rjson(fspath)
        [['a', 1], ['b', 2], ['c', 3]]
        >>> os.remove(fspath)


    """
    return wbytes(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        chmod=chmod,
        append=append,
    )

shellfish.sh.wjson_async(filepath: FsPath, data: Any, *, fmt: bool = False, pretty: bool = False, sort_keys: bool = False, append_newline: bool = False, default: Optional[Callable[[Any], Any]] = None, append: bool = False, chmod: Optional[int] = None, **kwargs: Any) -> int async

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

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
data	Any	json-serial-ize-able data	required
fmt	bool	Indented (2 spaces) or minify data (default=False)	False
pretty	bool	Indented (2 spaces) or minify data (default=False)	False
sort_keys	bool	Sort the data keys if the data is a dictionary.	False
append_newline	bool	Sort the data keys if the data is a dictionary.	False
default	Optional[Callable[[Any], Any]]	default function hook	None
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None
**kwargs	Any	Additional keyword arguments to pass to jsonbourne.JSON.dump	{}

Returns:

Name	Type	Description
int	int	Number of bytes written

Examples:

Imports:

>>> from asyncio import run
>>> from shellfish.fs._async import rjson_async, wjson_async

Dictionaries:

>>> data = {'a': 1, 'b': 2, 'c': 3}
>>> fspath = "wjson_async_dict.doctest.json"
>>> run(wjson_async(fspath, data))
19
>>> run(rjson_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(wjson_async(fspath, data))
25
>>> run(rjson_async(fspath))
[['a', 1], ['b', 2], ['c', 3]]

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

Source code in libs/shellfish/shellfish/fs/_async.py

async def wjson_async(
    filepath: FsPath,
    data: Any,
    *,
    fmt: bool = False,
    pretty: bool = False,
    sort_keys: bool = False,
    append_newline: bool = False,
    default: Optional[Callable[[Any], Any]] = None,
    append: bool = False,
    chmod: Optional[int] = None,
    **kwargs: Any,
) -> int:
    """Save/Write json-serial-ize-able data to a fspath

    Args:
        filepath: fspath to write to
        data (Any): json-serial-ize-able data
        fmt (bool): Indented (2 spaces) or minify data (default=False)
        pretty (bool): Indented (2 spaces) or minify data (default=False)
        sort_keys (bool): Sort the data keys if the data is a dictionary.
        append_newline (bool): Sort the data keys if the data is a dictionary.
        default: default function hook
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None
        **kwargs: Additional keyword arguments to pass to jsonbourne.JSON.dump

    Returns:
        int: Number of bytes written

    Examples:
        Imports:

        >>> from asyncio import run
        >>> from shellfish.fs._async import rjson_async, wjson_async

        Dictionaries:

        >>> data = {'a': 1, 'b': 2, 'c': 3}
        >>> fspath = "wjson_async_dict.doctest.json"
        >>> run(wjson_async(fspath, data))
        19
        >>> run(rjson_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(wjson_async(fspath, data))
        25
        >>> run(rjson_async(fspath))
        [['a', 1], ['b', 2], ['c', 3]]

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

    """
    return await wbytes_async(
        filepath=filepath,
        bites=JSON.dumpb(
            data=data,
            fmt=fmt,
            pretty=pretty,
            append_newline=append_newline,
            default=default,
            sort_keys=sort_keys,
            **kwargs,
        ),
        append=append,
        chmod=chmod,
    )

shellfish.sh.wstring(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int

Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	String encoding to write file with	'utf-8'
append	bool	Flag to append to file; default = False	False
chmod	Optional[int]	Optional chmod to set on file	None

Returns:

Type	Description
int	None

Examples:

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

Source code in libs/shellfish/shellfish/fs/__init__.py

def wstring(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding: String encoding to write file with
        append (bool): Flag to append to file; default = False
        chmod (Optional[int]): Optional chmod to set on file

    Returns:
        None

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

    """
    return wbytes(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

shellfish.sh.wstring_async(filepath: FsPath, string: str, *, encoding: str = 'utf-8', append: bool = False, chmod: Optional[int] = None) -> int async

(ASYNC) Save/Write a string to fspath

Parameters:

Name	Type	Description	Default
filepath	FsPath	fspath to write to	required
string	str	string to be written	required
encoding	str	File encoding (Default='utf-8')	'utf-8'
append	bool	Append to the fspath if True; default is False	False
chmod	Optional[int]	chmod the fspath if not None	None

Returns:

Name	Type	Description
int	int	number of bytes written

Source code in libs/shellfish/shellfish/fs/_async.py

async def wstring_async(
    filepath: FsPath,
    string: str,
    *,
    encoding: str = "utf-8",
    append: bool = False,
    chmod: Optional[int] = None,
) -> int:
    """(ASYNC) Save/Write a string to fspath

    Args:
        filepath: fspath to write to
        string (str): string to be written
        encoding (str): File encoding (Default='utf-8')
        append (bool): Append to the fspath if True; default is False
        chmod (Optional[int]): chmod the fspath if not None

    Returns:
        int: number of bytes written

    """
    return await wbytes_async(
        filepath=filepath,
        bites=string.encode(encoding),
        append=append,
        chmod=chmod,
    )

Modules