snowflake-cli 3.18.0__tar.gz → 3.19.0__tar.gz

snowflake_cli-3.19.0/CONTRIBUTING.md

@@ -0,0 +1,111 @@
+<!--
+ Copyright (c) 2024 Snowflake Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+# Contributing to Snowflake CLI
+
+## Detailed guides
+
+- **Command lifecycle and feature flags**: [docs/contributing/lifecycle.md](docs/contributing/lifecycle.md)
+  — PrPr/PuPr/GA rules, feature flag mechanics, release notes format
+- **Code conventions**: [docs/contributing/conventions.md](docs/contributing/conventions.md)
+  — security patterns, error handling, imports
+- **Testing**: [docs/contributing/testing.md](docs/contributing/testing.md)
+  — unit tests, snapshots, fixtures, feature flag test helpers
+- **Process**: [docs/contributing/process.md](docs/contributing/process.md)
+  — merge model, commit format, reviewer etiquette
+- **Remote debugging**: [docs/contributing/remote-debugging.md](docs/contributing/remote-debugging.md)
+  — debugging with PyCharm or IntelliJ
+
+## Quick start
+
+```bash
+pip install -U hatch==1.15.1 virtualenv==20.39.1
+hatch shell
+hatch run test
+```
+
+`hatch shell` spawns a new shell with the virtual environment active and the CLI
+installed in editable mode. Press `^D` to exit.
+
+To also activate pre-commit hooks (required before your first commit):
+
+```bash
+hatch run pre-commit install
+```
+
+## Reporting bugs and requesting features
+
+File a [GitHub Issue](https://github.com/snowflakedb/snowflake-cli/issues). Use
+the issue templates — they collect the information needed to act on the report
+quickly.
+
+## How to contribute code
+
+Fork the repo and submit a pull request from your fork. All forks of
+`snowflake-cli` are publicly visible on GitHub.
+
+Keep your fork up to date by rebasing onto upstream rather than merging:
+
+```bash
+git remote add sfcli https://github.com/snowflakedb/snowflake-cli.git
+git fetch sfcli
+git checkout <your-branch>
+git rebase sfcli/main
+```
+
+A maintainer will review and merge your PR after approval.
+
+## Development environment
+
+We use [hatch](https://hatch.pypa.io/latest/) to manage development environments.
+The supported Python versions are listed in `pyproject.toml` under the
+`Programming Language :: Python` classifiers. We recommend
+[pyenv](https://github.com/pyenv/pyenv) for managing Python versions locally.
+
+Do not use language features that are unavailable in the minimum supported
+version — code must run on all versions in the supported range.
+
+```bash
+pip install -U hatch==1.15.1 virtualenv==20.39.1
+hatch run pre-commit install
+```
+
+To create an environment pinned to a specific Python version:
+
+```bash
+hatch env create local.py3.10
+```
+
+To list all available environments:
+
+```bash
+hatch env show
+```
+
+## Running tests
+
+```bash
+hatch run test                 # unit tests
+hatch run integration:test     # integration tests (requires Snowflake connection)
+```
+
+See [docs/contributing/testing.md](docs/contributing/testing.md) for snapshots,
+fixtures, markers, and integration test environment setup.
+
+## Before submitting a PR
+
+The PR template contains a checklist. Complete it honestly — reviewers check
+every item and CI enforces some of them.

{snowflake_cli-3.18.0 → snowflake_cli-3.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-cli
-Version: 3.18.0
+Version: 3.19.0
 Summary: Snowflake CLI
 Project-URL: Source code, https://github.com/snowflakedb/snowflake-cli
 Project-URL: Bug Tracker, https://github.com/snowflakedb/snowflake-cli/issues
@@ -340,3 +340,5 @@ You should now be able to run `snow` and get the CLI message.
 
 Have a feature idea? Running into a bug? Want to contribute? We'd love to hear from you!
 Please open or review issues, open pull requests, or reach out to us on <developers@snowflake.com>
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.

{snowflake_cli-3.18.0 → snowflake_cli-3.19.0}/README.md

@@ -81,3 +81,5 @@ You should now be able to run `snow` and get the CLI message.
 
 Have a feature idea? Running into a bug? Want to contribute? We'd love to hear from you!
 Please open or review issues, open pull requests, or reach out to us on <developers@snowflake.com>
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and contribution guidelines.

{snowflake_cli-3.18.0 → snowflake_cli-3.19.0}/RELEASE-NOTES.md

@@ -23,6 +23,16 @@
 ## Fixes and improvements
 
 
+# v3.19.0
+
+## Deprecations
+
+## New additions
+* Added `--local-only` flag to `snow sql`. When set, `!source` and `!load` directives that reference `http://` or `https://` URLs are rejected instead of fetched, restricting the command to local SQL files. Useful for running SQL in environments where outbound network access from the CLI is undesirable, or when SQL inputs should be reviewed locally before execution. Local file `!source`/`!load` are unaffected. The flag also applies to the interactive REPL and to files reached transitively via nested `!source`.
+
+## Fixes and improvements
+
+
 # v3.18.0
 
 ## Deprecations

snowflake_cli-3.19.0/docs/contributing/conventions.md

@@ -0,0 +1,219 @@
+<!--
+ Copyright (c) 2024 Snowflake Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+# Code Conventions
+
+
+## SQL safety
+
+Never interpolate user-supplied values or config values directly into SQL strings.
+Use the appropriate helper depending on whether the value is an **object identifier**
+or a **string value**.
+
+### Object identifiers (table names, stage names, schema names, …)
+
+Use `FQN` and its `.sql_identifier` property, which wraps the identifier in
+`IDENTIFIER('...')` so Snowflake resolves it correctly.
+
+When the components come from separate variables, use the constructor directly —
+never f-string them together before passing to `FQN`:
+
+```python
+# WRONG — f-string composed before any sanitisation
+cursor.execute(f"CREATE TABLE {database}.{schema}.{table_name} ...")
+
+# ALSO WRONG — f-string still composes before FQN sees the parts
+from snowflake.cli.api.identifiers import FQN
+fqn = FQN.from_string(f"{database}.{schema}.{table_name}")
+cursor.execute(f"CREATE TABLE {fqn.sql_identifier} ...")
+
+# CORRECT — pass each component individually
+from snowflake.cli.api.identifiers import FQN
+fqn = FQN(database=database, schema=schema, name=table_name)
+cursor.execute(f"CREATE TABLE {fqn.sql_identifier} ...")
+```
+
+`FQN.from_string()` is safe when the full dotted name comes from a single
+trusted source (e.g. already-validated CLI argument). Use the constructor
+whenever the components arrive separately.
+
+### String values (LIKE patterns, CALL arguments, stage paths, string parameters)
+
+Use `to_string_literal()` from `snowflake.cli.api.project.util`, which produces
+a properly escaped single-quoted string literal:
+
+```python
+# WRONG
+cursor.execute(f"SHOW DATABASES LIKE {database}")
+
+# CORRECT
+from snowflake.cli.api.project.util import to_string_literal
+cursor.execute(f"SHOW DATABASES LIKE {to_string_literal(database)}")
+```
+
+When doing SHOW … LIKE to look up a **specific object by name** (not a user
+search pattern), use `identifier_to_show_like_pattern()` instead. It also
+escapes `%` and `_` wildcard characters so that `'my_db'` does not accidentally
+match `'myXdb'`:
+
+```python
+from snowflake.cli.api.project.util import identifier_to_show_like_pattern
+cursor.execute(f"SHOW DATABASES LIKE {identifier_to_show_like_pattern(name)}")
+```
+
+### Bind parameters
+
+For scalar values in queries and write statements (`SELECT`, `INSERT`, `UPDATE`,
+`DELETE`), prefer bind parameters — they are the safest option and require no
+escaping:
+
+```python
+cursor.execute("SELECT * FROM my_table WHERE id = %s", (user_id,))
+```
+
+Bind parameters are not supported for DDL or `SHOW` statements. Use
+`to_string_literal` or `identifier_to_show_like_pattern` there instead.
+
+## Terminal output safety
+
+Never print values from Snowflake server responses or user config directly to the
+terminal. They may contain ANSI escape sequences or terminal control characters.
+
+```python
+# WRONG
+cc.step(f"Object name: {server_response['name']}")
+
+# CORRECT
+from snowflake.cli.api.sanitizers import sanitize_for_terminal
+cc.step(f"Object name: {sanitize_for_terminal(server_response['name'])}")
+```
+
+## Error handling
+
+The project is migrating from `ClickException` to typed `CliError` subclasses.
+Existing `ClickException` usages are legacy — do not imitate them.
+
+All new code must use `CliError` or one of its subclasses from
+`snowflake.cli.api.exceptions`:
+
+```python
+# WRONG
+from click import ClickException
+raise ClickException("Something went wrong")
+
+# CORRECT
+from snowflake.cli.api.exceptions import CliError  # or a more specific subclass
+raise CliError("Something went wrong")
+```
+
+Check `src/snowflake/cli/api/exceptions.py` for available subclasses before
+raising a generic error.
+
+Error messages should describe what went wrong and, where possible, what the
+user can do about it:
+
+```python
+# WRONG — states what happened but not what to do
+raise CliError(f"File {path} not found")
+
+# CORRECT — states what happened and how to fix it
+raise CliError(f"File {path} not found. Check the path and try again.")
+```
+
+## Imports
+
+Prefer top-of-file imports. Local imports inside functions are acceptable only
+when unavoidable (e.g. to break circular imports or for config-time deferred
+loading), not as a general convenience.
+
+```python
+# PREFERRED
+from snowflake.cli.api.identifiers import FQN
+
+def my_command():
+    ...
+
+# ACCEPTABLE only when a top-level import causes issues
+def my_command():
+    from snowflake.cli.api.identifiers import FQN
+    ...
+```
+
+## Logging
+
+Use `logging.getLogger(__name__)` for diagnostic messages that help with
+troubleshooting but are not user-facing:
+
+```python
+import logging
+
+log = logging.getLogger(__name__)
+
+def my_function():
+    log.debug("Starting operation with params: %s", params)
+```
+
+Use `%`-style formatting, not f-strings:
+
+```python
+# WRONG
+log.debug(f"Processing {len(items)} items")
+
+# CORRECT
+log.debug("Processing %s items", len(items))
+```
+
+Never log sensitive values such as passwords, tokens, or private keys. Connection
+parameters from config may contain credentials — log identifiers (account, user,
+role) but not secrets.
+
+Use `cli_console` (see below) for messages the user should see during normal
+operation. The two are complementary: `cli_console` drives the interactive
+experience, `logging` provides the paper trail visible in debug output.
+
+## User-visible output
+
+Use `cli_console` from `snowflake.cli.api.console` for all user-visible output.
+Never use `print()` directly. `cli_console` respects `--silent` automatically.
+
+```python
+from snowflake.cli.api.console import cli_console as cc
+
+cc.step("Doing something...")          # regular progress line
+cc.warning("Something looks off")      # warning line
+
+with cc.phase("Building...", "Done."): # grouped output block
+    cc.step("Step A")
+    cc.step("Step B")
+```
+
+## Linting and formatting
+
+Linting and formatting run automatically on commit via pre-commit. Most issues
+are fixed automatically; the rest are reported inline. The active hooks and
+their pinned versions are defined in `.pre-commit-config.yaml`.
+
+Install the hooks once and they run automatically on every commit:
+
+```bash
+hatch run pre-commit install
+```
+
+To run them manually across the whole repo:
+
+```bash
+hatch run pre-commit run --all-files
+```

snowflake_cli-3.19.0/docs/contributing/lifecycle.md

@@ -0,0 +1,270 @@
+<!--
+ Copyright (c) 2024 Snowflake Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+ -->
+
+# Command Lifecycle: PrPr, PuPr, and GA
+
+Commands, command groups, flags, and arguments each progress through their own
+lifecycle independently. A command group can be GA while a specific command
+within it is still in PuPr, and a specific flag on that command can be in PrPr.
+
+By default, users must never see non-GA features. PrPr and PuPr features must
+always require an explicit opt-in (via feature flag) before they are visible.
+
+## Stage definitions
+
+### PrPr (Private Preview)
+
+- Feature is hidden behind a feature flag (default `False`)
+- No release note entry required
+- Breaking changes are acceptable
+- No backward compatibility obligation
+
+### PuPr (Public Preview)
+
+- Feature remains behind its feature flag — not visible to users who have not opted in
+- One-line release note required when entering PuPr (under `## New additions`):
+  ```
+  * <name> is now available in preview.
+  ```
+- Breaking changes are no longer acceptable from this point
+- Full backward compatibility rules apply going forward
+
+### GA (Generally Available)
+
+- Feature flag removed from `src/snowflake/cli/api/feature_flags.py`
+- `is_hidden` / `hidden=` stripped from the feature
+- Explicit release note required when entering GA (under `## New additions`):
+  ```
+  * <name> is now generally available.
+  ```
+- Full backward compatibility rules apply
+
+## Feature flags
+
+Flags are defined in `src/snowflake/cli/api/feature_flags.py` as entries in the
+`FeatureFlag` enum:
+
+```python
+class FeatureFlag(FeatureFlagMixin):
+    ENABLE_MY_FEATURE = BooleanFlag("ENABLE_MY_FEATURE", False)
+```
+
+### Enabling a flag
+
+Flags can be set in two ways:
+
+**Environment variable** — `SNOWFLAKE_CLI_FEATURES_<FLAG_NAME_UPPERCASE>`:
+```bash
+SNOWFLAKE_CLI_FEATURES_ENABLE_MY_FEATURE=true snow my-command
+```
+
+**`config.toml`** — under the `[cli.features]` section:
+```toml
+[cli.features]
+enable_my_feature = true
+```
+
+### Applying flags to features
+
+Flags can gate a command group, a single command, a specific argument, or any
+combination. The right scope depends on what you're hiding.
+
+**Hide an entire command group** (group absent from `snow --help`, but still
+callable by users who know the flag — useful for internal testing):
+```python
+from snowflake.cli.api.commands.snow_typer import SnowTyperFactory
+from snowflake.cli.api.feature_flags import FeatureFlag
+import typer
+
+app = SnowTyperFactory(
+    name="my-group",
+    is_hidden=FeatureFlag.ENABLE_MY_FEATURE.is_disabled,
+)
+```
+
+**Hide a single command** (command absent from `snow my-group --help`, still
+callable):
+```python
+@app.command(hidden=not FeatureFlag.ENABLE_MY_FEATURE.is_enabled())
+def my_command():
+    ...
+```
+
+**Hide a single option or argument**:
+```python
+@app.command()
+def my_command(
+    my_option: Optional[str] = typer.Option(
+        None,
+        hidden=not FeatureFlag.ENABLE_MY_FEATURE.is_enabled(),
+    ),
+):
+    ...
+```
+
+**Gate a feature so it cannot be invoked at all** (use sparingly — only when
+running without the flag would be unsafe or meaningless):
+```python
+@app.command(is_enabled=FeatureFlag.ENABLE_MY_FEATURE.is_enabled)
+def my_command():
+    ...
+```
+
+### Independent lifecycle example
+
+A command group, one of its commands, and a flag on that command can each be at
+a different lifecycle stage simultaneously:
+
+```python
+# Command group is GA — no feature flag
+app = SnowTyperFactory(name="my-group")
+
+# This command is PuPr — hidden unless flag is enabled
+@app.command(hidden=not FeatureFlag.ENABLE_MY_COMMAND.is_enabled())
+def my_command(
+    # This option is PrPr — hidden unless a second flag is enabled
+    experimental_option: Optional[str] = typer.Option(
+        None,
+        hidden=not FeatureFlag.ENABLE_MY_EXPERIMENTAL_OPTION.is_enabled(),
+    ),
+):
+    ...
+```
+
+## Transitioning between stages
+
+### PrPr → PuPr
+
+1. Add a release note entry under `## New additions`:
+   `* <name> is now available in preview.`
+2. No breaking changes from this point forward
+
+### PuPr → GA
+
+1. Remove the flag entry from `src/snowflake/cli/api/feature_flags.py`
+2. Remove `is_hidden=` / `hidden=` from the feature
+3. Add a release note entry under `## New additions`:
+   `* <name> is now generally available.`
+
+## Testing feature-flagged features
+
+Use `with_feature_flags` from `tests_common/feature_flag_utils.py`. Never set
+feature flag env vars directly in tests.
+
+```python
+from tests_common.feature_flag_utils import with_feature_flags
+from snowflake.cli.api.feature_flags import FeatureFlag
+
+@with_feature_flags({FeatureFlag.ENABLE_MY_FEATURE: True})
+def test_my_command(runner):
+    result = runner.invoke(["my-group", "my-command"])
+    assert result.exit_code == 0
+```
+
+## Snapshot tests and hidden features
+
+Snapshot tests capture all commands and options including hidden ones. Any
+change to a hidden feature — adding, removing, or renaming — requires
+regenerating snapshots even though the feature is not user-visible:
+
+```bash
+hatch run pytest tests/ --snapshot-update
+```
+
+Always review the `.ambr` diff in `tests/__snapshots__/` before committing.
+
+## Backward compatibility
+
+Once a feature reaches PuPr, the following are covered by the backward
+compatibility guarantee:
+
+- Command and subcommand names
+- Flag names (both long form `--flag` and short form `-f`)
+- Flag default values
+- `config.toml` fields
+- `snowflake.yml` schema fields
+
+Command output is **not** guaranteed — many commands return raw Snowflake server
+responses whose shape is outside CLI's control.
+
+Any change that breaks the above requires a `## Backward incompatibility` entry
+in `RELEASE-NOTES.md` and must not land in a minor version.
+
+## Deprecating commands and flags
+
+### Deprecating a command
+
+Mark the command with `deprecated=True`. Click will print a deprecation warning
+automatically when the command is invoked:
+
+```python
+@app.command(deprecated=True)
+def my_old_command():
+    ...
+```
+
+Add a release note entry under `## Deprecations`.
+
+### Deprecating a flag
+
+Use `deprecated_flag_callback` from `snowflake.cli.api.commands.flags` — do not
+roll your own callback:
+
+```python
+from snowflake.cli.api.commands.flags import deprecated_flag_callback
+
+@app.command()
+def my_command(
+    old_option: Optional[str] = typer.Option(
+        None,
+        callback=deprecated_flag_callback("Use --new-option instead."),
+    ),
+):
+    ...
+```
+
+Add a release note entry under `## Deprecations`.
+
+### Removal policy
+
+Deprecated commands and flags are not removed between minor versions. Removal
+may happen in a major version bump, but is not guaranteed to happen in the next
+one.
+
+## Release notes format
+
+The full release notes format and per-stage rules are in
+[`RELEASE-NOTES.md`](../../RELEASE-NOTES.md). The sections are:
+
+```markdown
+## Backward incompatibility
+## Deprecations
+## New additions
+## Fixes and improvements
+```
+
+All unreleased changes go under `# Unreleased version` at the top of the file.
+
+Entries should describe user-facing impact, not implementation details. Focus on
+what changed for the user, not how it was implemented.
+
+## CI enforcement
+
+A GitHub Actions workflow (`changelog.yaml`) checks that `RELEASE-NOTES.md` is
+modified on every PR targeting `main`. The check fails if the file is untouched.
+
+To skip the check for PRs that genuinely need no entry (e.g. pure test or
+documentation changes), apply the **`skip-release-notes`** label to the PR.