fivetran-cli 0.1.13__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 (75) hide show
  1. fivetran_cli-1.1.0/PKG-INFO +131 -0
  2. fivetran_cli-1.1.0/README.md +115 -0
  3. fivetran_cli-1.1.0/pyproject.toml +37 -0
  4. fivetran_cli-1.1.0/src/fivetran_cli/__init__.py +266 -0
  5. fivetran_cli-1.1.0/src/fivetran_cli/cli.py +19 -0
  6. fivetran_cli-1.1.0/src/fivetran_cli/cli_parser.py +71 -0
  7. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/args.py +131 -0
  8. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/__init__.py +18 -0
  9. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/base.py +389 -0
  10. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/reserved_flags.py +62 -0
  11. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/dispatch/timeout.py +76 -0
  12. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/parser/__init__.py +21 -0
  13. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/parser/builder.py +309 -0
  14. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/__init__.py +49 -0
  15. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/account.py +49 -0
  16. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/certificate.py +227 -0
  17. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/connection.py +194 -0
  18. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/connection_schema.py +315 -0
  19. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/connector_metadata.py +69 -0
  20. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/connector_sdk_package.py +94 -0
  21. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/destination.py +148 -0
  22. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/fingerprint.py +227 -0
  23. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/group.py +312 -0
  24. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/hybrid_deployment_agent.py +157 -0
  25. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/log_service.py +246 -0
  26. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/private_link.py +129 -0
  27. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/proxy_agent.py +166 -0
  28. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/public_connector.py +49 -0
  29. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/role.py +51 -0
  30. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/system_key.py +151 -0
  31. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/team.py +520 -0
  32. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/transformation.py +250 -0
  33. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/transformation_project.py +147 -0
  34. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/user.py +405 -0
  35. fivetran_cli-1.1.0/src/fivetran_cli/cli_utils/resources/webhook.py +166 -0
  36. fivetran_cli-1.1.0/src/fivetran_cli/constants.py +49 -0
  37. fivetran_cli-1.1.0/src/fivetran_cli/display/_formatters.py +74 -0
  38. fivetran_cli-1.1.0/src/fivetran_cli/display/_renderers.py +418 -0
  39. fivetran_cli-1.1.0/src/fivetran_cli/display/error_output.py +160 -0
  40. fivetran_cli-1.1.0/src/fivetran_cli/display/output.py +154 -0
  41. fivetran_cli-1.1.0/src/fivetran_cli/display/views.py +15 -0
  42. fivetran_cli-1.1.0/src/fivetran_cli/http/__init__.py +12 -0
  43. fivetran_cli-1.1.0/src/fivetran_cli/http/client.py +560 -0
  44. fivetran_cli-1.1.0/src/fivetran_cli/http/config.py +28 -0
  45. fivetran_cli-1.1.0/src/fivetran_cli/http/exceptions.py +71 -0
  46. fivetran_cli-1.1.0/src/fivetran_cli/plugin_api.py +20 -0
  47. fivetran_cli-1.1.0/src/fivetran_cli/telemetry_helper.py +147 -0
  48. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/PKG-INFO +131 -0
  49. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/SOURCES.txt +55 -0
  50. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/entry_points.txt +2 -0
  51. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/requires.txt +3 -0
  52. fivetran_cli-1.1.0/src/fivetran_cli.egg-info/top_level.txt +2 -0
  53. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/__init__.py +3 -0
  54. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/_sender.py +34 -0
  55. fivetran_cli-1.1.0/src/fivetran_cli_telemetry/telemetry.py +343 -0
  56. fivetran_cli-0.1.13/LICENSE +0 -21
  57. fivetran_cli-0.1.13/MANIFEST.in +0 -6
  58. fivetran_cli-0.1.13/PKG-INFO +0 -179
  59. fivetran_cli-0.1.13/README.md +0 -162
  60. fivetran_cli-0.1.13/pyproject.toml +0 -27
  61. fivetran_cli-0.1.13/src/fivetran_cli/__init__.py +0 -3
  62. fivetran_cli-0.1.13/src/fivetran_cli/__main__.py +0 -5
  63. fivetran_cli-0.1.13/src/fivetran_cli/cli.py +0 -2128
  64. fivetran_cli-0.1.13/src/fivetran_cli/client.py +0 -165
  65. fivetran_cli-0.1.13/src/fivetran_cli/output.py +0 -575
  66. fivetran_cli-0.1.13/src/fivetran_cli/views.py +0 -123
  67. fivetran_cli-0.1.13/src/fivetran_cli.egg-info/PKG-INFO +0 -179
  68. fivetran_cli-0.1.13/src/fivetran_cli.egg-info/SOURCES.txt +0 -18
  69. fivetran_cli-0.1.13/src/fivetran_cli.egg-info/requires.txt +0 -1
  70. fivetran_cli-0.1.13/src/fivetran_cli.egg-info/top_level.txt +0 -1
  71. fivetran_cli-0.1.13/tests/test_cli.py +0 -734
  72. fivetran_cli-0.1.13/tests/test_client.py +0 -91
  73. fivetran_cli-0.1.13/tests/test_output.py +0 -199
  74. {fivetran_cli-0.1.13 → fivetran_cli-1.1.0}/setup.cfg +0 -0
  75. {fivetran_cli-0.1.13 → fivetran_cli-1.1.0}/src/fivetran_cli.egg-info/dependency_links.txt +0 -0
