fivetran-cli 1.0.0__tar.gz → 1.2.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.
Files changed (64) hide show
  1. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/PKG-INFO +3 -3
  2. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/README.md +1 -1
  3. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/pyproject.toml +1 -1
  4. fivetran_cli-1.2.0/src/fivetran_cli/__init__.py +292 -0
  5. fivetran_cli-1.2.0/src/fivetran_cli/cli_utils/__init__.py +0 -0
  6. fivetran_cli-1.2.0/src/fivetran_cli/cli_utils/args.py +131 -0
  7. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/dispatch/base.py +69 -15
  8. fivetran_cli-1.2.0/src/fivetran_cli/cli_utils/dispatch/reserved_flags.py +62 -0
  9. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/parser/__init__.py +5 -1
  10. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/parser/builder.py +4 -5
  11. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/certificate.py +2 -0
  12. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/connection.py +1 -0
  13. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/connector_metadata.py +1 -0
  14. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/connector_sdk_package.py +1 -0
  15. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/destination.py +1 -0
  16. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/fingerprint.py +2 -0
  17. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/group.py +3 -0
  18. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/hybrid_deployment_agent.py +1 -0
  19. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/log_service.py +1 -0
  20. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/private_link.py +1 -0
  21. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/proxy_agent.py +2 -0
  22. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/role.py +1 -0
  23. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/system_key.py +1 -0
  24. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/team.py +4 -0
  25. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/transformation.py +2 -0
  26. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/transformation_project.py +1 -0
  27. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/user.py +3 -0
  28. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/webhook.py +1 -0
  29. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/constants.py +10 -0
  30. fivetran_cli-1.2.0/src/fivetran_cli/display/__init__.py +0 -0
  31. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/display/_formatters.py +1 -1
  32. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/display/_renderers.py +17 -7
  33. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/display/error_output.py +20 -68
  34. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/display/output.py +41 -6
  35. fivetran_cli-1.2.0/src/fivetran_cli/display/page_stream.py +98 -0
  36. fivetran_cli-1.2.0/src/fivetran_cli/http/client.py +582 -0
  37. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/http/config.py +1 -1
  38. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/http/exceptions.py +11 -0
  39. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/plugin_api.py +4 -0
  40. fivetran_cli-1.2.0/src/fivetran_cli/telemetry_helper.py +147 -0
  41. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli.egg-info/PKG-INFO +3 -3
  42. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli.egg-info/SOURCES.txt +10 -2
  43. fivetran_cli-1.2.0/src/fivetran_cli.egg-info/top_level.txt +2 -0
  44. fivetran_cli-1.2.0/src/fivetran_cli_telemetry/__init__.py +3 -0
  45. fivetran_cli-1.2.0/src/fivetran_cli_telemetry/_sender.py +34 -0
  46. fivetran_cli-1.2.0/src/fivetran_cli_telemetry/telemetry.py +343 -0
  47. fivetran_cli-1.0.0/src/fivetran_cli/__init__.py +0 -197
  48. fivetran_cli-1.0.0/src/fivetran_cli/cli_utils/parser/args.py +0 -61
  49. fivetran_cli-1.0.0/src/fivetran_cli/http/client.py +0 -357
  50. fivetran_cli-1.0.0/src/fivetran_cli.egg-info/top_level.txt +0 -1
  51. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/setup.cfg +0 -0
  52. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli.py +0 -0
  53. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_parser.py +0 -0
  54. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/dispatch/__init__.py +0 -0
  55. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/dispatch/timeout.py +0 -0
  56. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/__init__.py +0 -0
  57. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/account.py +0 -0
  58. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/connection_schema.py +0 -0
  59. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/cli_utils/resources/public_connector.py +0 -0
  60. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/display/views.py +0 -0
  61. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli/http/__init__.py +0 -0
  62. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli.egg-info/dependency_links.txt +0 -0
  63. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli.egg-info/entry_points.txt +0 -0
  64. {fivetran_cli-1.0.0 → fivetran_cli-1.2.0}/src/fivetran_cli.egg-info/requires.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: fivetran_cli
3
- Version: 1.0.0
3
+ Version: 1.2.0
4
4
  Summary: Command line wrapper for the Fivetran REST API and Connector SDK
5
5
  Author-email: Fivetran <developers@fivetran.com>
6
6
  Project-URL: Homepage, https://fivetran.com
@@ -8,7 +8,7 @@ Project-URL: Github, https://github.com/fivetran/engineering
8
8
  Classifier: Programming Language :: Python :: 3
