dbt-adapters 1.22.2__py3-none-any.whl

dbt/adapters/base/meta.py

@@ -0,0 +1,150 @@
+import abc
+from functools import wraps
+from typing import Any, Callable, Dict, FrozenSet, Optional, Set
+
+from dbt_common.events.functions import warn_or_error
+
+from dbt.adapters.events.types import AdapterDeprecationWarning
+
+
+Decorator = Callable[[Any], Callable]
+
+
+class _Available:
+    def __call__(self, func: Callable) -> Callable:
+        func._is_available_ = True  # type: ignore
+        return func
+
+    def parse(self, parse_replacement: Callable) -> Decorator:
+        """A decorator factory to indicate that a method on the adapter will be
+        exposed to the database wrapper, and will be stubbed out at parse time
+        with the given function.
+
+        @available.parse()
+        def my_method(self, a, b):
+            if something:
+                return None
+            return big_expensive_db_query()
+
+        @available.parse(lambda *args, **args: {})
+        def my_other_method(self, a, b):
+            x = {}
+            x.update(big_expensive_db_query())
+            return x
+        """
+
+        def inner(func):
+            func._parse_replacement_ = parse_replacement
+            return self(func)
+
+        return inner
+
+    def deprecated(
+        self, supported_name: str, parse_replacement: Optional[Callable] = None
+    ) -> Decorator:
+        """A decorator that marks a function as available, but also prints a
+        deprecation warning. Use like
+
+        @available.deprecated('my_new_method')
+        def my_old_method(self, arg):
+            args = compatability_shim(arg)
+            return self.my_new_method(*args)
+
+        @available.deprecated('my_new_slow_method', lambda *a, **k: (0, ''))
+        def my_old_slow_method(self, arg):
+            args = compatibility_shim(arg)
+            return self.my_new_slow_method(*args)
+
+        To make `adapter.my_old_method` available but also print out a warning
+        on use directing users to `my_new_method`.
+
+        The optional parse_replacement, if provided, will provide a parse-time
+        replacement for the actual method (see `available.parse`).
+        """
+
+        def wrapper(func):
+            func_name = func.__name__
+
+            @wraps(func)
+            def inner(*args, **kwargs):
+                warn_or_error(
+                    AdapterDeprecationWarning(old_name=func_name, new_name=supported_name)
+                )
+                return func(*args, **kwargs)
+
+            if parse_replacement:
+                available_function = self.parse(parse_replacement)
+            else:
+                available_function = self
+            return available_function(inner)
+
+        return wrapper
+
+    def parse_none(self, func: Callable) -> Callable:
+        wrapper = self.parse(lambda *a, **k: None)
+        return wrapper(func)
+
+    def parse_list(self, func: Callable) -> Callable:
+        wrapper = self.parse(lambda *a, **k: [])
+        return wrapper(func)
+
+
+available = _Available()
+
+
+class available_property(property):
+    """
+    This supports making dynamic properties (`@property`) available in the jinja context.
+
+    We use `@available` to make methods available in the jinja context, but this mechanism relies on the method being callable.
+    Intuitively, we should be able to use both `@available` and `@property` to create a dynamic property that's available in the jinja context.
+
+    Using the `@property` decorator as the inner decorator supplies `@available` with something that is not callable.
+    Instead of returning the method, `@property` returns the value itself, not the method that is called to create the value.
+
+    Using the `@available` decorator as the inner decorator adds `_is_available_ = True` to the function.
+    However, when the `@property` decorator executes, it returns a `property` object which does not have the `_is_available_` attribute.
+
+    This decorator solves this problem by simply adding `_is_available_ = True` as an attribute on the `property` built-in.
+    """
+
+    _is_available_ = True
+
+
+class AdapterMeta(abc.ABCMeta):
+    _available_: FrozenSet[str]
+    _parse_replacements_: Dict[str, Callable]
+
+    def __new__(mcls, name, bases, namespace, **kwargs) -> "AdapterMeta":
+        # mypy does not like the `**kwargs`. But `ABCMeta` itself takes
+        # `**kwargs` in its argspec here (and passes them to `type.__new__`.
+        # I'm not sure there is any benefit to it after poking around a bit,
+        # but having it doesn't hurt on the python side (and omitting it could
+        # hurt for obscure metaclass reasons, for all I know)
+        cls = abc.ABCMeta.__new__(mcls, name, bases, namespace, **kwargs)
+
+        # this is very much inspired by ABCMeta's own implementation
+
+        # dict mapping the method name to whether the model name should be
+        # injected into the arguments. All methods in here are exposed to the
+        # context.
+        available: Set[str] = set()
+        replacements: Dict[str, Any] = {}
+
+        # collect base class data first
+        for base in bases:
+            available.update(getattr(base, "_available_", set()))
+            replacements.update(getattr(base, "_parse_replacements_", set()))
+
+        # override with local data if it exists
+        for name, value in namespace.items():
+            if getattr(value, "_is_available_", False):
+                available.add(name)
+            parse_replacement = getattr(value, "_parse_replacement_", None)
+            if parse_replacement is not None:
+                replacements[name] = parse_replacement
+
+        cls._available_ = frozenset(available)
+        # should this be a namedtuple so it will be immutable like _available_?
+        cls._parse_replacements_ = replacements
+        return cls

