done ⚓︎

Done ~ completed subprocess results

Classes:

HrTimeDict –

High resolution time as a typed-dict; see HrTime
HrTime –

High resolution time split into whole seconds and nanoseconds
DoneError –

Error raised when a process returns a non-zero/not-ok exit status
DoneDict –

Completed subprocess as a typed-dict; see Done
Done –

Completed subprocess

HrTimeDict ⚓︎

Bases: TypedDict

High resolution time as a typed-dict; see HrTime

Attributes:

secs (int) –

Whole seconds
nanos (int) –

Nanoseconds remainder (0 <= nanos < 1_000_000_000)

secs `instance-attribute` ⚓︎

secs: int

Whole seconds

nanos `instance-attribute` ⚓︎

nanos: int

Nanoseconds remainder (0 <= nanos < 1_000_000_000)

HrTime ⚓︎

Bases: _ShellfishBaseModel

High resolution time split into whole seconds and nanoseconds

Examples:

>>> HrTime.from_seconds(1.5)
HrTime(secs=1, nanos=500000000)
>>> HrTime.from_seconds(1.5).hrdt_dict()
{'secs': 1, 'nanos': 500000000}

Methods:

from_seconds –

Return HrTime object from seconds
hrdt_dict –

Return this HrTime as a typed-dict

Attributes:

secs (int) –

Whole seconds
nanos (int) –

Nanoseconds remainder (0 <= nanos < 1_000_000_000)
sec (int) –

Deprecated alias for secs
ns (int) –

Deprecated alias for nanos

secs `class-attribute` `instance-attribute` ⚓︎

secs: int = Field(
    validation_alias=AliasChoices("sec", "secs", "s")
)

Whole seconds

nanos `class-attribute` `instance-attribute` ⚓︎

nanos: int = Field(
    validation_alias=AliasChoices("ns", "nsecs", "nanos")
)

Nanoseconds remainder (0 <= nanos < 1_000_000_000)

sec `property` ⚓︎

sec: int

Deprecated alias for secs

ns `property` ⚓︎

ns: int

Deprecated alias for nanos

from_seconds `classmethod` ⚓︎

from_seconds(seconds: float) -> HrTime

Return HrTime object from seconds

Parameters:

seconds ⚓︎
(float) –

number of seconds

Returns:

HrTime –

HrTime object for the given number of seconds

hrdt_dict ⚓︎

hrdt_dict() -> HrTimeDict

Return this HrTime as a typed-dict

DoneError ⚓︎

DoneError(done: Done)

Bases: SubprocessError

Error raised when a process returns a non-zero/not-ok exit status

Raised by Done.check.

Examples:

>>> done = Done(
...     args=["sh", "-c", "exit 1"],
...     returncode=1,
...     stdout="",
...     stderr="uh oh\n",
...     ti=0.0,
...     tf=0.1,
...     dt=0.1,
... )
>>> try:
...     done.check()
... except DoneError as e:
...     (e.returncode, e.cmd, e.stderr)
(1, ['sh', '-c', 'exit 1'], 'uh oh\n')

Parameters:

done ⚓︎
(Done) –

Done object with a non-zero/not-ok returncode

Methods:

error_msg –

Return the error message string for this error's returncode

Attributes:

returncode (int) –

Exit status of the process
cmd (list[str]) –

Command args the process was run with
stderr (str) –

Standard error (stderr) of the process
stdout (str) –

Standard output (stdout) of the process
done (Done) –

The Done object that produced this error
output (str) –

Alias for stdout; mirrors subprocess.CalledProcessError.output

returncode `instance-attribute` ⚓︎

returncode: int = done.returncode

Exit status of the process

cmd `instance-attribute` ⚓︎

cmd: list[str] = done.args

Command args the process was run with

stderr `instance-attribute` ⚓︎

stderr: str = done.stderr

Standard error (stderr) of the process

stdout `instance-attribute` ⚓︎

stdout: str = done.stdout

Standard output (stdout) of the process

done `instance-attribute` ⚓︎

done: Done = done

The Done object that produced this error

output `property` `writable` ⚓︎

output: str

Alias for stdout; mirrors subprocess.CalledProcessError.output

error_msg ⚓︎

error_msg() -> str

Return the error message string for this error's returncode

DoneDict ⚓︎

Bases: TypedDict

Completed subprocess as a typed-dict; see Done

Attributes:

args (list[str]) –

Command args the process was run with
returncode (int) –

Exit status of the process
stdout (str) –

Standard output (stdout) of the process
stderr (str) –

Standard error (stderr) of the process
ti (float) –

Time the process started (seconds since epoch)
tf (float) –

Time the process finished (seconds since epoch)
dt (float) –

Time the process took to run (seconds; tf - ti)
hrdt (HrTimeDict | None) –

