fivetran-cli 1.0.0__tar.gz → 1.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/PKG-INFO +1 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/__init__.py +105 -36
- fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/args.py +131 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/base.py +66 -15
- fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/reserved_flags.py +62 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/parser/__init__.py +5 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/parser/builder.py +4 -5
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/certificate.py +2 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connection.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connector_metadata.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connector_sdk_package.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/destination.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/fingerprint.py +2 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/group.py +3 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/hybrid_deployment_agent.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/log_service.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/private_link.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/proxy_agent.py +2 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/role.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/system_key.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/team.py +4 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/transformation.py +2 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/transformation_project.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/user.py +3 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/webhook.py +1 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/constants.py +10 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/_formatters.py +1 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/error_output.py +20 -68
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/output.py +1 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/client.py +231 -28
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/config.py +1 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/exceptions.py +11 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/plugin_api.py +4 -0
- fivetran_cli-1.1.0/src/fivetran_cli/telemetry_helper.py +147 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/PKG-INFO +1 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/SOURCES.txt +7 -2
- fivetran_cli-1.1.0/src/fivetran_cli.egg-info/top_level.txt +2 -0
- fivetran_cli-1.1.0/src/fivetran_cli_telemetry/__init__.py +3 -0
- fivetran_cli-1.1.0/src/fivetran_cli_telemetry/_sender.py +34 -0
- fivetran_cli-1.1.0/src/fivetran_cli_telemetry/telemetry.py +343 -0
- fivetran_cli-1.0.0/src/fivetran_cli/cli_utils/parser/args.py +0 -61
- fivetran_cli-1.0.0/src/fivetran_cli.egg-info/top_level.txt +0 -1
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/README.md +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/pyproject.toml +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/setup.cfg +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_parser.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/__init__.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/timeout.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/__init__.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/account.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connection_schema.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/public_connector.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/_renderers.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/views.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/__init__.py +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/dependency_links.txt +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/entry_points.txt +0 -0
- {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/requires.txt +0 -0
|
@@ -4,56 +4,105 @@ import argparse
|
|
|
4
4
|
import contextlib
|
|
5
5
|
import os
|
|
6
6
|
import sys
|
|
7
|
+
import time
|
|
7
8
|
from pathlib import Path
|
|
8
9
|
from typing import Sequence, TextIO
|
|
9
10
|
|
|
10
|
-
|
|
11
|
+
# Version format: <major_version>.<minor_version>.<patch_version>
|
|
12
|
+
# (where Major Version = 1, Minor Version is incremental MM from Sep 26 onwards, Patch Version is incremental within a month)
|
|
13
|
+
__version__ = "1.1.0"
|
|
11
14
|
|
|
15
|
+
from fivetran_cli import telemetry_helper
|
|
12
16
|
from fivetran_cli.cli_utils.dispatch.timeout import cancel_command_timeout, command_timed_out, install_command_timeout
|
|
13
|
-
from fivetran_cli.cli_utils.parser import build_parser, validate_fields
|
|
17
|
+
from fivetran_cli.cli_utils.parser import build_parser, resolve_output_format, validate_fields, validate_filters
|
|
14
18
|
from fivetran_cli.cli_parser import discover_plugins, first_command_token
|
|
15
19
|
from fivetran_cli.constants import COMMAND_TIMEOUT, FIVETRAN_CLI_COMMANDS, UNKNOWN_FIELDS_ERROR_PREFIX
|
|
16
20
|
from fivetran_cli.display.error_output import emit_error
|
|
17
21
|
from fivetran_cli.display.output import emit_output, emit_raw_json, ensure_writable_parent
|
|
18
22
|
from fivetran_cli.http.client import FivetranClient
|
|
19
23
|
from fivetran_cli.http.config import resolve_config, require_api_key
|
|
20
|
-
from fivetran_cli.http.exceptions import FivetranCliError, FivetranPartialResultError
|
|
24
|
+
from fivetran_cli.http.exceptions import FivetranCliError, FivetranPartialResultError, extract_api_error
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _configure_stdio_encoding() -> None:
|
|
28
|
+
"""Force UTF-8 on stdout/stderr so non-ASCII output can't crash the CLI
|
|
29
|
+
under a non-UTF-8 locale (e.g. Windows, LANG=C)."""
|
|
30
|
+
for stream in (sys.stdout, sys.stderr):
|
|
31
|
+
if hasattr(stream, "reconfigure"):
|
|
32
|
+
stream.reconfigure(encoding="utf-8", errors="replace")
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _telemetry_exit_code(exc: BaseException, *, fallback: int = 1) -> int:
|
|
36
|
+
"""Numeric code for telemetry: API error's status_code, KeyboardInterrupt's
|
|
37
|
+
conventional shell code (128 + SIGINT), SystemExit's own numeric code, or
|
|
38
|
+
`fallback` for anything else."""
|
|
39
|
+
api_error = extract_api_error(exc)
|
|
40
|
+
if api_error is not None:
|
|
41
|
+
return api_error.status_code
|
|
42
|
+
if isinstance(exc, KeyboardInterrupt):
|
|
43
|
+
return 130
|
|
44
|
+
if isinstance(exc, SystemExit) and isinstance(exc.code, int):
|
|
45
|
+
return exc.code
|
|
46
|
+
return fallback
|
|
21
47
|
|
|
22
48
|
|
|
23
49
|
def main(argv: Sequence[str] | None = None) -> int:
|
|
50
|
+
_configure_stdio_encoding()
|
|
24
51
|
return run(list(argv) if argv is not None else sys.argv[1:])
|
|
25
52
|
|
|
26
53
|
|
|
27
54
|
def run(argv: list[str], *, stdout: TextIO = sys.stdout, stderr: TextIO = sys.stderr) -> int:
|
|
28
55
|
parser = build_parser()
|
|
56
|
+
start_time = time.perf_counter()
|
|
57
|
+
|
|
58
|
+
# telemetry notice is emitted via sys.stderr by the shared module, so
|
|
59
|
+
# redirect it here to honor run() caller-provided stderr.
|
|
60
|
+
with contextlib.redirect_stderr(stderr):
|
|
61
|
+
telemetry_helper.show_notice_if_needed()
|
|
29
62
|
|
|
30
|
-
early_exit_code = _handle_early_dispatch(argv, parser, stdout)
|
|
63
|
+
early_exit_code = _handle_early_dispatch(argv, parser, stdout, start_time)
|
|
31
64
|
if early_exit_code is not None:
|
|
32
65
|
return early_exit_code
|
|
33
66
|
|
|
34
|
-
args,
|
|
35
|
-
if
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
flag_exit_code = _validate_prompt_flags(args, stderr)
|
|
39
|
-
if flag_exit_code is not None:
|
|
40
|
-
return flag_exit_code
|
|
67
|
+
args, process_exit_code, telemetry_exit_code = _parse_arguments(argv, parser, stdout, stderr, start_time)
|
|
68
|
+
if process_exit_code is not None:
|
|
69
|
+
telemetry_helper.record_cli_usage(argv, parser, telemetry_exit_code, time.perf_counter() - start_time)
|
|
70
|
+
return process_exit_code
|
|
41
71
|
|
|
42
72
|
if not hasattr(args, "handler"):
|
|
43
73
|
parser.print_help(stdout)
|
|
44
|
-
|
|
74
|
+
telemetry_helper.record_cli_usage(argv, parser, 1, time.perf_counter() - start_time)
|
|
75
|
+
return 1
|
|
76
|
+
|
|
77
|
+
process_exit_code, telemetry_exit_code = _execute_command(args, stdout, stderr)
|
|
78
|
+
telemetry_helper.record_cli_usage(
|
|
79
|
+
argv, parser, telemetry_exit_code, time.perf_counter() - start_time,
|
|
80
|
+
output_format=resolve_output_format(args),
|
|
81
|
+
)
|
|
82
|
+
return process_exit_code
|
|
83
|
+
|
|
45
84
|
|
|
46
|
-
|
|
85
|
+
def _resolve_plugin_cli_tool(target) -> str:
|
|
86
|
+
"""Return the plugin's self-reported telemetry name, falling back to its
|
|
87
|
+
registered entry-point name if it doesn't implement the hook, the hook
|
|
88
|
+
isn't callable, calling it raises, or it returns None."""
|
|
89
|
+
try:
|
|
90
|
+
plugin_cli_tool = target.plugin.get_cli_tool_name_for_telemetry()
|
|
91
|
+
return plugin_cli_tool if plugin_cli_tool is not None else target.plugin_name
|
|
92
|
+
except Exception:
|
|
93
|
+
return target.plugin_name
|
|
47
94
|
|
|
48
95
|
|
|
49
96
|
def _handle_early_dispatch(
|
|
50
97
|
argv: list[str],
|
|
51
98
|
parser: argparse.ArgumentParser,
|
|
52
99
|
stdout: TextIO,
|
|
100
|
+
start_time: float,
|
|
53
101
|
) -> int | None:
|
|
54
102
|
"""Handles help requests, version checks, and third-party plugin dispatch."""
|
|
55
103
|
if not argv or (len(argv) == 1 and argv[0] in {"-h", "--help", "help"}):
|
|
56
104
|
parser.print_help(stdout)
|
|
105
|
+
telemetry_helper.record_cli_usage(argv, parser, 0, time.perf_counter() - start_time)
|
|
57
106
|
return 0
|
|
58
107
|
|
|
59
108
|
if argv == ["version"]:
|
|
@@ -63,6 +112,7 @@ def _handle_early_dispatch(
|
|
|
63
112
|
)
|
|
64
113
|
if version_action is not None:
|
|
65
114
|
stdout.write(version_action.version + "\n")
|
|
115
|
+
telemetry_helper.record_cli_usage(argv, parser, 0, time.perf_counter() - start_time)
|
|
66
116
|
return 0
|
|
67
117
|
|
|
68
118
|
first_positional = first_command_token(argv)
|
|
@@ -70,6 +120,8 @@ def _handle_early_dispatch(
|
|
|
70
120
|
plugins = discover_plugins()
|
|
71
121
|
target = plugins.get(first_positional)
|
|
72
122
|
if target is not None:
|
|
123
|
+
plugin_cli_tool = _resolve_plugin_cli_tool(target)
|
|
124
|
+
telemetry_helper.record_plugin_dispatch(first_positional, plugin_cli_tool)
|
|
73
125
|
result = target.plugin.dispatch(argv)
|
|
74
126
|
return result if isinstance(result, int) else 0
|
|
75
127
|
|
|
@@ -81,47 +133,64 @@ def _parse_arguments(
|
|
|
81
133
|
parser: argparse.ArgumentParser,
|
|
82
134
|
stdout: TextIO,
|
|
83
135
|
stderr: TextIO,
|
|
84
|
-
|
|
85
|
-
|
|
136
|
+
start_time: float,
|
|
137
|
+
) -> tuple[argparse.Namespace | None, int | None, int | None]:
|
|
138
|
+
"""Parses CLI arguments. Returns (args, process_exit_code,
|
|
139
|
+
telemetry_exit_code) — see _execute_command for why there are two
|
|
140
|
+
distinct exit codes."""
|
|
86
141
|
try:
|
|
87
142
|
# argparse writes help/usage to process-global stdio, so redirect here
|
|
88
143
|
# to honor run() caller-provided output streams.
|
|
89
144
|
with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
|
|
90
|
-
return parser.parse_args(argv), None
|
|
145
|
+
return parser.parse_args(argv), None, None
|
|
91
146
|
except SystemExit as exc:
|
|
92
147
|
if exc.code == 0:
|
|
148
|
+
# Nested -h/--help (e.g. `beta connection list --help`) exits
|
|
149
|
+
# here — record it now, since run() never reaches its own
|
|
150
|
+
# telemetry call afterward.
|
|
151
|
+
telemetry_helper.record_cli_usage(argv, parser, 0, time.perf_counter() - start_time)
|
|
93
152
|
raise
|
|
94
|
-
|
|
153
|
+
# The process still exits 1 (our 0/1 exit-code contract), but
|
|
154
|
+
# telemetry's own exit_code field carries the original, more specific
|
|
155
|
+
# numeric SystemExit code argparse chose instead.
|
|
156
|
+
return None, 1, _telemetry_exit_code(exc)
|
|
95
157
|
|
|
96
158
|
|
|
97
|
-
def _validate_prompt_flags(args: argparse.Namespace
|
|
98
|
-
"""
|
|
159
|
+
def _validate_prompt_flags(args: argparse.Namespace) -> None:
|
|
160
|
+
"""Raise if conflicting prompt flags (--yes and --non-interactive) are
|
|
161
|
+
both set."""
|
|
99
162
|
if getattr(args, "yes", False) and getattr(args, "non_interactive", False):
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
163
|
+
raise FivetranCliError("--yes and --non-interactive cannot be used together.")
|
|
164
|
+
|
|
165
|
+
|
|
166
|
+
def _validate_flags_before_execution(args: argparse.Namespace) -> None:
|
|
167
|
+
"""Fail fast on bad input BEFORE invoking the handler, so it's reported
|
|
168
|
+
before any API call."""
|
|
169
|
+
_validate_prompt_flags(args)
|
|
170
|
+
_validate_output_destination(args)
|
|
171
|
+
validate_fields(args)
|
|
172
|
+
validate_filters(args)
|
|
103
173
|
|
|
104
174
|
|
|
105
175
|
def _execute_command(
|
|
106
176
|
args: argparse.Namespace,
|
|
107
177
|
stdout: TextIO,
|
|
108
178
|
stderr: TextIO,
|
|
109
|
-
) -> int:
|
|
110
|
-
"""Configures the client, invokes the command handler, and emits formatted
|
|
179
|
+
) -> tuple[int, int]:
|
|
180
|
+
"""Configures the client, invokes the command handler, and emits formatted
|
|
181
|
+
output. Returns (process_exit_code, telemetry_exit_code): the process
|
|
182
|
+
always exits 0/1 (our fixed exit-code contract), but telemetry's own
|
|
183
|
+
exit_code field carries richer numeric detail when available (e.g. the
|
|
184
|
+
API's HTTP status_code) instead of a generic 1 — see _telemetry_exit_code."""
|
|
111
185
|
operation_completed = False
|
|
112
186
|
payload = None
|
|
113
187
|
client: FivetranClient | None = None
|
|
114
188
|
try:
|
|
189
|
+
_validate_flags_before_execution(args)
|
|
115
190
|
config = resolve_config(args)
|
|
116
191
|
require_api_key(config)
|
|
117
192
|
client = FivetranClient(config, stderr=stderr)
|
|
118
193
|
|
|
119
|
-
# Fail fast on an unwritable --output-file or an invalid --fields
|
|
120
|
-
# value BEFORE invoking the handler, so bad input is reported before
|
|
121
|
-
# any mutating API call.
|
|
122
|
-
_validate_output_destination(args)
|
|
123
|
-
validate_fields(args)
|
|
124
|
-
|
|
125
194
|
install_command_timeout(COMMAND_TIMEOUT, stderr)
|
|
126
195
|
|
|
127
196
|
args._stdout = stdout
|
|
@@ -131,14 +200,14 @@ def _execute_command(
|
|
|
131
200
|
payload = args.handler(args, client)
|
|
132
201
|
operation_completed = True
|
|
133
202
|
emit_output(payload, args=args, stdout=stdout)
|
|
134
|
-
return 0
|
|
203
|
+
return 0, 0
|
|
135
204
|
finally:
|
|
136
205
|
cancel_command_timeout()
|
|
137
206
|
|
|
138
|
-
except KeyboardInterrupt:
|
|
207
|
+
except KeyboardInterrupt as exc:
|
|
139
208
|
if not command_timed_out():
|
|
140
209
|
stderr.write("\nfivetran: interrupted\n")
|
|
141
|
-
return 1
|
|
210
|
+
return 1, _telemetry_exit_code(exc)
|
|
142
211
|
|
|
143
212
|
except FivetranPartialResultError as exc:
|
|
144
213
|
# Pagination stopped early on a malformed page — still a failure
|
|
@@ -152,17 +221,17 @@ def _execute_command(
|
|
|
152
221
|
f"fivetran: failed to render partial results: "
|
|
153
222
|
f"{type(render_exc).__name__}: {render_exc}\n"
|
|
154
223
|
)
|
|
155
|
-
return 1
|
|
224
|
+
return 1, _telemetry_exit_code(exc)
|
|
156
225
|
|
|
157
226
|
except FivetranCliError as exc:
|
|
158
227
|
emit_error(exc, args=args, stderr=stderr, operation_completed=operation_completed)
|
|
159
228
|
if operation_completed and not str(exc).startswith(UNKNOWN_FIELDS_ERROR_PREFIX):
|
|
160
229
|
emit_raw_json(payload, stdout)
|
|
161
|
-
return 1
|
|
230
|
+
return 1, _telemetry_exit_code(exc)
|
|
162
231
|
|
|
163
232
|
except Exception as exc:
|
|
164
233
|
stderr.write(f"fivetran: unexpected error: {type(exc).__name__}: {exc}\n")
|
|
165
|
-
return 1
|
|
234
|
+
return 1, _telemetry_exit_code(exc)
|
|
166
235
|
|
|
167
236
|
finally:
|
|
168
237
|
if client is not None:
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Runtime argument-value resolution helpers for the Fivetran CLI.
|
|
3
|
+
|
|
4
|
+
resolve_api_key() → str | None
|
|
5
|
+
resolve_output_format() → "text" | "json"
|
|
6
|
+
resolve_fields() → list[str] | None
|
|
7
|
+
validate_fields() → None, raises FivetranCliError on invalid input
|
|
8
|
+
resolve_filters() → list[FilterCondition] | None
|
|
9
|
+
validate_filters() → None, raises FivetranCliError on invalid input
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
from __future__ import annotations
|
|
13
|
+
|
|
14
|
+
import argparse
|
|
15
|
+
import os
|
|
16
|
+
|
|
17
|
+
from fivetran_cli.constants import FIVETRAN_API_KEY_ENV
|
|
18
|
+
from fivetran_cli.http.client import FilterCondition
|
|
19
|
+
from fivetran_cli.http.exceptions import FivetranCliError
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
def resolve_api_key(args: argparse.Namespace) -> str | None:
|
|
23
|
+
"""Return the effective API key for this invocation.
|
|
24
|
+
|
|
25
|
+
Precedence:
|
|
26
|
+
--api-key <key> (explicit CLI flag)
|
|
27
|
+
FIVETRAN_API_KEY environment variable (fallback)
|
|
28
|
+
None (neither provided)
|
|
29
|
+
"""
|
|
30
|
+
return getattr(args, "api_key", None) or os.environ.get(FIVETRAN_API_KEY_ENV)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def resolve_output_format(args: argparse.Namespace) -> str:
|
|
34
|
+
"""Return the output format for this invocation.
|
|
35
|
+
"""
|
|
36
|
+
if getattr(args, "output", None):
|
|
37
|
+
return args.output
|
|
38
|
+
return "text"
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def validate_fields(args: argparse.Namespace) -> None:
|
|
42
|
+
"""Raise if --fields was passed but is empty, or contains a nested
|
|
43
|
+
(dotted) field path, e.g. 'a.b'. Not passing --fields at all is fine."""
|
|
44
|
+
raw: str | None = getattr(args, "fields", None)
|
|
45
|
+
if raw is None:
|
|
46
|
+
return
|
|
47
|
+
|
|
48
|
+
fields = [f.strip() for f in raw.split(",") if f.strip()]
|
|
49
|
+
if not fields:
|
|
50
|
+
raise FivetranCliError("--fields cannot be empty")
|
|
51
|
+
|
|
52
|
+
nested = [f for f in fields if "." in f]
|
|
53
|
+
if nested:
|
|
54
|
+
raise FivetranCliError(
|
|
55
|
+
f"--fields only supports top-level field names, not nested paths: {', '.join(nested)}"
|
|
56
|
+
)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def resolve_fields(args: argparse.Namespace) -> list[str] | None:
|
|
60
|
+
"""Return the explicit field list from --fields, or None if not set."""
|
|
61
|
+
raw: str | None = getattr(args, "fields", None)
|
|
62
|
+
if not raw:
|
|
63
|
+
return None
|
|
64
|
+
return [f.strip() for f in raw.split(",") if f.strip()]
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _split_filter_condition(condition: str) -> FilterCondition:
|
|
68
|
+
"""Split a single "key=value" or "key!=value" condition into (dotted_path, operator, raw_value)."""
|
|
69
|
+
|
|
70
|
+
equals_index = condition.find("=")
|
|
71
|
+
if equals_index == -1:
|
|
72
|
+
raise FivetranCliError(
|
|
73
|
+
"--filter conditions must be in the form key=value or key!=value "
|
|
74
|
+
"(dotted paths supported for nested keys, e.g. status.pause=true), "
|
|
75
|
+
f"got: {condition!r}"
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
if equals_index > 0 and condition[equals_index - 1] == "!":
|
|
79
|
+
key, operator, raw_value = condition[:equals_index - 1], "!=", condition[equals_index + 1:]
|
|
80
|
+
else:
|
|
81
|
+
key, operator, raw_value = condition[:equals_index], "=", condition[equals_index + 1:]
|
|
82
|
+
|
|
83
|
+
key = key.strip()
|
|
84
|
+
if not key:
|
|
85
|
+
raise FivetranCliError(f"--filter key cannot be empty: {condition!r}")
|
|
86
|
+
return key, operator, raw_value
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def _check_for_conflicting_conditions(conditions: list[FilterCondition]) -> None:
|
|
90
|
+
"""Raise if a field has more than one "=" condition, or is required
|
|
91
|
+
to equal a value that a "!=" on the same field also excludes — both
|
|
92
|
+
are unsatisfiable. "=X,!=Y" for a different Y is fine."""
|
|
93
|
+
equals_values: dict[str, str] = {}
|
|
94
|
+
not_equals_values: dict[str, set[str]] = {}
|
|
95
|
+
for path, operator, raw_value in conditions:
|
|
96
|
+
if operator == "=":
|
|
97
|
+
if path in equals_values:
|
|
98
|
+
raise FivetranCliError(f"--filter has more than one '=' condition for '{path}'")
|
|
99
|
+
equals_values[path] = raw_value
|
|
100
|
+
else:
|
|
101
|
+
not_equals_values.setdefault(path, set()).add(raw_value)
|
|
102
|
+
|
|
103
|
+
for path, raw_value in equals_values.items():
|
|
104
|
+
if raw_value in not_equals_values.get(path, ()):
|
|
105
|
+
raise FivetranCliError(
|
|
106
|
+
f"--filter requires '{path}' to equal {raw_value!r} but also excludes that value via '!='"
|
|
107
|
+
)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def validate_filters(args: argparse.Namespace) -> None:
|
|
111
|
+
"""Raise if --filter is malformed, i.e. any comma-separated condition is
|
|
112
|
+
not in key=value / key!=value form, has an empty condition, or conflicts with
|
|
113
|
+
another condition on the same field."""
|
|
114
|
+
raw: str | None = getattr(args, "filter", None)
|
|
115
|
+
if raw is None:
|
|
116
|
+
return
|
|
117
|
+
if not raw:
|
|
118
|
+
raise FivetranCliError("--filter cannot be empty")
|
|
119
|
+
|
|
120
|
+
conditions = [_split_filter_condition(condition) for condition in raw.split(",")]
|
|
121
|
+
_check_for_conflicting_conditions(conditions)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
def resolve_filters(args: argparse.Namespace) -> list[FilterCondition] | None:
|
|
125
|
+
"""Return the parsed (dotted_path, operator, raw_value) triples from
|
|
126
|
+
--filter, or None if not set."""
|
|
127
|
+
raw: str | None = getattr(args, "filter", None)
|
|
128
|
+
if not raw:
|
|
129
|
+
return None
|
|
130
|
+
|
|
131
|
+
return [_split_filter_condition(condition) for condition in raw.split(",")]
|
|
@@ -22,7 +22,22 @@ from enum import Enum
|
|
|
22
22
|
from pathlib import Path
|
|
23
23
|
from typing import Any, Callable, Sequence
|
|
24
24
|
|
|
25
|
-
from fivetran_cli.
|
|
25
|
+
from fivetran_cli.cli_utils.dispatch.reserved_flags import (
|
|
26
|
+
FLAG_ALL_COLUMNS,
|
|
27
|
+
FLAG_API_KEY,
|
|
28
|
+
FLAG_CONFIG,
|
|
29
|
+
FLAG_CONFIG_FILE,
|
|
30
|
+
FLAG_FIELDS,
|
|
31
|
+
FLAG_FILTER,
|
|
32
|
+
FLAG_HELP,
|
|
33
|
+
FLAG_LIMIT,
|
|
34
|
+
FLAG_NON_INTERACTIVE,
|
|
35
|
+
FLAG_OUTPUT,
|
|
36
|
+
FLAG_OUTPUT_FILE,
|
|
37
|
+
FLAG_YES,
|
|
38
|
+
)
|
|
39
|
+
from fivetran_cli.cli_utils.args import resolve_filters
|
|
40
|
+
from fivetran_cli.constants import HELP_POSITION, OUTPUT_FORMATS
|
|
26
41
|
from fivetran_cli.http.client import FivetranClient
|
|
27
42
|
from fivetran_cli.http.exceptions import FivetranCliError
|
|
28
43
|
|
|
@@ -66,7 +81,7 @@ class Endpoint:
|
|
|
66
81
|
PayloadMode.OPTIONAL — payload accepted but not required
|
|
67
82
|
PayloadMode.REQUIRED — payload must be supplied
|
|
68
83
|
destructive Requires --yes or interactive confirmation
|
|
69
|
-
paginated Adds --limit
|
|
84
|
+
paginated Adds --limit, --all-columns, and --filter flags
|
|
70
85
|
"""
|
|
71
86
|
method: str
|
|
72
87
|
path_template: str
|
|
@@ -75,11 +90,28 @@ class Endpoint:
|
|
|
75
90
|
payload: PayloadMode = PayloadMode.NONE
|
|
76
91
|
destructive: bool = False
|
|
77
92
|
paginated: bool = False
|
|
93
|
+
paginated_output_columns: tuple[str, ...] = ()
|
|
78
94
|
action_label: str = "" # e.g. "Delete", "Remove", "Drop"
|
|
79
95
|
resource_type: str = "" # e.g. "connection", "user from team"
|
|
80
96
|
consequence: str = "This action cannot be undone."
|
|
81
97
|
|
|
82
98
|
|
|
99
|
+
@dataclass(frozen=True)
|
|
100
|
+
class CommandMetadata:
|
|
101
|
+
"""
|
|
102
|
+
The smaller set of an Endpoint's metadata that other modules (outside this
|
|
103
|
+
dispatch layer) need to read off the parsed argparse Namespace.
|
|
104
|
+
|
|
105
|
+
id_args Names of path variables, used to recover a resource ID
|
|
106
|
+
for error messages (see display/error_output.py).
|
|
107
|
+
output_columns Full column list for a paginated endpoint's response
|
|
108
|
+
item schema, used to build table headers up front
|
|
109
|
+
instead of deriving them from fetched data.
|
|
110
|
+
"""
|
|
111
|
+
id_args: tuple[str, ...] = ()
|
|
112
|
+
output_columns: tuple[str, ...] = ()
|
|
113
|
+
|
|
114
|
+
|
|
83
115
|
def add_endpoint_command(
|
|
84
116
|
subparsers: argparse._SubParsersAction, # type: ignore[type-arg]
|
|
85
117
|
name: str,
|
|
@@ -132,7 +164,7 @@ def add_endpoint_command(
|
|
|
132
164
|
|
|
133
165
|
if endpoint.paginated:
|
|
134
166
|
optional_group.add_argument( # type: ignore[union-attr]
|
|
135
|
-
"--
|
|
167
|
+
f"--{FLAG_LIMIT}",
|
|
136
168
|
type=int,
|
|
137
169
|
default=None,
|
|
138
170
|
action=_RejectDuplicateAction,
|
|
@@ -151,7 +183,13 @@ def add_endpoint_command(
|
|
|
151
183
|
|
|
152
184
|
global_group = parser.add_argument_group("global options")
|
|
153
185
|
_add_global_args(global_group, endpoint)
|
|
154
|
-
parser.set_defaults(
|
|
186
|
+
parser.set_defaults(
|
|
187
|
+
handler=_make_handler(endpoint),
|
|
188
|
+
command_metadata=CommandMetadata(
|
|
189
|
+
id_args=endpoint.id_args,
|
|
190
|
+
output_columns=endpoint.paginated_output_columns,
|
|
191
|
+
),
|
|
192
|
+
)
|
|
155
193
|
|
|
156
194
|
|
|
157
195
|
def _add_global_args(
|
|
@@ -160,13 +198,13 @@ def _add_global_args(
|
|
|
160
198
|
) -> None:
|
|
161
199
|
"""Register global options on every operation-level parser based on operation."""
|
|
162
200
|
parser.add_argument(
|
|
163
|
-
"-h", "--
|
|
201
|
+
"-h", f"--{FLAG_HELP}",
|
|
164
202
|
action="help",
|
|
165
203
|
default=argparse.SUPPRESS,
|
|
166
204
|
help="show this help message and exit",
|
|
167
205
|
)
|
|
168
206
|
parser.add_argument(
|
|
169
|
-
"--
|
|
207
|
+
f"--{FLAG_API_KEY}",
|
|
170
208
|
dest="api_key",
|
|
171
209
|
required=False,
|
|
172
210
|
action=_RejectDuplicateAction,
|
|
@@ -177,31 +215,43 @@ def _add_global_args(
|
|
|
177
215
|
),
|
|
178
216
|
)
|
|
179
217
|
parser.add_argument(
|
|
180
|
-
"--
|
|
181
|
-
choices=
|
|
218
|
+
f"--{FLAG_OUTPUT}",
|
|
219
|
+
choices=OUTPUT_FORMATS,
|
|
182
220
|
default=None,
|
|
183
221
|
action=_RejectDuplicateAction,
|
|
184
222
|
help="Output format: text (default) or json.",
|
|
185
223
|
)
|
|
186
224
|
if endpoint.paginated:
|
|
187
225
|
parser.add_argument(
|
|
188
|
-
"--
|
|
226
|
+
f"--{FLAG_ALL_COLUMNS}",
|
|
189
227
|
dest="show_all_columns",
|
|
190
228
|
action="store_true",
|
|
191
229
|
default=False,
|
|
192
230
|
help="Show all columns instead of the default 8.",
|
|
193
231
|
)
|
|
232
|
+
parser.add_argument(
|
|
233
|
+
f"--{FLAG_FILTER}",
|
|
234
|
+
default=None,
|
|
235
|
+
action=_RejectDuplicateAction,
|
|
236
|
+
metavar="KEY=VALUE[,KEY=VALUE..]",
|
|
237
|
+
help=(
|
|
238
|
+
"Filter results to rows/items matching every comma-separated "
|
|
239
|
+
"KEY=VALUE or KEY!=VALUE condition. Use dotted keys "
|
|
240
|
+
"for nested fields, e.g. status.pause=true. "
|
|
241
|
+
"Example: --filter id=sid,status.setup_state!=connected"
|
|
242
|
+
),
|
|
243
|
+
)
|
|
194
244
|
|
|
195
245
|
if endpoint.method == "GET":
|
|
196
246
|
parser.add_argument(
|
|
197
|
-
"--
|
|
247
|
+
f"--{FLAG_FIELDS}",
|
|
198
248
|
default=None,
|
|
199
249
|
action=_RejectDuplicateAction,
|
|
200
250
|
help="Comma-separated list of top-level fields/columns to display.",
|
|
201
251
|
)
|
|
202
252
|
|
|
203
253
|
parser.add_argument(
|
|
204
|
-
"--
|
|
254
|
+
f"--{FLAG_OUTPUT_FILE}",
|
|
205
255
|
dest="output_file",
|
|
206
256
|
default=None,
|
|
207
257
|
action=_RejectDuplicateAction,
|
|
@@ -210,14 +260,14 @@ def _add_global_args(
|
|
|
210
260
|
)
|
|
211
261
|
if endpoint.destructive:
|
|
212
262
|
parser.add_argument(
|
|
213
|
-
"--
|
|
263
|
+
f"--{FLAG_NON_INTERACTIVE}",
|
|
214
264
|
dest="non_interactive",
|
|
215
265
|
action="store_true",
|
|
216
266
|
default=False,
|
|
217
267
|
help="Automatically accepts the default choice for all confirmation prompts",
|
|
218
268
|
)
|
|
219
269
|
parser.add_argument(
|
|
220
|
-
"--
|
|
270
|
+
f"--{FLAG_YES}",
|
|
221
271
|
action="store_true",
|
|
222
272
|
default=False,
|
|
223
273
|
help="Automatically answers yes to the destructive confirmation prompt",
|
|
@@ -244,6 +294,7 @@ def _make_handler(endpoint: Endpoint) -> Handler:
|
|
|
244
294
|
query=query,
|
|
245
295
|
payload=payload,
|
|
246
296
|
limit=limit_val,
|
|
297
|
+
filters=resolve_filters(args),
|
|
247
298
|
)
|
|
248
299
|
|
|
249
300
|
return client.request(
|
|
@@ -293,8 +344,8 @@ def _load_payload(args: argparse.Namespace) -> Any:
|
|
|
293
344
|
|
|
294
345
|
def _add_payload_options(parser: argparse.ArgumentParser | argparse._ArgumentGroup, *, required: bool) -> None:
|
|
295
346
|
group = parser.add_mutually_exclusive_group(required=required)
|
|
296
|
-
group.add_argument("--
|
|
297
|
-
group.add_argument("--
|
|
347
|
+
group.add_argument(f"--{FLAG_CONFIG}", default=None, action=_RejectDuplicateAction, help="Inline JSON payload for the request.")
|
|
348
|
+
group.add_argument(f"--{FLAG_CONFIG_FILE}", default=None, action=_RejectDuplicateAction, help="Path to a JSON file (or '-' for stdin).")
|
|
298
349
|
|
|
299
350
|
|
|
300
351
|
def _confirm_destructive(args: argparse.Namespace, endpoint: Endpoint) -> None:
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
"""
|
|
2
|
+
Source of truth for the built-in CLI flags that every generated
|
|
3
|
+
operation parser registers, via add_endpoint_command()/_add_global_args()
|
|
4
|
+
in dispatch/base.py.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
# ─── Individual flag names ───────────────────────
|
|
10
|
+
FLAG_HELP = "help"
|
|
11
|
+
FLAG_API_KEY = "api-key"
|
|
12
|
+
FLAG_OUTPUT = "output"
|
|
13
|
+
FLAG_OUTPUT_FILE = "output-file"
|
|
14
|
+
FLAG_FIELDS = "fields"
|
|
15
|
+
FLAG_ALL_COLUMNS = "all-columns"
|
|
16
|
+
FLAG_LIMIT = "limit"
|
|
17
|
+
FLAG_FILTER = "filter"
|
|
18
|
+
FLAG_NON_INTERACTIVE = "non-interactive"
|
|
19
|
+
FLAG_YES = "yes"
|
|
20
|
+
FLAG_CONFIG = "config"
|
|
21
|
+
FLAG_CONFIG_FILE = "config-file"
|
|
22
|
+
|
|
23
|
+
# ─── Grouped by the condition under which _add_global_args()/
|
|
24
|
+
# add_endpoint_command() registers them ──────────────────────────────────
|
|
25
|
+
RESERVED_FLAGS_ALWAYS = frozenset({FLAG_HELP, FLAG_API_KEY, FLAG_OUTPUT, FLAG_OUTPUT_FILE})
|
|
26
|
+
RESERVED_FLAGS_GET = frozenset({FLAG_FIELDS})
|
|
27
|
+
RESERVED_FLAGS_PAGINATED = frozenset({FLAG_ALL_COLUMNS, FLAG_LIMIT, FLAG_FILTER})
|
|
28
|
+
RESERVED_FLAGS_DESTRUCTIVE = frozenset({FLAG_NON_INTERACTIVE, FLAG_YES})
|
|
29
|
+
RESERVED_FLAGS_PAYLOAD = frozenset({FLAG_CONFIG, FLAG_CONFIG_FILE})
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def reserved_flags_for_operation(
|
|
33
|
+
method: str,
|
|
34
|
+
*,
|
|
35
|
+
paginated: bool = False,
|
|
36
|
+
payload_required: bool = False,
|
|
37
|
+
payload_optional: bool = False,
|
|
38
|
+
destructive: bool = False,
|
|
39
|
+
) -> frozenset[str]:
|
|
40
|
+
"""
|
|
41
|
+
Return the exact set of built-in CLI flags
|
|
42
|
+
that add_endpoint_command()/_add_global_args() register for an operation
|
|
43
|
+
with these characteristics.
|
|
44
|
+
|
|
45
|
+
Example Input:
|
|
46
|
+
method="GET", paginated=True, payload_required=False,
|
|
47
|
+
payload_optional=False, destructive=False
|
|
48
|
+
Example Output:
|
|
49
|
+
frozenset({"help", "api-key", "output", "output-file",
|
|
50
|
+
"fields", "all-columns", "limit", "filter"})
|
|
51
|
+
"""
|
|
52
|
+
flags = set(RESERVED_FLAGS_ALWAYS)
|
|
53
|
+
if method.upper() == "GET":
|
|
54
|
+
flags |= RESERVED_FLAGS_GET
|
|
55
|
+
if paginated:
|
|
56
|
+
flags |= RESERVED_FLAGS_PAGINATED
|
|
57
|
+
if destructive:
|
|
58
|
+
flags |= RESERVED_FLAGS_DESTRUCTIVE
|
|
59
|
+
if payload_required or payload_optional:
|
|
60
|
+
flags |= RESERVED_FLAGS_PAYLOAD
|
|
61
|
+
return frozenset(flags)
|
|
62
|
+
|
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
"""Parser public API."""
|
|
2
2
|
|
|
3
|
-
from fivetran_cli.cli_utils.
|
|
3
|
+
from fivetran_cli.cli_utils.args import (
|
|
4
4
|
resolve_api_key,
|
|
5
5
|
resolve_fields,
|
|
6
|
+
resolve_filters,
|
|
6
7
|
resolve_output_format,
|
|
7
8
|
validate_fields,
|
|
9
|
+
validate_filters,
|
|
8
10
|
)
|
|
9
11
|
from fivetran_cli.cli_utils.parser.builder import build_parser
|
|
10
12
|
|
|
@@ -12,6 +14,8 @@ __all__ = [
|
|
|
12
14
|
"build_parser",
|
|
13
15
|
"resolve_api_key",
|
|
14
16
|
"resolve_fields",
|
|
17
|
+
"resolve_filters",
|
|
15
18
|
"resolve_output_format",
|
|
16
19
|
"validate_fields",
|
|
20
|
+
"validate_filters",
|
|
17
21
|
]
|