dbt/adapters/base/plugin.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+from typing import List, Optional, Type
+
+from dbt.adapters.contracts.connection import Credentials
+from dbt.adapters.protocol import AdapterProtocol
+
+
+class AdapterPlugin:
+    """Defines the basic requirements for a dbt adapter plugin.
+
+    :param include_path: The path to this adapter plugin's root
+    :param dependencies: A list of adapter names that this adapter depends
+        upon.
+    """
+
+    def __init__(
+        self,
+        adapter: Type[AdapterProtocol],
+        credentials: Type[Credentials],
+        include_path: str,
+        dependencies: Optional[List[str]] = None,
+        project_name: Optional[str] = None,
+    ) -> None:
+        self.adapter: Type[AdapterProtocol] = adapter
+        self.credentials: Type[Credentials] = credentials
+        self.include_path: str = include_path
+        self.project_name: str = project_name or f"dbt_{Path(include_path).name}"
+        self.dependencies: List[str]
+        if dependencies is None:
+            self.dependencies = []
+        else:
+            self.dependencies = dependencies

dbt/adapters/base/query_headers.py

@@ -0,0 +1,106 @@
+from threading import local
+from typing import Any, Callable, Dict, Optional
+
+from dbt_common.exceptions import DbtRuntimeError
+
+from dbt.adapters.clients.jinja import QueryStringGenerator
+from dbt.adapters.contracts.connection import AdapterRequiredConfig, QueryComment
+
+
+class QueryHeaderContextWrapper:
+    def __init__(self, context) -> None:
+        self._inner_context = context
+
+    def __getattr__(self, name):
+        return getattr(self._inner_context, name, "")
+
+
+class _QueryComment(local):
+    """A thread-local class storing thread-specific state information for
+    connection management, namely:
+        - the current thread's query comment.
+        - a source_name indicating what set the current thread's query comment
+    """
+
+    def __init__(self, initial) -> None:
+        self.query_comment: Optional[str] = initial
+        self.append: bool = False
+
+    def add(self, sql: str) -> str:
+        if not self.query_comment:
+            return sql
+
+        if self.append:
+            # replace last ';' with '<comment>;'
+            sql = sql.rstrip()
+            if sql[-1] == ";":
+                sql = sql[:-1]
+                return "{}\n/* {} */;".format(sql, self.query_comment.strip())
+
+            return "{}\n/* {} */".format(sql, self.query_comment.strip())
+
+        return "/* {} */\n{}".format(self.query_comment.strip(), sql)
+
+    def set(self, comment: Optional[str], append: bool):
+        if isinstance(comment, str) and "*/" in comment:
+            # tell the user "no" so they don't hurt themselves by writing
+            # garbage
+            raise DbtRuntimeError(f'query comment contains illegal value "*/": {comment}')
+        self.query_comment = comment
+        self.append = append
+
+
+QueryStringFunc = Callable[[str, Optional[QueryHeaderContextWrapper]], str]
+
+
+class MacroQueryStringSetter:
+    DEFAULT_QUERY_COMMENT_APPEND = False
+
+    def __init__(
+        self, config: AdapterRequiredConfig, query_header_context: Dict[str, Any]
+    ) -> None:
+        self.config = config
+        self._query_header_context = query_header_context
+
+        comment_macro = self._get_comment_macro()
+        self.generator: QueryStringFunc = lambda name, model: ""
+        # if the comment value was None or the empty string, just skip it
+        if comment_macro:
+            assert isinstance(comment_macro, str)
+            macro = "\n".join(
+                (
+                    "{%- macro query_comment_macro(connection_name, node) -%}",
+                    comment_macro,
+                    "{% endmacro %}",
+                )
+            )
+            ctx = self._get_context()
+            self.generator = QueryStringGenerator(macro, ctx)
+        self.comment = _QueryComment(None)
+        self.reset()
+
+    def _get_comment_macro(self) -> Optional[str]:
+        return self.config.query_comment.comment
+
+    def _get_context(self) -> Dict[str, Any]:
+        return self._query_header_context
+
+    def add(self, sql: str) -> str:
+        return self.comment.add(sql)
+
+    def reset(self):
+        self.set("master", None)
+
+    def set(self, name: str, query_header_context: Any):
+        wrapped: Optional[QueryHeaderContextWrapper] = None
+        if query_header_context is not None:
+            wrapped = QueryHeaderContextWrapper(query_header_context)
+        comment_str = self.generator(name, wrapped)
+
+        append = self.DEFAULT_QUERY_COMMENT_APPEND
+        if (
+            isinstance(self.config.query_comment, QueryComment)
+            and self.config.query_comment.append is not None
+        ):
+            append = self.config.query_comment.append
+        self.comment.set(comment_str, append)