popoto.transfer.cli¶
popoto.transfer.cli
¶
popoto-transfer -- a CLI front-end for :mod:popoto.transfer.
Two subcommands:
export
Wraps :func:popoto.transfer.export_records. Writes JSON Lines to
--out (a file, or - for stdout) and a human summary to stderr.
import
Wraps :func:popoto.transfer.import_records. Reads JSON Lines from
--in (a file, or - for stdin) and prints the reconciliation
report to stderr.
Both subcommands refuse to touch Redis database 0 unless --allow-db0 is
passed. Database 0 is, on many machines running this ORM, a live store rather
than a test database, and an import writes to it. The guard reads the
database off the live connection pool -- not an environment variable -- so it
catches the unset-REDIS_URL fallback as well as an explicit …/0 URL.
The refusal applies to transfers that use Redis. A model bound to another
backend (Meta.backend = "postgres", or POPOTO_BACKEND=postgres) is
transferred without --allow-db0, because the transfer never contacts
Redis. That is enforced rather than assumed: on every run without
--allow-db0, whatever database the process started on, from before the
--model module is imported until the run ends, the Redis connection pool
refuses to hand out a connection to database 0 (a pipeline included), so any
Redis command the model module or the transfer would issue against database 0
is refused before it reaches the server. A Redis-bound model is refused once
it is resolved, before its first command, if the global client is bound to
database 0 at that moment -- so a --model module that rebinds the client
to database 0 is refused, and one that rebinds it away from database 0 is not.
Known residual: a model module that builds its own database-0 client while
the global client stays elsewhere is refused only at that client's first
checkout; if that happens mid-transfer the refusal carries the "partway"
warning.
The human-readable summary always goes to stderr, never stdout, so that
--out - can stream JSON Lines on stdout without the summary corrupting
it: popoto-transfer export --model pkg.mod:Model --out - | gzip > b.gz
still shows the operator a summary on their terminal. --json claims
stdout for a machine-readable summary instead, and is refused together with
--out - since both would write to stdout.
Submodule imports (redis, the transfer drivers, the model registry) are
kept out of module scope and inside the functions that need them, so argument
parsing and the database-0 fence run before any of them is touched. This does
not make --help cheap: the console-script entry point imports
popoto.transfer.cli, which imports the popoto package, so the ORM is
already resolved by the time :func:main is called.
CLIError
¶
Bases: Exception
A diagnosed, user-facing CLI failure.
Raised by :func:resolve_model and the flag-validation helpers. Callers
catch it, print str(exc) to stderr, and return exit code 1 -- never a
traceback.
build_parser()
¶
Construct the argument parser.
Returns:
| Type | Description |
|---|---|
ArgumentParser
|
The configured :class: |
ArgumentParser
|
the strings |
ArgumentParser
|
keyword, so dispatch in :func: |
ArgumentParser
|
than an attribute named |
Source code in src/popoto/transfer/cli.py
88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 | |
resolve_model(spec)
¶
Resolve a "module.path:ClassName" spec into a Model subclass.
Prepends the current working directory to sys.path first, since a
console script does not get the CWD on sys.path the way
python -m does, and the single most likely first invocation is from
the operator's own project root.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
spec
|
str
|
A colon-separated model spec, e.g. |
required |
Returns:
| Type | Description |
|---|---|
Any
|
The resolved :class: |
Raises:
| Type | Description |
|---|---|
CLIError
|
If |
Source code in src/popoto/transfer/cli.py
main(argv=None)
¶
Entry point for the popoto-transfer console script.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
argv
|
Optional[List[str]]
|
Argument list, defaulting to |
None
|
Returns:
| Type | Description |
|---|---|
int
|
A process exit code: |
int
|
failure (bad |
int
|
file, a manifest mismatch, a query error, a connection error, or an |
int
|
|
int
|
records before raising), |
int
|
own convention), or |
int
|
record did not land (any |
int
|
import outcome, or any export error; a |
int
|
clean and does not trigger this). |