High resolution dt, if the runner provided one
stdin (str | None) –

Standard input (stdin) written to the process, if any
async_proc (bool) –

True if the process was run asynchronously
verbose (bool) –

True if stdout/stderr were echoed to the parent process' stdout/stderr

args `instance-attribute` ⚓︎

args: list[str]

Command args the process was run with

returncode `instance-attribute` ⚓︎

returncode: int

Exit status of the process

stdout `instance-attribute` ⚓︎

stdout: str

Standard output (stdout) of the process

stderr `instance-attribute` ⚓︎

stderr: str

Standard error (stderr) of the process

ti `instance-attribute` ⚓︎

ti: float

Time the process started (seconds since epoch)

tf `instance-attribute` ⚓︎

tf: float

Time the process finished (seconds since epoch)

dt `instance-attribute` ⚓︎

dt: float

Time the process took to run (seconds; tf - ti)

hrdt `instance-attribute` ⚓︎

hrdt: HrTimeDict | None

High resolution dt, if the runner provided one

stdin `instance-attribute` ⚓︎

stdin: str | None

Standard input (stdin) written to the process, if any

async_proc `instance-attribute` ⚓︎

async_proc: bool

True if the process was run asynchronously

verbose `instance-attribute` ⚓︎

verbose: bool

True if stdout/stderr were echoed to the parent process' stdout/stderr

Done ⚓︎

Bases: _ShellfishBaseModel

Completed subprocess

Returned by shellfish.sh.do (and friends) once a process has finished.

Examples:

>>> done = Done(
...     args=["echo", "hello"],
...     returncode=0,
...     stdout="hello\nworld\n",
...     stderr="",
...     ti=0.0,
...     tf=0.5,
...     dt=0.5,
... )
>>> done.returncode
0
>>> done.lines
['hello', 'world']
>>> done.grep("world")
['world']
>>> done.check()  # does not raise; returncode is 0

Methods:

model_post_init –

Pydantic post-init hook; defers to __post_init__
hrdt_dict –

Return the high resolution run-time as a typed-dict
stdout_lines –

Return stdout split into lines
stderr_lines –

Return stderr split into lines
done_dict –

Return Done object as typed-dict
check –

Check returncode and stderr
sys_print –

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

Write stdout as a string to a fspath
completed_process –

Return subprocess.CompletedProcess object
write_stderr –

Write stderr as a string to a fspath
json_parse_stdout –

Return json parsed stdout
json_parse_stderr –

Return json parsed stderr
json_parse –

Return json parsed stdout (or stderr)
parse_json –

Alias for json_parse
grep –

Return lines in stdout that contain the given string

Attributes:

args (list[str]) –

Command args the process was run with
returncode (int) –

Exit status of the process
stdout (str) –

Standard output (stdout) of the process
stderr (str) –

Standard error (stderr) of the process
ti (float) –

Time the process started (seconds since epoch)
tf (float) –

Time the process finished (seconds since epoch)
dt (float) –

Time the process took to run (seconds; tf - ti)
hrdt (HrTime | None) –

High resolution dt, if the runner provided one
stdin (str | None) –

Standard input (stdin) written to the process, if any
async_proc (bool) –

True if the process was run asynchronously
dryrun (bool) –

True if the process was not actually run (dryrun)
verbose (bool) –

Echo stdout/stderr to the parent process on init; excluded from dumps
lines (list[str]) –

Stdout split into lines without line-endings

args `instance-attribute` ⚓︎

args: list[str]

Command args the process was run with

returncode `instance-attribute` ⚓︎

returncode: int

Exit status of the process

stdout `instance-attribute` ⚓︎

stdout: str

Standard output (stdout) of the process

stderr `instance-attribute` ⚓︎

stderr: str

Standard error (stderr) of the process

ti `instance-attribute` ⚓︎

ti: float

Time the process started (seconds since epoch)

tf `instance-attribute` ⚓︎

tf: float

Time the process finished (seconds since epoch)

dt `instance-attribute` ⚓︎

dt: float

Time the process took to run (seconds; tf - ti)

hrdt `class-attribute` `instance-attribute` ⚓︎

hrdt: HrTime | None = None

High resolution dt, if the runner provided one

stdin `class-attribute` `instance-attribute` ⚓︎

stdin: str | None = None

Standard input (stdin) written to the process, if any

async_proc `class-attribute` `instance-attribute` ⚓︎

async_proc: bool = False

True if the process was run asynchronously

dryrun `class-attribute` `instance-attribute` ⚓︎

dryrun: bool = Field(False)

True if the process was not actually run (dryrun)

verbose `class-attribute` `instance-attribute` ⚓︎

verbose: bool = Field(False, exclude=True)

Echo stdout/stderr to the parent process on init; excluded from dumps

lines `property` ⚓︎

lines: list[str]

Stdout split into lines without line-endings

model_post_init ⚓︎

model_post_init(_context: Any) -> None

Pydantic post-init hook; defers to __post_init__

hrdt_dict ⚓︎

hrdt_dict() -> HrTimeDict

Return the high resolution run-time as a typed-dict

Falls back to converting dt to HrTime when the runner did not provide an hrdt.

stdout_lines ⚓︎

stdout_lines(*, keepends: bool = False) -> list[str]

Return stdout split into lines

Parameters:

keepends ⚓︎
(bool, default: False ) –

Keep the line-ending characters on each line

Returns:

list[str] –

List of stdout lines

stderr_lines ⚓︎

stderr_lines(*, keepends: bool = False) -> list[str]

Return stderr split into lines

Parameters:

keepends ⚓︎
(bool, default: False ) –

Keep the line-ending characters on each line

Returns:

list[str] –

List of stderr lines

done_dict ⚓︎

done_dict() -> DoneDict

Return Done object as typed-dict

check ⚓︎

check(
    ok_code: int
    | list[int]
    | tuple[int, ...]
    | set[int] = 0,
) -> None

Check returncode and stderr

Parameters:

ok_code ⚓︎
(int | list[int] | tuple[int, ...] | set[int], default: 0 ) –

Return code (or collection of return codes) considered ok

Raises:

DoneError –

If the return code is not ok

sys_print ⚓︎

sys_print() -> None

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

write_stdout ⚓︎

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

Write stdout as a string to a fspath

Parameters:

filepath ⚓︎
(FsPath) –

Filepath to write stdout to
append ⚓︎
(bool, default: False ) –

Append to the file instead of overwriting it

completed_process ⚓︎

completed_process() -> CompletedProcess[str]

Return subprocess.CompletedProcess object

write_stderr ⚓︎

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

Write stderr as a string to a fspath

Parameters:

filepath ⚓︎
(FsPath) –

Filepath of location to write stderr
append ⚓︎
(bool, default: False ) –

Append to the file instead of overwriting it

json_parse_stdout ⚓︎