@@ -0,0 +1,131 @@
1
+ Metadata-Version: 2.4
2
+ Name: fivetran_cli
3
+ Version: 1.1.0
4
+ Summary: Command line wrapper for the Fivetran REST API and Connector SDK
5
+ Author-email: Fivetran <developers@fivetran.com>
6
+ Project-URL: Homepage, https://fivetran.com
7
+ Project-URL: Github, https://github.com/fivetran/engineering
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.10
12
+ Description-Content-Type: text/markdown
13
+ Requires-Dist: rich>=13.0
14
+ Requires-Dist: requests==2.34.2
15
+ Requires-Dist: fivetran-connector-sdk>2.10.4
16
+
17
+ # fivetran-cli
18
+
19
+ The Fivetran CLI lets you manage your Fivetran account from the terminal. Supported operations include creating and updating connections, controlling schema settings, managing users and teams, deploying custom connectors, and more.
20
+
21
+ To learn more, see our [Fivetran CLI documentation](https://fivetran.com/docs/developer-resources/fivetran-cli)
22
+
23
+ ## **Install**
24
+
25
+ pip install fivetran-cli
26
+
27
+ Verify the installation:
28
+
29
+ fivetran --version
30
+
31
+ ## Requirements
32
+
33
+ - Python 3.10 or later
34
+ - A Fivetran account and API key for commands that communicate with Fivetran
35
+
36
+ ## Authentication
37
+
38
+ Fivetran API commands require a Base64-encoded API key. Set it as an environment variable:
39
+
40
+ export FIVETRAN_API_KEY="<base64-encoded-api-key>"
41
+
42
+ You can also pass the key to an individual command with `--api-key`:
43
+
44
+ fivetran beta connection list --api-key "<base64-encoded-api-key>"
45
+
46
+ See the [Fivetran REST API getting started guide](https://fivetran.com/docs/developer-resources/rest-api/getting-started) for instructions on creating and encoding an API key.
47
+
48
+ ## REST API commands
49
+
50
+ REST API operations use the following command structure:
51
+
52
+ fivetran beta <resource> <operation> [options]
53
+
54
+ For example:
55
+
56
+ List up to 10 connections:
57
+
58
+ fivetran beta connection list --limit 10
59
+
60
+ Retrieve one connection:
61
+
62
+ fivetran beta connection get --connection-id <connection-id>
63
+
64
+ Trigger a connection sync:
65
+
66
+ fivetran beta connection sync --connection-id <connection-id>
67
+
68
+ Use `--help` to discover the available resources, operations, and command-specific options:
69
+
70
+ fivetran beta --help
71
+ fivetran beta connection --help
72
+ fivetran beta connection list --help
73
+
74
+ ### Request payloads
75
+
76
+ Commands that accept a request body support inline JSON, a JSON file, or standard input:
77
+
78
+ fivetran beta connection create --config '{"group_id":"<group-id>","service":"<service>"}'
79
+ fivetran beta connection create --config-file connection.json
80
+
81
+ Refer to the [Fivetran REST API reference](https://fivetran.com/docs/developer-resources/rest-api) for the fields required by each operation.
82
+
83
+ ## Output options
84
+
85
+ REST API commands produce readable terminal output by default. The following options control how successful results are displayed:
86
+
87
+ | Option | Description |
88
+ | --- | --- |
89
+ | `--output text` | Use formatted terminal output. This is the default. |
90
+ | `--output json` | Write the complete response as JSON. |
91
+ | `--fields id,service` | Display only the selected fields or columns. |
92
+ | `--all-columns` | Show all columns instead of the default 8. |
93
+ | `--output-file <path>` | Write successful output to a file instead of stdout. |
94
+
95
+ Examples:
96
+
97
+ Return machine-readable output:
98
+
99
+ fivetran beta connection list --output json
100
+
101
+ Select columns for a compact table:
102
+
103
+ fivetran beta connection list --fields id,service,schema
104
+
105
+ Write the complete response to a file:
106
+
107
+ fivetran beta connection list --output json --output-file connections.json
108
+
109
+ ## Connector SDK commands
110
+
111
+ Installing `fivetran-cli` also installs the Fivetran Connector SDK. Its commands remain available through the same `fivetran` executable:
112
+
113
+ Run a connector locally:
114
+
115
+ fivetran debug
116
+
117
+ Deploy a connector to Fivetran:
118
+
119
+ fivetran deploy
120
+
121
+ See the [Connector SDK getting started guide](https://fivetran.com/docs/connector-sdk/getting-started) and [Connector SDK CLI command reference](https://fivetran.com/docs/connector-sdk/getting-started/connector-sdk-commands) for details.
122
+
123
+ ## Help
124
+
125
+ Run the following command to see all installed commands, including commands provided by Connector SDK plugins:
126
+
127
+ fivetran --help
128
+
129
+ ## Maintenance
130
+
131
+ This package is actively maintained by Fivetran developers. Contact the [Fivetran Support team](https://support.fivetran.com/hc/en-us) for assistance.
@@ -0,0 +1,115 @@
1
+ # fivetran-cli
2
+
3
+ The Fivetran CLI lets you manage your Fivetran account from the terminal. Supported operations include creating and updating connections, controlling schema settings, managing users and teams, deploying custom connectors, and more.
4
+
5
+ To learn more, see our [Fivetran CLI documentation](https://fivetran.com/docs/developer-resources/fivetran-cli)
6
+
7
+ ## **Install**
8
+
9
+ pip install fivetran-cli
10
+
11
+ Verify the installation:
12
+
13
+ fivetran --version
14
+
15
+ ## Requirements
16
+
17
+ - Python 3.10 or later
18
+ - A Fivetran account and API key for commands that communicate with Fivetran
19
+
20
+ ## Authentication
21
+
22
+ Fivetran API commands require a Base64-encoded API key. Set it as an environment variable:
23
+
24
+ export FIVETRAN_API_KEY="<base64-encoded-api-key>"
25
+
26
+ You can also pass the key to an individual command with `--api-key`:
27
+
28
+ fivetran beta connection list --api-key "<base64-encoded-api-key>"
29
+
30
+ See the [Fivetran REST API getting started guide](https://fivetran.com/docs/developer-resources/rest-api/getting-started) for instructions on creating and encoding an API key.
31
+
32
+ ## REST API commands
33
+
34
+ REST API operations use the following command structure:
35
+
36
+ fivetran beta <resource> <operation> [options]
37
+
38
+ For example:
39
+
40
+ List up to 10 connections:
41
+
42
+ fivetran beta connection list --limit 10
43
+
44
+ Retrieve one connection:
45
+
46
+ fivetran beta connection get --connection-id <connection-id>
47
+
48
+ Trigger a connection sync:
49
+
50
+ fivetran beta connection sync --connection-id <connection-id>
51
+
52
+ Use `--help` to discover the available resources, operations, and command-specific options:
53
+
54
+ fivetran beta --help
55
+ fivetran beta connection --help
56
+ fivetran beta connection list --help
57
+
58
+ ### Request payloads
59
+
60
+ Commands that accept a request body support inline JSON, a JSON file, or standard input:
61
+
62
+ fivetran beta connection create --config '{"group_id":"<group-id>","service":"<service>"}'
63
+ fivetran beta connection create --config-file connection.json
64
+
65
+ Refer to the [Fivetran REST API reference](https://fivetran.com/docs/developer-resources/rest-api) for the fields required by each operation.
66
+
67
+ ## Output options
68
+
69
+ REST API commands produce readable terminal output by default. The following options control how successful results are displayed:
70
+
71
+ | Option | Description |
72
+ | --- | --- |
73
+ | `--output text` | Use formatted terminal output. This is the default. |
74
+ | `--output json` | Write the complete response as JSON. |
75
+ | `--fields id,service` | Display only the selected fields or columns. |
76
+ | `--all-columns` | Show all columns instead of the default 8. |
77
+ | `--output-file <path>` | Write successful output to a file instead of stdout. |
78
+
79
+ Examples:
80
+
81
+ Return machine-readable output:
82
+
83
+ fivetran beta connection list --output json
84
+
85
+ Select columns for a compact table:
86
+
87
+ fivetran beta connection list --fields id,service,schema
88
+
89
+ Write the complete response to a file:
90
+
91
+ fivetran beta connection list --output json --output-file connections.json
92
+
93
+ ## Connector SDK commands
94
+
95
+ Installing `fivetran-cli` also installs the Fivetran Connector SDK. Its commands remain available through the same `fivetran` executable:
96
+
97
+ Run a connector locally:
98
+
99
+ fivetran debug
100
+
101
+ Deploy a connector to Fivetran:
102
+
103
+ fivetran deploy
104
+
105
+ See the [Connector SDK getting started guide](https://fivetran.com/docs/connector-sdk/getting-started) and [Connector SDK CLI command reference](https://fivetran.com/docs/connector-sdk/getting-started/connector-sdk-commands) for details.
106
+
107
+ ## Help
108
+
109
+ Run the following command to see all installed commands, including commands provided by Connector SDK plugins:
110
+
111
+ fivetran --help
112
+
113
+ ## Maintenance
114
+
115
+ This package is actively maintained by Fivetran developers. Contact the [Fivetran Support team](https://support.fivetran.com/hc/en-us) for assistance.
@@ -0,0 +1,37 @@
1
+ [project]
2
+ name = "fivetran_cli"
3
+ dynamic = ["version"]
4
+ authors = [
5
+ { name="Fivetran", email="developers@fivetran.com" },
6
+ ]
7
+ description = "Command line wrapper for the Fivetran REST API and Connector SDK"
8
+ readme = "README.md"
9
+ requires-python = ">=3.10"
10
+ classifiers = [
11
+ "Programming Language :: Python :: 3",
12
+ "License :: OSI Approved :: MIT License",
13
+ "Operating System :: OS Independent",
14
+ ]
15
+ dependencies = [
16
+ "rich>=13.0",
17
+ "requests==2.34.2",
18
+ "fivetran-connector-sdk>2.10.4",
19
+ ]
20
+
21
+ [project.scripts]
22
+ fivetran = "fivetran_cli:main"
23
+
24
+ [project.urls]
25
+ Homepage = "https://fivetran.com"
26
+ Github = "https://github.com/fivetran/engineering"
27
+
28
+ [build-system]
29
+ requires = ["setuptools>=61.0"]
30
+ build-backend = "setuptools.build_meta"
31
+
32
+ [tool.setuptools.packages.find]
33
+ where = ["src"]
34
+ namespaces = true
35
+
36
+ [tool.setuptools.dynamic]
37
+ version = {attr = "fivetran_cli.__version__"}
@@ -0,0 +1,266 @@
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
+ # (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"
14
+
15
+ from fivetran_cli import telemetry_helper
16
+ from fivetran_cli.cli_utils.dispatch.timeout import cancel_command_timeout, command_timed_out, install_command_timeout
17
+ from fivetran_cli.cli_utils.parser import build_parser, resolve_output_format, validate_fields, validate_filters
18
+ from fivetran_cli.cli_parser import discover_plugins, first_command_token
19
+ from fivetran_cli.constants import COMMAND_TIMEOUT, FIVETRAN_CLI_COMMANDS, UNKNOWN_FIELDS_ERROR_PREFIX
20
+ from fivetran_cli.display.error_output import emit_error
21
+ from fivetran_cli.display.output import emit_output, emit_raw_json, ensure_writable_parent
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 _execute_command(
176
+ args: argparse.Namespace,
177
+ stdout: TextIO,
178
+ stderr: TextIO,
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."""
185
+ operation_completed = False
186
+ payload = None
187
+ client: FivetranClient | None = None
188
+ try:
189
+ _validate_flags_before_execution(args)
190
+ config = resolve_config(args)
191
+ require_api_key(config)
192
+ client = FivetranClient(config, stderr=stderr)
193
+
194
+ install_command_timeout(COMMAND_TIMEOUT, stderr)
195
+
196
+ args._stdout = stdout
197
+ args._stderr = stderr
198
+
199
+ try:
200
+ payload = args.handler(args, client)
201
+ operation_completed = True
202
+ emit_output(payload, args=args, stdout=stdout)
203
+ return 0, 0
204
+ finally:
205
+ cancel_command_timeout()
206
+
207
+ except KeyboardInterrupt as exc:
208
+ if not command_timed_out():
209
+ stderr.write("\nfivetran: interrupted\n")
210
+ return 1, _telemetry_exit_code(exc)
211
+
212
+ except FivetranPartialResultError as exc:
213
+ # Pagination stopped early on a malformed page — still a failure
214
+ # (exit non-zero), but any data collected so far is still shown.
215
+ emit_error(exc, args=args, stderr=stderr)
216
+ if exc.partial_data is not None:
217
+ try:
218
+ emit_output(exc.partial_data, args=args, stdout=stdout)
219
+ except Exception as render_exc:
220
+ stderr.write(
221
+ f"fivetran: failed to render partial results: "
222
+ f"{type(render_exc).__name__}: {render_exc}\n"
223
+ )
224
+ return 1, _telemetry_exit_code(exc)
225
+
226
+ except FivetranCliError as exc:
227
+ emit_error(exc, args=args, stderr=stderr, operation_completed=operation_completed)
228
+ if operation_completed and not str(exc).startswith(UNKNOWN_FIELDS_ERROR_PREFIX):
229
+ emit_raw_json(payload, stdout)
230
+ return 1, _telemetry_exit_code(exc)
231
+
232
+ except Exception as exc:
233
+ stderr.write(f"fivetran: unexpected error: {type(exc).__name__}: {exc}\n")
234
+ return 1, _telemetry_exit_code(exc)
235
+
236
+ finally:
237
+ if client is not None:
238
+ client.close()
239
+
240
+
241
+ def _validate_output_destination(args: argparse.Namespace) -> None:
242
+ """
243
+ Fail fast, before the command handler runs, if --output-file points to a
244
+ path we won't be able to write to. This only checks permissions/existence.
245
+ """
246
+ output_file: str | None = getattr(args, "output_file", None)
247
+ if output_file is None:
248
+ return
249
+ if not output_file.strip():
250
+ raise FivetranCliError("--output-file cannot be empty")
251
+ if output_file.endswith("/") or (os.sep != "/" and output_file.endswith(os.sep)):
252
+ raise FivetranCliError(f"Cannot open output file '{output_file}': Path ends with a directory separator")
253
+
254
+ path = Path(output_file)
255
+
256
+ if path.exists() and path.is_dir():
257
+ raise FivetranCliError(f"Cannot open output file '{output_file}': Is a directory")
258
+
259
+ # Resolve output_file to its real path first: if it's a symlink, this is
260
+ # the symlink target's directory (what mkstemp() actually writes into);
261
+ # otherwise it's just output_file's own parent directory.
262
+ ensure_writable_parent(os.path.realpath(output_file))
263
+
264
+
265
+ if __name__ == "__main__":
266
+ raise SystemExit(main())
@@ -0,0 +1,19 @@
1
+ """Direct fivetran_cli CLI entrypoint."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import sys
6
+ from collections.abc import Sequence
7
+
8
+
9
+ def main(argv: Sequence[str] | None = None):
10
+ """Run the fivetran_cli CLI directly, optionally with an explicit argv."""
11
+ original_argv = list(sys.argv)
12
+ if argv is not None:
13
+ sys.argv = [original_argv[0] if original_argv else "fivetran", *argv]
14
+ try:
15
+ from fivetran_cli import main as cli_main
16
+
17
+ return cli_main()
18
+ finally:
19
+ sys.argv = original_argv
@@ -0,0 +1,71 @@
1
+ import argparse
2
+ import sys
3
+ from dataclasses import dataclass
4
+ from importlib.metadata import entry_points
5
+
6
+ from fivetran_cli.constants import FIVETRAN_CLI_COMMANDS, PLUGIN_GROUP
7
+ from fivetran_cli.plugin_api import FivetranCliPlugin
8
+
9
+
10
+ @dataclass(frozen=True)
11
+ class PluginMatch:
12
+ plugin_name: str
13
+ plugin: FivetranCliPlugin
14
+ description: str
15
+
16
+
17
+ def discover_plugins() -> dict[str, PluginMatch]:
18
+ """Returns {command_name: PluginMatch} for every command claimed by a
19
+ registered fivetran_cli.plugins entry point. A plugin that fails to load,
20
+ or raises while listing its commands, is skipped rather than crashing the CLI.
21
+ """
22
+ registry = {}
23
+ for entry_point in entry_points(group=PLUGIN_GROUP):
24
+ try:
25
+ plugin = entry_point.load()
26
+ commands = plugin.get_commands()
27
+ except Exception as exc:
28
+ print(f"fivetran: warning: plugin '{entry_point.name}' failed to load: {exc}", file=sys.stderr)
29
+ continue
30
+ for command, description in commands.items():
31
+ existing = registry.get(command)
32
+ if existing is not None and existing.plugin_name != entry_point.name:
33
+ print(
34
+ f"fivetran: warning: command '{command}' is claimed by both "
35
+ f"'{existing.plugin_name}' and '{entry_point.name}'; using '{existing.plugin_name}'",
36
+ file=sys.stderr,
37
+ )
38
+ continue
39
+ registry[command] = PluginMatch(entry_point.name, plugin, description)
40
+ return registry
41
+
42
+
43
+ def first_command_token(argv: list[str]) -> str | None:
44
+ """Returns the first non-flag token in argv.
45
+
46
+ fivetran_cli follows connector_sdk's own convention: the command always
47
+ comes first, and every option (global or command-specific) comes after it
48
+ (e.g. `fivetran deploy --api-key KEY`, never `fivetran --api-key KEY deploy`).
49
+ A value-taking flag placed before the command is not supported and its
50
+ value is misread as the command — the same failure mode connector_sdk's
51
+ own intercept_unknown_command() has, so a misplaced flag fails consistently
52
+ however it's routed.
53
+ """
54
+ return next((token for token in argv if not token.startswith("-")), None)
55
+
56
+
57
+ def create_help_parser(plugins: dict[str, PluginMatch]) -> argparse.ArgumentParser:
58
+ return argparse.ArgumentParser(
59
+ prog="fivetran", allow_abbrev=False, add_help=True,
60
+ usage="fivetran <command> [options]",
61
+ description="Command line wrapper for the Fivetran REST API and Connector SDK.",
62
+ epilog=_commands_epilog(plugins),
63
+ formatter_class=argparse.RawDescriptionHelpFormatter)
64
+
65
+
66
+ def _commands_epilog(plugins: dict[str, PluginMatch]) -> str:
67
+ all_commands = dict(FIVETRAN_CLI_COMMANDS)
68
+ all_commands.update({name: match.description for name, match in plugins.items()})
69
+ width = max(len(name) for name in all_commands)
70
+ lines = "\n".join(f" {name:<{width}} {description}" for name, description in sorted(all_commands.items()))
71
+ return f"commands:\n{lines}"