Command-line interface

Installing the package puts a mypackage executable on your PATH via the [project.scripts] entry point:

[project.scripts]
mypackage = "mypackage.cli:main"

It is built on argparse from the standard library, so the package still declares zero runtime dependencies.

mypackage --help
mypackage --version

summarize¶

Print descriptive statistics for a series of numbers.

mypackage summarize [PATH] [--ddof N] [--json]

PATH is a file of whitespace- or comma-separated numbers, or - (the default) to read standard input. Every value must be finite: nan and inf are rejected, because a summary of them is meaningless and --json could not represent them in standard JSON.

$ echo "1 2 3 4 5" | mypackage summarize
count                  5
ddof                   1
maximum                5
mean                   3
median                 3
minimum                1
spread                 4
std              1.58114
variance             2.5

$ echo "1 2 3 4 5" | mypackage summarize --json
{
  "count": 5,
  "ddof": 1,
  "maximum": 5.0,
  "mean": 3.0,
  "median": 3.0,
  "minimum": 1.0,
  "spread": 4.0,
  "std": 1.5811388300841898,
  "variance": 2.5
}

$ mypackage summarize measurements.txt --ddof 0

smooth¶

Apply a smoothing filter and print one value per line.

mypackage smooth [PATH] [--method {mean,median,ewma}] [--window N]
                        [--alpha A] [--padding STRATEGY] [--precision D]

$ printf "1 1 99 1 1" | mypackage smooth --method median --window 3 --precision 1
1.0
1.0
1.0
1.0
1.0

With --padding none the output is window - 1 samples shorter:

$ echo "1 2 3 4 5" | mypackage smooth --padding none --precision 1
2.0
3.0
4.0

Exit codes¶

Errors go to standard error, prefixed with error: , leaving standard output clean for pipes:

$ echo "1 2 banana" | mypackage summarize
error: 'input' must contain only numbers, got 'banana' at index 2
$ echo $?
1

Testing a CLI¶

main accepts its streams as arguments and returns an exit status rather than calling sys.exit. That is what makes the whole CLI testable in-process, with no subprocess and no monkeypatching:

import io

from mypackage.cli import main

out = io.StringIO()
status = main(["summarize", "-", "--json"], out=out, stdin=io.StringIO("1 2 3 4"))

status                                 # 0
json.loads(out.getvalue())["mean"]     # 2.5

build_parser is exposed separately so tests and documentation tooling can introspect the argument structure without running anything.

API¶

Full signatures live in the CLI API reference.