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

snowflake_cli-3.20.0/AGENTS.md

@@ -0,0 +1,28 @@
+<!--
+ 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.
+ -->
+
+# Agent Instructions
+
+Before writing any code, read each of the following guides in full:
+
+- [CONTRIBUTING.md](CONTRIBUTING.md)
+- [docs/contributing/adding-commands.md](docs/contributing/adding-commands.md)
+- [docs/contributing/conventions.md](docs/contributing/conventions.md)
+- [docs/contributing/lifecycle.md](docs/contributing/lifecycle.md)
+- [docs/contributing/testing.md](docs/contributing/testing.md)
+- [docs/contributing/process.md](docs/contributing/process.md)
+
+All requirements in those guides are mandatory, unless explicitly marked otherwise.

snowflake_cli-3.20.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+<!--
+ 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
+
+- **Adding commands**: [docs/contributing/adding-commands.md](docs/contributing/adding-commands.md)
+  — design sign-off, plugin structure, registration, return types, destructive commands
+- **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)
+  — SQL safety, secrets, file access, terminal output, error handling, imports, logging, user-visible output
+- **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.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: snowflake-cli
-Version: 3.18.0
+Version: 3.20.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
@@ -237,7 +237,7 @@ Requires-Dist: requests==2.33.0
 Requires-Dist: requirements-parser==0.13.0
 Requires-Dist: rich==14.0.0
 Requires-Dist: setuptools==80.8.0
-Requires-Dist: snowflake-connector-python[secure-local-storage]==4.5.0
+Requires-Dist: snowflake-connector-python[secure-local-storage]==4.6.0
 Requires-Dist: snowflake-core==1.10.0
 Requires-Dist: snowflake-snowpark-python==1.41.0
 Requires-Dist: tomlkit==0.13.3
@@ -249,8 +249,10 @@ Requires-Dist: coverage==7.10.4; extra == 'development'
 Requires-Dist: factory-boy==3.3.3; extra == 'development'
 Requires-Dist: faker==37.4.0; extra == 'development'
 Requires-Dist: pre-commit>=3.5.0; extra == 'development'
+Requires-Dist: pytest-cov==6.0.0; extra == 'development'
 Requires-Dist: pytest-httpserver==1.1.3; extra == 'development'
 Requires-Dist: pytest-randomly==3.16.0; extra == 'development'
+Requires-Dist: pytest-xdist==3.6.1; extra == 'development'
 Requires-Dist: pytest==8.4.1; extra == 'development'
 Requires-Dist: syrupy==4.9.1; extra == 'development'
 Requires-Dist: uv==0.10.9; extra == 'development'
@@ -340,3 +342,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.20.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.20.0}/RELEASE-NOTES.md

@@ -23,6 +23,33 @@
 ## Fixes and improvements
 
 
+# v3.20.0
+
+## Deprecations
+
+## New additions
+* Added a `--protocol` option (plus matching `SNOWFLAKE_PROTOCOL` env var and `protocol` config key) to `snow connection add` and the global connection overrides. This allows selecting `http` or `https` as the connection protocol without editing `config.toml`, which is primarily useful for local development against `http` deployments.
+* Added `snow helpers generate-project-schema` command to emit a JSON Schema for the `snowflake.yml` project definition file. The output follows [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/schema) and can be plugged into supported editors (e.g. VS Code via the YAML extension) or CI pipelines to get completion and to catch structural mistakes (unknown keys, wrong types, missing required fields) before a deploy. The schema is generated from the CLI's own models, so some cross-field and semantic checks are still only applied at load/deploy time. Use `--definition-version` to select the project definition version (`1`, `1.1`, or `2`; defaults to `2`) and `--output-file`/`-o` to write the schema to a file.
+
+## Fixes and improvements
+* Fixed `TooManyFilesError` during `snow streamlit deploy` when `main_file` is a descendant of a directory listed in `artifacts`.
+* Upgraded `snowflake-connector-python` from 4.5.0 to 4.6.0.
+* `snow dcm list-deployments` and `snow dcm drop-deployment` now wrap the project name in `IDENTIFIER(...)`, matching every other DCM subcommand. Fully-qualified and quoted project names are now handled consistently.
+* Fixed `snow sql` table output rendering as a series of `|` characters when selecting many columns into a non-terminal destination (e.g. piped or redirected output).
+* `get_account_identifier()` and `snow spcs service build-image` now raise a clear, user-visible error when `CURRENT_ORGANIZATION_NAME()` / `CURRENT_ACCOUNT_NAME()` return no row or a NULL value, instead of a cryptic `TypeError: 'NoneType' object is not subscriptable` / `AttributeError: 'NoneType' object has no attribute 'lower'`.
+* `snow app setup` and `snow app deploy` now verify the current role can deploy to the account-configured destination (the `DEFAULT_SNOWFLAKE_APPS_DESTINATION_DATABASE` / `DEFAULT_SNOWFLAKE_APPS_DESTINATION_SCHEMA` account defaults) before using it. When the role is missing the required privileges, the commands fall back to your personal database — as if no account default were set — and print a warning listing the missing grants and pointing you to your account administrator.
+
+
+# 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.20.0/docs/contributing/adding-commands.md