9
9
  Classifier: License :: OSI Approved :: MIT License
10
10
  Classifier: Operating System :: OS Independent
11
- Requires-Python: >=3.10
11
+ Requires-Python: >=3.11
12
12
  Description-Content-Type: text/markdown
13
13
  Requires-Dist: rich>=13.0
14
14
  Requires-Dist: requests==2.34.2
@@ -30,7 +30,7 @@ Verify the installation:
30
30
 
31
31
  ## Requirements
32
32
 
33
- - Python 3.10 or later
33
+ - Python 3.11 or later
34
34
  - A Fivetran account and API key for commands that communicate with Fivetran
35
35
 
36
36
  ## Authentication
@@ -14,7 +14,7 @@ Verify the installation:
14
14
 
15
15
  ## Requirements
16
16
 
17
- - Python 3.10 or later
17
+ - Python 3.11 or later
18
18
  - A Fivetran account and API key for commands that communicate with Fivetran
19
19
 
20
20
  ## Authentication
@@ -6,7 +6,7 @@ authors = [
6
6
  ]
7
7
  description = "Command line wrapper for the Fivetran REST API and Connector SDK"
8
8
  readme = "README.md"
9
- requires-python = ">=3.10"
9
+ requires-python = ">=3.11"
10
10
  classifiers = [
11
11
  "Programming Language :: Python :: 3",
12
12
  "License :: OSI Approved :: MIT License",
@@ -0,0 +1,292 @@
1
+ from __future__ import annotations
2
+
3
+ import argparse
4
+ import contextlib
5
+ import os
6
+ import sys
7
+ import time
8
+ from pathlib import Path
9
+ from typing import Sequence, TextIO
10
+
11
+ # Version format: <major_version>.<minor_version>.<patch_version>
12
+ __version__ = "1.2.0"
13
+
14
+ from fivetran_cli import telemetry_helper
15
+ from fivetran_cli.cli_utils.dispatch.timeout import cancel_command_timeout, command_timed_out, install_command_timeout
16
+ from fivetran_cli.cli_utils.parser import build_parser, resolve_output_format, validate_fields, validate_filters
17
+ from fivetran_cli.cli_parser import discover_plugins, first_command_token
18
+ from fivetran_cli.constants import COMMAND_TIMEOUT, FIVETRAN_CLI_COMMANDS, UNKNOWN_FIELDS_ERROR_PREFIX
19
+ from fivetran_cli.display.error_output import emit_error
20
+ from fivetran_cli.display.output import create_page_stream, emit_output, emit_raw_json, ensure_writable_parent
21
+ from fivetran_cli.display.page_stream import PageStream
22
+ from fivetran_cli.http.client import FivetranClient
23
+ from fivetran_cli.http.config import resolve_config, require_api_key
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
47
+
48
+
49
+ def main(argv: Sequence[str] | None = None) -> int:
50
+ _configure_stdio_encoding()
51
+ return run(list(argv) if argv is not None else sys.argv[1:])
52
+
53
+
54
+ def run(argv: list[str], *, stdout: TextIO = sys.stdout, stderr: TextIO = sys.stderr) -> int:
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()
62
+
63
+ early_exit_code = _handle_early_dispatch(argv, parser, stdout, start_time)
64
+ if early_exit_code is not None:
65
+ return early_exit_code
66
+
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
71
+
72
+ if not hasattr(args, "handler"):
73
+ parser.print_help(stdout)
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
+
84
+
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
94
+
95
+
96
+ def _handle_early_dispatch(
97
+ argv: list[str],
98
+ parser: argparse.ArgumentParser,
99
+ stdout: TextIO,
100
+ start_time: float,
101
+ ) -> int | None:
102
+ """Handles help requests, version checks, and third-party plugin dispatch."""
103
+ if not argv or (len(argv) == 1 and argv[0] in {"-h", "--help", "help"}):
104
+ parser.print_help(stdout)
105
+ telemetry_helper.record_cli_usage(argv, parser, 0, time.perf_counter() - start_time)
106
+ return 0
107
+
108
+ if argv == ["version"]:
109
+ version_action = next(
110
+ (a for a in parser._actions if isinstance(a, argparse._VersionAction)),
111
+ None,
112
+ )
113
+ if version_action is not None:
114
+ stdout.write(version_action.version + "\n")
115
+ telemetry_helper.record_cli_usage(argv, parser, 0, time.perf_counter() - start_time)
116
+ return 0
117
+
118
+ first_positional = first_command_token(argv)
119
+ if first_positional is not None and first_positional not in FIVETRAN_CLI_COMMANDS:
120
+ plugins = discover_plugins()
121
+ target = plugins.get(first_positional)
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)
125
+ result = target.plugin.dispatch(argv)
126
+ return result if isinstance(result, int) else 0
127
+
128
+ return None
129
+
130
+
131
+ def _parse_arguments(
132
+ argv: list[str],
133
+ parser: argparse.ArgumentParser,
134
+ stdout: TextIO,
135
+ stderr: TextIO,
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."""
141
+ try:
142
+ # argparse writes help/usage to process-global stdio, so redirect here
143
+ # to honor run() caller-provided output streams.
144
+ with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
145
+ return parser.parse_args(argv), None, None
146
+ except SystemExit as exc:
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)
152
+ raise
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)
157
+
158
+
159
+ def _validate_prompt_flags(args: argparse.Namespace) -> None:
160
+ """Raise if conflicting prompt flags (--yes and --non-interactive) are
161
+ both set."""
162
+ if getattr(args, "yes", False) and getattr(args, "non_interactive", False):
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)
173
+
174
+
175
+ def _handle_partial_result_error(
176
+ exc: FivetranPartialResultError,
177
+ args: argparse.Namespace,
178
+ stdout: TextIO,
179
+ stderr: TextIO,
180
+ page_stream: PageStream | None,
181
+ ) -> None:
182
+ """Reports a pagination that stopped early. Data collected so far is shown
183
+ on stdout, unless it was already streamed page by page. An output file is
184
+ only ever written by a successful run."""
185
+ emit_error(exc, args=args, stderr=stderr)
186
+ output_file = getattr(args, "output_file", None)
187
+ if output_file:
188
+ stderr.write(f"Output file '{output_file}' was not written because the results are incomplete.\n")
189
+ return
190
+ if exc.partial_data is None or page_stream is not None:
191
+ return
192
+ try:
193
+ emit_output(exc.partial_data, args=args, stdout=stdout)
194
+ except Exception as render_exc:
195
+ stderr.write(
196
+ f"fivetran: failed to render partial results: "
197
+ f"{type(render_exc).__name__}: {render_exc}\n"
198
+ )
199
+
200
+
201
+ def _execute_command(
202
+ args: argparse.Namespace,
203
+ stdout: TextIO,
204
+ stderr: TextIO,
205
+ ) -> tuple[int, int]:
206
+ """Configures the client, invokes the command handler, and emits formatted
207
+ output. Returns (process_exit_code, telemetry_exit_code): the process
208
+ always exits 0/1 (our fixed exit-code contract), but telemetry's own
209
+ exit_code field carries richer numeric detail when available (e.g. the
210
+ API's HTTP status_code) instead of a generic 1 — see _telemetry_exit_code."""
211
+ operation_completed = False
212
+ payload = None
213
+ page_stream: PageStream | None = None
214
+ client: FivetranClient | None = None
215
+ try:
216
+ _validate_flags_before_execution(args)
217
+ config = resolve_config(args)
218
+ require_api_key(config)
219
+ client = FivetranClient(config, stderr=stderr)
220
+ page_stream = create_page_stream(args, stdout)
221
+
222
+ install_command_timeout(COMMAND_TIMEOUT, stderr)
223
+
224
+ args._stdout = stdout
225
+ args._stderr = stderr
226
+ args._page_stream = page_stream
227
+
228
+ try:
229
+ payload = args.handler(args, client)
230
+ operation_completed = True
231
+ # finish the page stream and don't emit output again as page by page rendering happened already
232
+ if page_stream is not None:
233
+ page_stream.finish()
234
+ else:
235
+ emit_output(payload, args=args, stdout=stdout)
236
+ return 0, 0
237
+ finally:
238
+ cancel_command_timeout()
239
+
240
+ except KeyboardInterrupt as exc:
241
+ if not command_timed_out():
242
+ stderr.write("\nfivetran: interrupted\n")
243
+ return 1, _telemetry_exit_code(exc)
244
+
245
+ except FivetranPartialResultError as exc:
246
+ # Pagination stopped early — still a failure (exit non-zero). Data
247
+ # collected so far is shown on stdout, unless it was already streamed
248
+ # page by page. An output file is only ever written by a successful run.
249
+ _handle_partial_result_error(exc, args, stdout, stderr, page_stream)
250
+ return 1, _telemetry_exit_code(exc)
251
+
252
+ except FivetranCliError as exc:
253
+ emit_error(exc, args=args, stderr=stderr, operation_completed=operation_completed)
254
+ if operation_completed and not str(exc).startswith(UNKNOWN_FIELDS_ERROR_PREFIX):
255
+ emit_raw_json(payload, stdout)
256
+ return 1, _telemetry_exit_code(exc)
257
+
258
+ except Exception as exc:
259
+ stderr.write(f"fivetran: unexpected error: {type(exc).__name__}: {exc}\n")
260
+ return 1, _telemetry_exit_code(exc)
261
+
262
+ finally:
263
+ if client is not None:
264
+ client.close()
265
+
266
+
267
+ def _validate_output_destination(args: argparse.Namespace) -> None:
268
+ """
269
+ Fail fast, before the command handler runs, if --output-file points to a
270
+ path we won't be able to write to. This only checks permissions/existence.
271
+ """
272
+ output_file: str | None = getattr(args, "output_file", None)
273
+ if output_file is None:
274
+ return
275
+ if not output_file.strip():
276
+ raise FivetranCliError("--output-file cannot be empty")
277
+ if output_file.endswith("/") or (os.sep != "/" and output_file.endswith(os.sep)):
278
+ raise FivetranCliError(f"Cannot open output file '{output_file}': Path ends with a directory separator")
279
+
280
+ path = Path(output_file)
281
+
282
+ if path.exists() and path.is_dir():
283
+ raise FivetranCliError(f"Cannot open output file '{output_file}': Is a directory")
284
+
285
+ # Resolve output_file to its real path first: if it's a symlink, this is
286
+ # the symlink target's directory (what mkstemp() actually writes into);
287
+ # otherwise it's just output_file's own parent directory.
288
+ ensure_writable_parent(os.path.realpath(output_file))
289
+
290
+
291
+ if __name__ == "__main__":
292
+ raise SystemExit(main())
@@ -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.constants import HELP_POSITION
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 flag
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
- "--limit",
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(handler=_make_handler(endpoint), _endpoint_id_args=endpoint.id_args)
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", "--help",
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
- "--api-key",
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
- "--output",
181
- choices=("text", "json"),
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
- "--all-columns",
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
- "--fields",
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
- "--output-file",
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
- "--non-interactive",
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
- "--yes",
270
+ f"--{FLAG_YES}",
221
271
  action="store_true",
222
272
  default=False,
223
273
  help="Automatically answers yes to the destructive confirmation prompt",
@@ -233,6 +283,7 @@ def _make_handler(endpoint: Endpoint) -> Handler:
233
283
  payload = _load_payload(args) if endpoint.payload is not PayloadMode.NONE else None
234
284
  path = _build_path(endpoint.path_template, args, endpoint.id_args)
235
285
  query = {arg: getattr(args, arg, None) for arg in endpoint.query_args}
286
+ page_stream = getattr(args, "_page_stream", None)
236
287
 
237
288
  if endpoint.paginated:
238
289
  limit_val: int | None = getattr(args, "limit", None)
@@ -244,6 +295,9 @@ def _make_handler(endpoint: Endpoint) -> Handler:
244
295
  query=query,
245
296
  payload=payload,
246
297
  limit=limit_val,
298
+ filters=resolve_filters(args),
299
+ on_page=page_stream.write_page if page_stream else None,
300
+ output_to_file=bool(getattr(args, "output_file", None)),
247
301
  )
248
302
 
249
303
  return client.request(
@@ -293,8 +347,8 @@ def _load_payload(args: argparse.Namespace) -> Any:
293
347
 
294
348
  def _add_payload_options(parser: argparse.ArgumentParser | argparse._ArgumentGroup, *, required: bool) -> None:
295
349
  group = parser.add_mutually_exclusive_group(required=required)
296
- group.add_argument("--config", default=None, action=_RejectDuplicateAction, help="Inline JSON payload for the request.")
297
- group.add_argument("--config-file", default=None, action=_RejectDuplicateAction, help="Path to a JSON file (or '-' for stdin).")
350
+ group.add_argument(f"--{FLAG_CONFIG}", default=None, action=_RejectDuplicateAction, help="Inline JSON payload for the request.")
351
+ group.add_argument(f"--{FLAG_CONFIG_FILE}", default=None, action=_RejectDuplicateAction, help="Path to a JSON file (or '-' for stdin).")
298
352
 
299
353
 
300
354
  def _confirm_destructive(args: argparse.Namespace, endpoint: Endpoint) -> None: