snowflake-cli-labs 2.5.0rc2__py3-none-any.whl → 2.6.0__py3-none-any.whl

snowflake/cli/api/utils/rendering.py

@@ -63,10 +63,31 @@ def _env_bootstrap(env: Environment) -> Environment:
     return env
 
 
+class IgnoreAttrEnvironment(Environment):
+    """
+    extend Environment class and ignore attributes during rendering.
+    This ensures that attributes of classes
+    do not get used during rendering (e.g. __class__, get, etc).
+    Only dict items can be used for rendering.
+    """
+
+    def getattr(self, obj, attribute):  # noqa: A003
+        try:
+            return obj[attribute]
+        except (TypeError, LookupError, AttributeError):
+            return self.undefined(obj=obj, name=attribute)
+
+    def getitem(self, obj, argument):
+        try:
+            return obj[argument]
+        except (AttributeError, TypeError, LookupError):
+            return self.undefined(obj=obj, name=argument)
+
+
 def get_snowflake_cli_jinja_env() -> Environment:
     _random_block = "___very___unique___block___to___disable___logic___blocks___"
     return _env_bootstrap(
-        Environment(
+        IgnoreAttrEnvironment(
             loader=loaders.BaseLoader(),
             keep_trailing_newline=True,
             variable_start_string=_YML_TEMPLATE_START,
@@ -81,7 +102,7 @@ def get_snowflake_cli_jinja_env() -> Environment:
 def get_sql_cli_jinja_env():
     _random_block = "___very___unique___block___to___disable___logic___blocks___"
     return _env_bootstrap(
-        Environment(
+        IgnoreAttrEnvironment(
             loader=loaders.BaseLoader(),
             keep_trailing_newline=True,
             variable_start_string="&{",
@@ -108,7 +129,7 @@ def jinja_render_from_file(
         None if file path is provided, else returns the rendered string.
     """
     env = _env_bootstrap(
-        Environment(
+        IgnoreAttrEnvironment(
             loader=loaders.FileSystemLoader(template_path.parent),
             keep_trailing_newline=True,
             undefined=StrictUndefined,

snowflake/cli/app/cli_app.py

@@ -30,6 +30,7 @@ from snowflake.cli.api.config import config_init
 from snowflake.cli.api.output.formats import OutputFormat
 from snowflake.cli.api.output.types import CollectionResult
 from snowflake.cli.api.secure_path import SecurePath
+from snowflake.cli.app import loggers
 from snowflake.cli.app.api_impl.plugin.plugin_config_provider_impl import (
     PluginConfigProviderImpl,
 )
@@ -88,6 +89,7 @@ def _commands_registration_callback(value: bool):
 @_commands_registration.before
 def _config_init_callback(configuration_file: Optional[Path]):
     config_init(configuration_file)
+    loggers.create_initial_loggers()
 
 
 @_commands_registration.before

snowflake/cli/app/commands_registration/command_plugins_loader.py

@@ -100,6 +100,10 @@ class CommandPluginsLoader:
         self._loaded_command_paths[
             loaded_plugin.command_spec.full_command_path
         ] = loaded_plugin
+
+        if self._is_external_plugin(loaded_plugin):
+            log.info("Loaded external plugin: %s", plugin_name)
+
         return loaded_plugin
 
     def _load_plugin_spec(
@@ -145,6 +149,10 @@ class CommandPluginsLoader:
             )
             return None
 
+    @staticmethod
+    def _is_external_plugin(plugin) -> bool:
+        return isinstance(plugin, LoadedExternalCommandPlugin)
+
 
 def load_only_builtin_command_plugins() -> List[LoadedCommandPlugin]:
     loader = CommandPluginsLoader()

snowflake/cli/app/dev/docs/commands_docs_generator.py

@@ -0,0 +1,100 @@
+# 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.
+
+from __future__ import annotations
+
+import logging
+from typing import List, Optional
+
+from click import Command
+from snowflake.cli.api.secure_path import SecurePath
+from snowflake.cli.app.dev.docs.template_utils import get_template_environment
+from typer.core import TyperArgument
+
+log = logging.getLogger(__name__)
+
+CMD_USAGE_TMPL = "usage.rst.jinja2"
+OVERVIEW_TMPL = "overview.rst.jinja2"
+
+
+def generate_command_docs(
+    root: SecurePath, command: Command, cmd_parts: Optional[List] = None
+):
+    """
+    Iterates recursively through commands info. Creates a file structure resembling
+    commands structure. For each terminal command creates a "usage" rst file.
+    """
+    if getattr(command, "hidden", False):
+        return
+
+    root.mkdir(exist_ok=True)
+    if cmd_parts is None:
+        _render_command_usage(command, root, cmd_parts, template_name=OVERVIEW_TMPL)
+
+    cmd_parts = cmd_parts or []
+    if hasattr(command, "commands"):
+        for command_name, command_info in command.commands.items():
+            path = root / command.name if command.name != "default" else root
+            generate_command_docs(path, command_info, [*cmd_parts, command_name])
+    else:
+        _render_command_usage(command, root, cmd_parts)
+
+
+def get_main_option(options: List[str]) -> str:
+    long_options = [option for option in options if option.startswith("--")]
+    if long_options:
+        return long_options[0]
+
+    short_options = [option for option in options if option.startswith("-")]
+    if short_options:
+        return short_options[0]
+
+    return ""
+
+
+def _render_command_usage(
+    command: Command,
+    root: SecurePath,
+    path: Optional[List] = None,
+    template_name: str = CMD_USAGE_TMPL,
+):
+    # This is end command
+    command_name = command.name
+    env = get_template_environment()
+    env.filters[get_main_option.__name__] = get_main_option
+    template = env.get_template(template_name)
+    arguments = []
+    options = []
+    for param in command.params:
+        if isinstance(param, TyperArgument):
+            arguments.append(param)
+        else:
+            options.append(param)
+
+    # RST files are presumed to be standalone pages in the docs with a matching item in the left nav.
+    # Included files, which these are, need to use the .txt extension.
+    file_path = root / f"usage-{command_name}.txt"
+    log.info("Creating %s", file_path)
+    with file_path.open("w+") as fh:
+        fh.write(
+            template.render(
+                {
+                    "help": command.help,
+                    "name": command_name,
+                    "options": options,
+                    "arguments": arguments,
+                    "path": path,
+                }
+            )
+        )

snowflake/cli/app/dev/docs/generator.py

@@ -15,80 +15,21 @@
 from __future__ import annotations
 
 import logging
-from pathlib import Path
-from typing import List, Optional
 
 from click import Command
-from jinja2 import Environment, FileSystemLoader
 from snowflake.cli.api.secure_path import SecurePath
-from typer.core import TyperArgument
+from snowflake.cli.app.dev.docs.commands_docs_generator import generate_command_docs
+from snowflake.cli.app.dev.docs.project_definition_docs_generator import (
+    generate_project_definition_docs,
+)
 
 log = logging.getLogger(__name__)
 
-CMD_USAGE_TMPL = "usage.rst.jinja2"
-OVERVIEW_TMPL = "overview.rst.jinja2"
 
-
-def generate_docs(root: SecurePath, command: Command, cmd_parts: Optional[List] = None):
+def generate_docs(root: SecurePath, command: Command):
     """
-    Iterates recursively through commands info. Creates a file structure resembling
-    commands structure. For each terminal command creates a "usage" rst file.
+    Generates documentation for each command, its options and for the project definition.
     """
-    if getattr(command, "hidden", False):
-        return
-
     root.mkdir(exist_ok=True)
-    if cmd_parts is None:
-        _render_usage(command, root, cmd_parts, template_name=OVERVIEW_TMPL)
-
-    cmd_parts = cmd_parts or []
-    if hasattr(command, "commands"):
-        for command_name, command_info in command.commands.items():
-            path = root / command.name if command.name != "default" else root
-            generate_docs(path, command_info, [*cmd_parts, command_name])
-    else:
-        _render_usage(command, root, cmd_parts)
-
-
-def get_main_option(options: List[str]) -> str:
-    long_options = [option for option in options if option.startswith("--")]
-    short_options = [option for option in options if option.startswith("-")]
-    if long_options:
-        return long_options[0]
-    if short_options:
-        return short_options[0]
-    return ""
-
-
-def _render_usage(
-    command: Command,
-    root: SecurePath,
-    path: Optional[List] = None,
-    template_name: str = CMD_USAGE_TMPL,
-):
-    # This is end command
-    command_name = command.name
-    env = Environment(loader=FileSystemLoader(Path(__file__).parent / "templates"))
-    env.filters[get_main_option.__name__] = get_main_option
-    template = env.get_template(template_name)
-    arguments = []
-    options = []
-    for param in command.params:
-        if isinstance(param, TyperArgument):
-            arguments.append(param)
-        else:
-            options.append(param)
-    file_path = root / f"usage-{command_name}.txt"
-    log.info("Creating %s", file_path)
-    with file_path.open("w+") as fh:
-        fh.write(
-            template.render(
-                {
-                    "help": command.help,
-                    "name": command_name,
-                    "options": options,
-                    "arguments": arguments,
-                    "path": path,
-                }
-            )
-        )
+    generate_command_docs(root / "commands", command)
+    generate_project_definition_docs(root / "project_definition")

snowflake/cli/app/dev/docs/project_definition_docs_generator.py

@@ -0,0 +1,58 @@
+# 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.
+
+from __future__ import annotations
+
+import logging
+from typing import Any, Dict
+
+from pydantic.json_schema import model_json_schema
+from snowflake.cli.api.project.schemas.project_definition import ProjectDefinition
+from snowflake.cli.api.secure_path import SecurePath
+from snowflake.cli.app.dev.docs.project_definition_generate_json_schema import (
+    ProjectDefinitionGenerateJsonSchema,
+)
+from snowflake.cli.app.dev.docs.template_utils import get_template_environment
+
+log = logging.getLogger(__name__)
+
+DEFINITION_DESCRIPTION = "definition_description.rst.jinja2"
+
+
+def generate_project_definition_docs(root: SecurePath):
+    """
+    Recursively traverses the generated project definition schema,
+    creating a file for each section that mirrors the YAML structure.
+    Each file contains the definition for every field within that section.
+    """
+
+    root.mkdir(exist_ok=True)
+    list_of_sections = model_json_schema(
+        ProjectDefinition, schema_generator=ProjectDefinitionGenerateJsonSchema
+    )["result"]
+    for section in list_of_sections:
+        _render_definition_description(root, section)
+    return
+
+
+def _render_definition_description(root: SecurePath, section: Dict[str, Any]) -> None:
+    env = get_template_environment()
+
+    # RST files are presumed to be standalone pages in the docs with a matching item in the left nav.
+    # Included files, which these are, need to use the .txt extension.
+    file_path = root / f"definition_{section['name']}.txt"
+    log.info("Creating %s", file_path)
+    template = env.get_template(DEFINITION_DESCRIPTION)
+    with file_path.open("w+") as fh:
+        fh.write(template.render(section))

snowflake/cli/app/dev/docs/project_definition_generate_json_schema.py

@@ -0,0 +1,227 @@
+# 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.
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, List, Tuple
+
+from pydantic.json_schema import GenerateJsonSchema
+
+
+@dataclass
+class ProjectDefinitionProperty:
+    """
+    Class for storing data of properties to be used in project definition generators.
+    """
+
+    path: str
+    title: str
+    indents: int
+    item_index: int
+    required: bool
+    name: str
+    description: str
+    add_types: bool
+    types: str
+
+
+class ProjectDefinitionGenerateJsonSchema(GenerateJsonSchema):
+    def __init__(self, by_alias: bool = False, ref_template: str = ""):
+        super().__init__(by_alias, "{model}")
+        self._remapped_definitions: Dict[str, Any] = {}
+
+    def generate(self, schema, mode="validation"):
+        """
+        Transforms the generated json from the model to a list of project definition sections with its properties.
+        For example:
+        {
+            "result": [
+                {
+                    "title": "Native app definitions for the project",
+                    "name": "native_app",
+                    "properties": [
+                        {
+                            "path": "Version of the project definition schema, which is currently 1",
+                            "title": "Title of field A",
+                            "indents": 0,
+                            "item_index": 0,
+                            "required": True,
+                            "name": "definition_version",
+                            "add_types": True,
+                            "types": "string | integer",
+                        },
+                        {
+                            "path": "native_app.name",
+                            "title": "Project identifier",
+                            "indents": 1,
+                            "item_index": 0,
+                            "required": True,
+                            "name": "name",
+                            "add_types": True,
+                            "types": "string",
+                        }
+                    ]
+                }
+            ]
+        }
+        """
+        json_schema = super().generate(schema, mode=mode)
+        self._remapped_definitions = json_schema["$defs"]
+        return {"result": self._get_definition_sections(json_schema)}
+
+    def _get_definition_sections(
+        self, current_definition: Dict[str, Any]
+    ) -> List[Dict[str, Any]]:
+        required_properties: List[Dict[str, Any]] = []
+        sections: List[Dict[str, Any]] = []
+
+        for property_name, property_model in current_definition["properties"].items():
+            is_required = (
+                "required" in current_definition
+                and property_name in current_definition["required"]
+            )
+            children_properties = self._get_children_properties(
+                property_model, property_name
+            )
+
+            new_property = ProjectDefinitionProperty(
+                path=property_name,
+                title=property_model.get("title", ""),
+                description=property_model.get("description", ""),
+                indents=0,
+                item_index=0,
+                required=is_required,
+                name=property_name,
+                add_types=len(children_properties) == 0,
+                types=" | ".join(self._get_property_types(property_model)),
+            )
+            properties = [asdict(new_property)] + children_properties
+
+            if is_required:
+                required_properties.extend(properties)
+            else:
+                sections.append(
+                    {
+                        "properties": properties,
+                        "title": property_model["title"],
+                        "name": property_name,
+                    }
+                )
+
+        for section in sections:
+            section["properties"] = required_properties + section["properties"]
+
+        return sections
+
+    def _get_section_properties(
+        self,
+        current_definition: Dict[str, Any],
+        current_path: str = "",
+        depth: int = 0,
+        is_array_item: bool = False,
+    ) -> List[Dict[str, Any]]:
+        required_properties: List[Dict[str, Any]] = []
+        optional_properties: List[Dict[str, Any]] = []
+        item_index = 0
+
+        for property_name, property_model in current_definition["properties"].items():
+            item_index += 1 if is_array_item else 0
+            is_required = (
+                "required" in current_definition
+                and property_name in current_definition["required"]
+            )
+            new_current_path = (
+                property_name
+                if current_path == ""
+                else current_path + "." + property_name
+            )
+            children_properties = self._get_children_properties(
+                property_model, new_current_path, depth
+            )
+            new_property = ProjectDefinitionProperty(
+                path=new_current_path,
+                title=property_model.get("title", ""),
+                description=property_model.get("description", ""),
+                indents=depth,
+                item_index=item_index,
+                required=is_required,
+                name=property_name,
+                add_types=len(children_properties) == 0,
+                types=" | ".join(self._get_property_types(property_model)),
+            )
+            properties = [asdict(new_property)] + children_properties
+            if is_required:
+                required_properties.extend(properties)
+            else:
+                optional_properties.extend(properties)
+        return required_properties + optional_properties
+
+    def _get_children_properties(
+        self,
+        property_model: Dict[str, Any],
+        current_path: str,
+        depth: int = 0,
+    ) -> List[Dict[str, Any]]:
+        child_properties: List[Dict[str, Any]] = []
+        references: List[Tuple[str, bool]] = self._get_property_references(
+            property_model
+        )
+        for reference, is_array_item in references:
+            child_properties.extend(
+                self._get_section_properties(
+                    self._remapped_definitions[reference],
+                    current_path,
+                    depth + 1,
+                    is_array_item,
+                )
+            )
+
+        return child_properties
+
+    def _get_property_references(
+        self,
+        model_with_type: Dict[str, Any],
+        is_array_item: bool = False,
+    ) -> list[tuple[str, bool]]:
+        result: List[Tuple[str, bool]] = []
+
+        if "$ref" in model_with_type:
+            return [(model_with_type["$ref"], is_array_item)]
+
+        if "type" in model_with_type and model_with_type["type"] == "array":
+            result.extend(self._get_property_references(model_with_type["items"], True))
+
+        if "anyOf" in model_with_type:
+            for property_type in model_with_type["anyOf"]:
+                result.extend(
+                    self._get_property_references(property_type, is_array_item)
+                )
+        return result
+
+    def _get_property_types(self, model_with_type: Dict[str, Any]) -> list[str]:
+        types_result: List[str] = []
+        if "type" in model_with_type:
+            if model_with_type["type"] == "array":
+                items_types = self._get_property_types(model_with_type["items"])
+                if len(items_types) > 0:
+                    types_result.append(f"array[{' | '.join(items_types)}]")
+
+            elif model_with_type["type"] != "null":
+                types_result.append(model_with_type["type"])
+        elif "anyOf" in model_with_type:
+            for property_type in model_with_type["anyOf"]:
+                types = self._get_property_types(property_type)
+                types_result.extend(types)
+        return types_result

snowflake/cli/app/dev/docs/template_utils.py

@@ -0,0 +1,23 @@
+# 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.
+
+from pathlib import Path
+
+from jinja2 import Environment, FileSystemLoader
+
+_TEMPLATE_PATH = Path(__file__).parent / "templates"
+
+
+def get_template_environment() -> Environment:
+    return Environment(loader=FileSystemLoader(_TEMPLATE_PATH))

snowflake/cli/app/dev/docs/templates/definition_description.rst.jinja2

@@ -0,0 +1,38 @@
+{{ title }}
+
+Project definition structure
+===============================================================================
+
+.. code-block::
+
+{% for property in properties %}
+{{ "  "*(property["indents"] + 1) + ("- " if property["item_index"] == 1 else "") + ("  " if property["item_index"] > 1 else "") + property["name"] }}: {% if property["add_types"] %}<{{ property["types"] }}>{% endif %}
+{%- endfor %}
+
+
+Project definition properties
+===============================================================================
+{%- if properties %}
+The following table describes the project definition properties.
+
+.. list-table:: Project definition properties
+  :widths: 30 70
+  :header-rows: 1
+
+  * - Property
+    - Definition
+{% for property in properties %}
+  * - **{{property["path"]}}**
+
+      *{{"Required" if property["required"] else "Optional"}}*{{ (", *"+property["types"]+"*") if property["types"]}}
+
+    - {{property["title"]}}
+{% if property["description"] %}
+      {{ property["description"] }}
+{% else %}{% endif -%}
+{%+ endfor %}
+{% else %}
+
+None
+
+{% endif -%}

snowflake/cli/app/dev/docs/templates/usage.rst.jinja2

@@ -11,6 +11,7 @@ Syntax
 {%- endfor %}
 {%- for param in options if not param.hidden %}
     {{ (param.opts | get_main_option) }}{% if not param.is_flag %} <{{ param.name }}>{% endif %}
+    {%- if param.type.name == "boolean" and param.secondary_opts|length > 0  %} {{ "/ " }}{{ param.secondary_opts[0] }}{% endif %}
 {%- endfor %}
 
 Arguments
@@ -38,7 +39,11 @@ Options
 
 {%- if options %}
 {% for param in options if not param.hidden %}
-:samp:`{% for p in param.opts %}{{ p }}{{ ", " if not loop.last }}{% endfor %}
+:samp:`{% if param.type.name == "boolean" %}
+        {%- for p in param.opts %}{{ p }}{{ ", " if not loop.last }}{% endfor %}{% if param.secondary_opts|length > 0  %} {{ "/ " }}{{ param.secondary_opts[0] }}{% endif %}
+    {%- else %}
+        {%- for p in param.opts %}{{ p }}{{ ", " if not loop.last }}{% endfor %}
+    {%- endif %}
     {%- if not param.is_flag %}
         {%- if param.type.name != "choice" %}{{ ' {' }}{% else %} {% endif %}{{ param.make_metavar() }}{% if param.type.name != "choice" %}{{ '}' }}
         {%- endif %}