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.
Files changed (59) hide show
  1. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/PKG-INFO +1 -1
  2. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/__init__.py +105 -36
  3. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/args.py +131 -0
  4. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/base.py +66 -15
  5. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/reserved_flags.py +62 -0
  6. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/parser/__init__.py +5 -1
  7. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/parser/builder.py +4 -5
  8. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/certificate.py +2 -0
  9. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connection.py +1 -0
  10. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connector_metadata.py +1 -0
  11. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connector_sdk_package.py +1 -0
  12. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/destination.py +1 -0
  13. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/fingerprint.py +2 -0
  14. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/group.py +3 -0
  15. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/hybrid_deployment_agent.py +1 -0
  16. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/log_service.py +1 -0
  17. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/private_link.py +1 -0
  18. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/proxy_agent.py +2 -0
  19. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/role.py +1 -0
  20. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/system_key.py +1 -0
  21. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/team.py +4 -0
  22. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/transformation.py +2 -0
  23. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/transformation_project.py +1 -0
  24. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/user.py +3 -0
  25. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/webhook.py +1 -0
  26. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/constants.py +10 -0
  27. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/_formatters.py +1 -1
  28. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/error_output.py +20 -68
  29. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/output.py +1 -1
  30. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/client.py +231 -28
  31. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/config.py +1 -1
  32. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/exceptions.py +11 -0
  33. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/plugin_api.py +4 -0
  34. fivetran_cli-1.1.0/src/fivetran_cli/telemetry_helper.py +147 -0
  35. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/PKG-INFO +1 -1
  36. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/SOURCES.txt +7 -2
  37. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/top_level.txt +2 -0
  38. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/__init__.py +3 -0
  39. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/_sender.py +34 -0
  40. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/telemetry.py +343 -0
  41. fivetran_cli-1.0.0/src/fivetran_cli/cli_utils/parser/args.py +0 -61
  42. fivetran_cli-1.0.0/src/fivetran_cli.egg-info/top_level.txt +0 -1
  43. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/README.md +0 -0
  44. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/pyproject.toml +0 -0
  45. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/setup.cfg +0 -0
  46. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli.py +0 -0
  47. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_parser.py +0 -0
  48. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/__init__.py +0 -0
  49. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/dispatch/timeout.py +0 -0
  50. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/__init__.py +0 -0
  51. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/account.py +0 -0
  52. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/connection_schema.py +0 -0
  53. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/cli_utils/resources/public_connector.py +0 -0
  54. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/_renderers.py +0 -0
  55. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/display/views.py +0 -0
  56. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli/http/__init__.py +0 -0
  57. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/dependency_links.txt +0 -0
  58. {fivetran_cli-1.0.0 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/entry_points.txt +0 -0
  59. {fivetran_cli-1.0.0 → fivetran_cli-1.1.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.1.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
@@ -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
- __version__ = "1.0.0"
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, parse_exit_code = _parse_arguments(argv, parser, stdout, stderr)
35
- if parse_exit_code is not None:
36
- return parse_exit_code
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
- return 0
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
- return _execute_command(args, stdout, stderr)
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
- ) -> tuple[argparse.Namespace | None, int | None]:
85
- """Parses CLI arguments."""
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
- return None, 1
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, stderr: TextIO) -> int | None:
98
- """Reject conflicting prompt flags after parse for all commands."""
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
- stderr.write("Error: --yes and --non-interactive cannot be used together.\n")
101
- return 1
102
- return None
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 output."""
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.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",
@@ -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("--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).")
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.parser.args import (
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
  ]