@@ -0,0 +1,235 @@
+<!--
+ 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.
+ -->
+
+# Adding Commands
+
+## Design sign-off before writing code
+
+Before implementing any change to the user-facing interface — new commands,
+command groups, arguments, options, or output format — get maintainer sign-off.
+
+**What sign-off covers:**
+
+- Command and subcommand names
+- Flag names, types, and defaults
+- Lifecycle stage (PrPr, PuPr, or GA) — see [lifecycle.md](lifecycle.md)
+- Output format and result type
+- Where the command lives (new group or existing one)
+
+**What sign-off does not cover:** implementation details inside the plugin
+directory — service/manager structure, helper functions, file layout. Those are
+yours to decide as long as they stay encapsulated within `_plugins/<your-plugin>/`
+and do not add to `api/` or `_app/`.
+
+**Where to get sign-off:** open a GitHub Issue describing the interface and tag a
+maintainer for review.
+
+---
+
+## Which case are you in?
+
+**Adding a command to an existing group** — skip to
+[Writing commands](#writing-commands). No registration changes needed.
+
+**New top-level command group** — read
+[Creating a command group](#creating-a-command-group) first, then
+[Registering the plugin](#registering-the-plugin).
+
+---
+
+## Creating a command group
+
+### Flat structure
+
+Use a flat layout when the group manages a single domain (one entity type or
+one set of related operations). `snow git` is the canonical example:
+
+```
+src/snowflake/cli/_plugins/<name>/
+    __init__.py
+    commands.py       # @app.command() definitions
+    manager.py        # business logic / Snowflake API calls
+    plugin_spec.py    # pluggy hook — wires commands into the CLI
+```
+
+`commands.py` creates the `SnowTyperFactory` app and defines all commands on it.
+See `src/snowflake/cli/_plugins/git/` as a reference.
+
+### Nested structure
+
+Use a nested layout when the group is a capability or platform that hosts
+multiple independent entity types — not just because the group is large. `snow spcs`
+hosts compute pools, services, image registries, and image repositories as
+separate sub-groups because each is a distinct entity type with its own lifecycle.
+
+```
+src/snowflake/cli/_plugins/<name>/
+    __init__.py           # assembles the top-level app from sub-typers
+    plugin_spec.py
+    <entity-a>/
+        commands.py
+        manager.py
+    <entity-b>/
+        commands.py
+        manager.py
+```
+
+`__init__.py` creates the parent app and adds each sub-typer:
+
+```python
+from snowflake.cli._plugins.<name>.<entity_a>.commands import app as entity_a_app
+from snowflake.cli.api.commands.snow_typer import SnowTyperFactory
+
+app = SnowTyperFactory(name="<name>", help="...")
+app.add_typer(entity_a_app)
+```
+
+See `src/snowflake/cli/_plugins/spcs/__init__.py` as a reference.
+
+Start flat. Move to nested only when a second distinct entity type is needed —
+the nesting should reflect domain structure, not anticipate it.
+
+---
+
+## Registering the plugin
+
+Two files need to change for a new top-level group.
+
+**`plugin_spec.py`** — the pluggy hook that attaches the app to the CLI:
+
+```python
+from snowflake.cli._plugins.<name> import commands
+from snowflake.cli.api.plugins.command import (
+    SNOWCLI_ROOT_COMMAND_PATH,
+    CommandSpec,
+    CommandType,
+    plugin_hook_impl,
+)
+
+@plugin_hook_impl
+def command_spec():
+    return CommandSpec(
+        parent_command_path=SNOWCLI_ROOT_COMMAND_PATH,
+        command_type=CommandType.COMMAND_GROUP,
+        typer_instance=commands.app.create_instance(),
+    )
+```
+
+For a nested layout, `app` is defined in `__init__.py`, so import it from the
+package directly:
+
+```python
+from snowflake.cli._plugins.<name> import app
+...
+    typer_instance=app.create_instance(),
+```
+
+See `src/snowflake/cli/_plugins/spcs/plugin_spec.py` as a reference.
+
+**`src/snowflake/cli/_app/commands_registration/builtin_plugins.py`** — add an
+import and a dict entry in `get_builtin_plugin_name_to_plugin_spec()`:
+
+```python
+from snowflake.cli._plugins.<name> import plugin_spec as <name>_plugin_spec
+
+def get_builtin_plugin_name_to_plugin_spec():
+    plugin_specs = {
+        ...
+        "<name>": <name>_plugin_spec,
+    }
+    return plugin_specs
+```
+
+The plugin name string is what appears in `snow --help`. Pick a short,
+lowercase, hyphen-separated name that matches the `SnowTyperFactory` `name=`
+argument.
+
+---
+
+## Writing commands
+
+Every command must return a `CommandResult` subtype. Never call `print()`
+directly — use `cli_console` for progress messages (see
+[conventions.md](conventions.md)) and return a `CommandResult` for the
+command's final output.
+
+The function's docstring becomes the command's `--help` text. Write it as a
+short, imperative sentence describing what the command does from the user's
+perspective:
+
+```python
+@app.command()
+def create(name: str):
+    """Creates a new table."""
+    ...
+```
+
+### Return types
+
+All types are in `src/snowflake/cli/api/output/types.py`:
+
+| Type | When to use |
+|------|-------------|
+| `MessageResult` | Plain string confirmation — "Statement executed successfully." |
+| `QueryResult` | Multi-row cursor result (SHOW, SELECT returning many rows) |
+| `SingleQueryResult` | Single-row cursor result (DESCRIBE, CREATE ... RETURN ...) |
+| `CollectionResult` | Iterable of dicts with no cursor (locally constructed results) |
+| `ObjectResult` | Single dict with no cursor |
+
+Other specialized types (`MultipleResults`, `StreamResult`, `EmptyResult`) exist for less common cases — see `src/snowflake/cli/api/output/types.py`.
+
+### Lifecycle and visibility
+
+New commands start in PrPr behind a feature flag. See [lifecycle.md](lifecycle.md)
+for the `SnowTyperFactory` and `@app.command()` patterns that hide commands
+until the flag is enabled, and for the PrPr → PuPr → GA progression.
+
+### Destructive commands
+
+Commands that modify or delete existing resources should use `ForceOption` and
+`InteractiveOption` from `snowflake.cli.api.commands.flags`.
+
+Behavior matrix:
+
+| `--force` | `--interactive` | Result |
+|-----------|-----------------|--------|
+| unset | False (non-interactive default, e.g. CI or piped input) | Abort — safe default for scripts |
+| unset | True (interactive terminal default) | Prompt the user |
+| set | either | Proceed without prompting |
+
+### Testing
+
+Every new command needs comprehensive unit and integration tests covering the
+happy path and the main error paths. See [testing.md](testing.md) for the
+`runner` fixture, snapshot tests, and how to test feature-flagged commands.
+
+## Reusable code in `src/snowflake/cli/api/`
+
+Before writing new utilities, check `src/snowflake/cli/api/` — it contains
+shared flags, helpers, and base classes that most plugins rely on:
+
+| Module | What it provides |
+|--------|-----------------|
+| `commands/flags.py` | Standard flags: `ForceOption`, `InteractiveOption`, `OutputFormatOption`, `PatternOption`, and others |
+| `commands/snow_typer.py` | `SnowTyperFactory` — the standard way to create a command group |
+| `output/types.py` | All `CommandResult` subtypes |
+| `identifiers.py` | `FQN` — fully-qualified name handling (see [conventions.md](conventions.md)) |
+| `project/util.py` | `to_string_literal`, `identifier_to_show_like_pattern` |
+| `console/__init__.py` | `cli_console` for user-visible output |
+| `exceptions.py` | `CliError` subclasses |
+
+For commands that operate on Snowflake objects, check whether an `ObjectManager`
+subclass already exists for your object type before writing raw SQL queries.