json_parse_stdout(
    *,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any

Return json parsed stdout

Parameters:

jsonc ⚓︎
(bool, default: False ) –

Parse stdout as jsonc (json with comments)
jsonl ⚓︎
(bool, default: False ) –

Parse stdout as jsonl (json-lines)
ndjson ⚓︎
(bool, default: False ) –

Parse stdout as ndjson (newline delimited json)

Returns:

Any –

The parsed stdout

json_parse_stderr ⚓︎

json_parse_stderr(
    *,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any

Return json parsed stderr

Parameters:

jsonc ⚓︎
(bool, default: False ) –

Parse stderr as jsonc (json with comments)
jsonl ⚓︎
(bool, default: False ) –

Parse stderr as jsonl (json-lines)
ndjson ⚓︎
(bool, default: False ) –

Parse stderr as ndjson (newline delimited json)

Returns:

Any –

The parsed stderr

json_parse ⚓︎

json_parse(
    *,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any

Return json parsed stdout (or stderr)

Parameters:

stderr ⚓︎
(bool, default: False ) –

Parse stderr instead of stdout
jsonc ⚓︎
(bool, default: False ) –

Parse as jsonc (json with comments)
jsonl ⚓︎
(bool, default: False ) –

Parse as jsonl (json-lines)
ndjson ⚓︎
(bool, default: False ) –

Parse as ndjson (newline delimited json)

Returns:

Any –

The parsed stdout, or the parsed stderr if stderr is True

parse_json ⚓︎

parse_json(
    *,
    stderr: bool = False,
    jsonc: bool = False,
    jsonl: bool = False,
    ndjson: bool = False,
) -> Any

Alias for json_parse

(bc I keep flip-flopping the fn name)

Parameters:

stderr ⚓︎
(bool, default: False ) –

Parse stderr instead of stdout
jsonc ⚓︎
(bool, default: False ) –

Parse as jsonc (json with comments)
jsonl ⚓︎
(bool, default: False ) –

Parse as jsonl (json-lines)
ndjson ⚓︎
(bool, default: False ) –

Parse as ndjson (newline delimited json)

Returns:

Any –

The parsed stdout, or the parsed stderr if stderr is True

grep ⚓︎

grep(string: str) -> list[str]

Return lines in stdout that contain the given string

Parameters:

string ⚓︎
(str) –

String to search for

Returns:

list[str] –

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

done ⚓︎

HrTimeDict ⚓︎

secs instance-attribute ⚓︎

nanos instance-attribute ⚓︎

HrTime ⚓︎

secs class-attribute instance-attribute ⚓︎

nanos class-attribute instance-attribute ⚓︎

sec property ⚓︎

ns property ⚓︎

from_seconds classmethod ⚓︎

seconds ⚓︎

hrdt_dict ⚓︎

DoneError ⚓︎

done ⚓︎

returncode instance-attribute ⚓︎

cmd instance-attribute ⚓︎

stderr instance-attribute ⚓︎

stdout instance-attribute ⚓︎

done instance-attribute ⚓︎

output property writable ⚓︎

error_msg ⚓︎

DoneDict ⚓︎

args instance-attribute ⚓︎

returncode instance-attribute ⚓︎

stdout instance-attribute ⚓︎

stderr instance-attribute ⚓︎

ti instance-attribute ⚓︎

tf instance-attribute ⚓︎

dt instance-attribute ⚓︎

hrdt instance-attribute ⚓︎

stdin instance-attribute ⚓︎

async_proc instance-attribute ⚓︎

verbose instance-attribute ⚓︎

Done ⚓︎

args instance-attribute ⚓︎

returncode instance-attribute ⚓︎

stdout instance-attribute ⚓︎

stderr instance-attribute ⚓︎

ti instance-attribute ⚓︎

tf instance-attribute ⚓︎

dt instance-attribute ⚓︎

hrdt class-attribute instance-attribute ⚓︎

stdin class-attribute instance-attribute ⚓︎

async_proc class-attribute instance-attribute ⚓︎

dryrun class-attribute instance-attribute ⚓︎

verbose class-attribute instance-attribute ⚓︎

lines property ⚓︎

model_post_init ⚓︎

hrdt_dict ⚓︎

stdout_lines ⚓︎

keepends ⚓︎

stderr_lines ⚓︎

keepends ⚓︎

done_dict ⚓︎

check ⚓︎

ok_code ⚓︎

sys_print ⚓︎

write_stdout ⚓︎

filepath ⚓︎

append ⚓︎

completed_process ⚓︎

write_stderr ⚓︎

filepath ⚓︎

append ⚓︎

json_parse_stdout ⚓︎

jsonc ⚓︎

jsonl ⚓︎

ndjson ⚓︎

json_parse_stderr ⚓︎

jsonc ⚓︎

jsonl ⚓︎

ndjson ⚓︎

json_parse ⚓︎

stderr ⚓︎

jsonc ⚓︎

jsonl ⚓︎

ndjson ⚓︎

parse_json ⚓︎

stderr ⚓︎

jsonc ⚓︎

secs `instance-attribute` ⚓︎

nanos `instance-attribute` ⚓︎

secs `class-attribute` `instance-attribute` ⚓︎

nanos `class-attribute` `instance-attribute` ⚓︎

sec `property` ⚓︎

ns `property` ⚓︎

from_seconds `classmethod` ⚓︎

`seconds` ⚓︎

`done` ⚓︎

returncode `instance-attribute` ⚓︎

cmd `instance-attribute` ⚓︎

stderr `instance-attribute` ⚓︎

stdout `instance-attribute` ⚓︎

done `instance-attribute` ⚓︎

output `property` `writable` ⚓︎

args `instance-attribute` ⚓︎

returncode `instance-attribute` ⚓︎

stdout `instance-attribute` ⚓︎

stderr `instance-attribute` ⚓︎

ti `instance-attribute` ⚓︎

tf `instance-attribute` ⚓︎

dt `instance-attribute` ⚓︎

hrdt `instance-attribute` ⚓︎

stdin `instance-attribute` ⚓︎

async_proc `instance-attribute` ⚓︎

verbose `instance-attribute` ⚓︎

args `instance-attribute` ⚓︎

returncode `instance-attribute` ⚓︎

stdout `instance-attribute` ⚓︎

stderr `instance-attribute` ⚓︎

ti `instance-attribute` ⚓︎

tf `instance-attribute` ⚓︎

dt `instance-attribute` ⚓︎

hrdt `class-attribute` `instance-attribute` ⚓︎

stdin `class-attribute` `instance-attribute` ⚓︎

async_proc `class-attribute` `instance-attribute` ⚓︎

dryrun `class-attribute` `instance-attribute` ⚓︎

verbose `class-attribute` `instance-attribute` ⚓︎

lines `property` ⚓︎

`keepends` ⚓︎

`keepends` ⚓︎

`ok_code` ⚓︎

`filepath` ⚓︎

`append` ⚓︎

`filepath` ⚓︎

`append` ⚓︎

`jsonc` ⚓︎

`jsonl` ⚓︎

`ndjson` ⚓︎

`jsonc` ⚓︎

`jsonl` ⚓︎

`ndjson` ⚓︎

`stderr` ⚓︎

`jsonc` ⚓︎

`jsonl` ⚓︎

`ndjson` ⚓︎

`stderr` ⚓︎

`jsonc` ⚓︎

`jsonl` ⚓︎

`ndjson` ⚓︎

`string` ⚓︎