pycarlo 0.10.186__py3-none-any.whl → 0.12.18__py3-none-any.whl

pycarlo/lib/types.py

@@ -0,0 +1,68 @@
+"""
+Custom GraphQL types for the Monte Carlo Python Schema Library.
+
+This module provides custom implementations of/replacements for sgqlc types that are used
+in the auto-generated schema.
+"""
+
+import logging
+from typing import Any, Optional, Union
+
+import sgqlc.types
+
+logger = logging.getLogger(__name__)
+
+
+class Enum(sgqlc.types.Enum):
+    """
+    A backward-compatible GraphQL enum type that gracefully handles unknown values.
+
+    Problem:
+    When new enum values are added to the Monte Carlo GraphQL API, older SDK versions
+    that don't have these values in their generated schema will crash with a ValueError
+    when trying to deserialize API responses containing the new values.
+
+    Solution:
+    This custom Enum class returns unknown enum values as plain strings instead of
+    raising an error. Since sgqlc enums are already represented as strings internally,
+    this maintains full compatibility with existing code while preventing crashes.
+
+    Behavior:
+    - Known enum values: Returned as strings (same as sgqlc.types.Enum)
+    - Unknown enum values: Returned as strings with a warning logged
+    - All comparisons, collections, and operations work identically
+
+    Example:
+        # Previous Values for EntitlementTypes = ['SSO', 'MULTI_WORKSPACE']
+        # API is updated to return new value: ['SSO', 'NEW_FEATURE', 'MULTI_WORKSPACE']
+
+        # With standard sgqlc.types.Enum:
+        # ValueError: EntitlementTypes does not accept value NEW_FEATURE
+
+        # With this Enum:
+        # Will return the new value as str and log a warning, no exception raised
+
+        # Code still works:
+        if 'SSO' in entitlements:  # Works
+            enable_sso()
+        if 'NEW_FEATURE' in entitlements:  # Also works
+            enable_new_feature()
+    """
+
+    def __new__(
+        cls, json_data: Any, _: Optional[Any] = None
+    ) -> Union[str, sgqlc.types.Variable, None]:
+        try:
+            return sgqlc.types.get_variable_or_none(json_data)
+        except ValueError:
+            pass
+
+        if json_data not in cls:
+            # Log warning but don't crash - return the unknown value as a string
+            logger.warning(
+                f"Unknown enum value '{json_data}' for {cls.__name__}. "
+                f"This may indicate the SDK is out of date. Returning raw string value."
+            )
+            return str(json_data)
+
+        return str(json_data)

{pycarlo-0.10.186.dist-info → pycarlo-0.12.18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycarlo
-Version: 0.10.186
+Version: 0.12.18
 Summary: Monte Carlo's Python SDK
 Home-page: https://www.montecarlodata.com/
 Author: Monte Carlo Data, Inc
@@ -19,15 +19,13 @@ Classifier: Programming Language :: Python :: 3.12
 Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: dataclasses-json <6.0.0,>=0.5.7
-Requires-Dist: python-box >=5.0.0
-Requires-Dist: requests <3.0.0,>=2.0.0
-Requires-Dist: responses >=0.20.0
-Requires-Dist: sgqlc <17.0,>=14.1
+Requires-Dist: dataclasses-json<6.0.0,>=0.5.7
+Requires-Dist: python-box>=5.0.0
+Requires-Dist: requests<3.0.0,>=2.0.0
+Requires-Dist: responses>=0.20.0
+Requires-Dist: sgqlc<17.0,>=14.1
 
-# Pycarlo
-
-Monte Carlo's Alpha Python SDK!
+# Pycarlo - Monte Carlo's Python SDK
 
 ## Installation
 
@@ -40,23 +38,22 @@ virtualenv venv
 pip install -U pycarlo
 ```
 
-Developers of the SDK can use:
-
-```shell
-make install-with-tests
-. venv/bin/activate
-pre-commit install
-```
-
 ## Overview
 
 Pycarlo comprises two components: `core` and `features`.
 
-All Monte Carlo API queries and mutations that you could execute via the API are supported via the `core` library. Operations can be executed as first class objects, using [sgqlc](https://github.com/profusion/sgqlc), or as raw GQL with variables. In both cases, a consistent object where fields can be referenced by dot notation and the more pythonic snake_case is returned for ease of use.
+All Monte Carlo API queries and mutations that you could execute via the API are supported via the
+`core` library. Operations can be executed as first class objects, using
+[sgqlc](https://github.com/profusion/sgqlc), or as raw GQL with variables. In both cases, a
+consistent object where fields can be referenced by dot notation and the more pythonic snake_case is
+returned for ease of use.
 
-The `features` library provides additional convenience for performing common operations like with dbt, circuit breaking, and pii filtering.
+The `features` library provides additional convenience for performing common operations like with
+dbt, circuit breaking, and pii filtering.
 
-Note that an API Key is required to use the SDK. See [here](https://docs.getmontecarlo.com/docs/developer-resources#creating-an-api-key) for details on how to generate one.
+Note that an API Key is required to use the SDK. See
+[our docs on generating API keys](https://docs.getmontecarlo.com/docs/developer-resources#creating-an-api-key)
+for details.
 
 ## Basic usage
 
@@ -144,13 +141,20 @@ print(client(mutation))
 # ]
 ```
 
-Note that you can find Monte Carlo's API reference [here](https://apidocs.getmontecarlo.com/).
+### Examples
+
+We have [a few examples here you can reference](./examples).
 
-For details and additional examples on how to map (convert) GraphQL queries to `sgqlc` operations please refer to the docs [here](https://sgqlc.readthedocs.io/en/latest/sgqlc.operation.html).
+See [Monte Carlo's API reference](https://apidocs.getmontecarlo.com/) for all supported queries and
+mutations.
+
+For details and additional examples on how to map (convert) GraphQL queries to `sgqlc` operations
+please refer to [the sgqlc docs](https://sgqlc.readthedocs.io/en/latest/sgqlc.operation.html).
 
 ### Features
 
-You can use [pydoc](https://docs.python.org/3.8/library/pydoc.html) to retrieve documentation on any feature packages (`pydoc pycarlo.features`).
+You can use [pydoc](https://docs.python.org/library/pydoc.html) to retrieve documentation on any
+feature packages (`pydoc pycarlo.features`).
 
 For instance for [circuit breakers](https://docs.getmontecarlo.com/docs/circuit-breakers):
 
@@ -160,9 +164,13 @@ pydoc pycarlo.features.circuit_breakers.service
 
 ## Session configuration
 
-By default, when creating a client the `default` profile from `~/.mcd/profiles.ini` is used. This file created via [montecarlo configure](https://docs.getmontecarlo.com/docs/using-the-cli#setting-up-the-cli) on the CLI. Note that you can find Monte Carlo's CLI reference [here](https://clidocs.getmontecarlo.com/).
+By default, when creating a client the `default` profile from `~/.mcd/profiles.ini` is used. This
+file created via
+[montecarlo configure](https://docs.getmontecarlo.com/docs/using-the-cli#setting-up-the-cli) on the
+CLI. See [Monte Carlo's CLI reference](https://clidocs.getmontecarlo.com/) for more details.
 
-You can override this usage by creating a custom `Session`. For instance, if you want to pass the ID and Token:
+You can override this usage by creating a custom `Session`. For instance, if you want to pass the ID
+and Token:
 
 ```python
 from pycarlo.core import Client, Session
@@ -174,7 +182,8 @@ Sessions support the following params:
 
 - `mcd_id`: API Key ID.
 - `mcd_token`: API secret.
-- `mcd_profile`: Named profile containing credentials. This is created via the CLI (e.g. `montecarlo configure --profile-name zeus`).
+- `mcd_profile`: Named profile containing credentials. This is created via the CLI (e.g.
+  `montecarlo configure --profile-name zeus`).
 - `mcd_config_path`: Path to file containing credentials. Defaults to `~/.mcd/`.
 
 You can also specify the API Key, secret or profile name using the following environment variables:
@@ -183,7 +192,8 @@ You can also specify the API Key, secret or profile name using the following env
 - `MCD_DEFAULT_API_TOKEN`
 - `MCD_DEFAULT_PROFILE`
 
-When creating a session any explicitly passed `mcd_id` and `mcd_token` params take precedence, followed by environmental variables and then any config-file options.
+When creating a session any explicitly passed `mcd_id` and `mcd_token` params take precedence,
+followed by environmental variables and then any config-file options.
 
 Environment variables can be mixed with passed credentials, but not the config-file profile.
 
@@ -191,9 +201,11 @@ Environment variables can be mixed with passed credentials, but not the config-f
 
 ## Integration Gateway API
 
-There are features that require the Integration Gateway API instead of the regular GraphQL Application API, for example Airflow Callbacks invoked by the `airflow-mcd` library.
+There are features that require the Integration Gateway API instead of the regular GraphQL
+Application API, for example Airflow Callbacks invoked by the `airflow-mcd` library.
 
-To use the Gateway you need to initialize the `Session` object passing a `scope` parameter and then use `make_request` to invoke Gateway endpoints:
+To use the Gateway you need to initialize the `Session` object passing a `scope` parameter and then
+use `make_request` to invoke Gateway endpoints:
 
 ```python
 from pycarlo.core import Client, Session
@@ -211,17 +223,22 @@ The following values also be set by the environment:
 - `MCD_VERBOSE_ERRORS`: Enable logging. This includes a trace ID for each session and request.
 - `MCD_API_ENDPOINT`: Customize the endpoint where queries and mutations are executed.
 
-## Tests and releases
+## Enum Backward Compatibility
+
+Unlike the baseline `sgqlc` behavior, this SDK is designed to maintain backward compatibility when
+new enum values are added to the Monte Carlo API. If the API returns an enum value that doesn't
+exist in your SDK version, it will be returned as a string with a warning logged, rather than
+raising an error. This allows older SDK versions to continue working when new features are added.
 
-To update queries and mutations via introspection, use `make generate`.
+To avoid warnings and ensure full feature support, keep your SDK updated to the latest version.
 
-`make test` can be used to run all tests locally. CircleCI manages all testing for deployment. When ready for a review, create a PR against `main`.
+## Contributing
 
-When ready to release, create a new [Github release](https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository) with a tag using semantic versioning (e.g. `v0.42.0`) and CircleCI will test and publish to PyPI. Note that an existing version will not be deployed.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for details.
 
 ## References
 
-- Dashboard: <https://getmontecarlo.com>
+- Monte Carlo App: <https://getmontecarlo.com>
 - Product docs: <https://docs.getmontecarlo.com>
 - Status page: <https://status.getmontecarlo.com>
 - API (and SDK): <https://apidocs.getmontecarlo.com>
@@ -229,4 +246,4 @@ When ready to release, create a new [Github release](https://docs.github.com/en/
 
 ## License
 
-Apache 2.0 - See the [LICENSE](http://www.apache.org/licenses/LICENSE-2.0) for more information.
+Apache 2.0 - See the [LICENSE](./LICENSE) for more information.

{pycarlo-0.10.186.dist-info → pycarlo-0.12.18.dist-info}/RECORD

@@ -20,9 +20,12 @@ pycarlo/features/circuit_breakers/service.py,sha256=TljwMOhA5igBumkpJwM22iEJGyvt
 pycarlo/features/dbt/__init__.py,sha256=A2cFr8_aSY_kDw1m7jR6QkHfiBMC1cZ6O8WosF9XrRg,85
 pycarlo/features/dbt/dbt_importer.py,sha256=eJb9Jiu7tAEb_xsLO-ycDOjjVm-LLfTtbAzlzIRxT5I,7328
 pycarlo/features/dbt/queries.py,sha256=9o1HevRECYyGXQ0lG0LrN4iuuXCS-SWjz7NTgAAZIro,621
-pycarlo/features/metadata/__init__.py,sha256=lSfQ-3W6d4YCWpjWlbxBNm07KomrmPORweCGLvLbGuM,360
-pycarlo/features/metadata/allow_block_list.py,sha256=UWqGOzLELRRryHVRgNXqlfUfHFX9SeXuhKix_5B_7CY,5823
-pycarlo/features/metadata/metadata_filters_container.py,sha256=iHMd3S-JQLkTVgiKU5sgeJN9Wb6KWm-6YuulOCStGZ4,12670
+pycarlo/features/metadata/__init__.py,sha256=0RDVHnwPvQcNXkeXEAxL4VJ8VWrl2P0fft_Kl2nlo7I,912
+pycarlo/features/metadata/asset_allow_block_list.py,sha256=jXCS7HtUJhexEXZyRzyN4MT-BPSaMTKWCWiBT_l-Ijo,761
+pycarlo/features/metadata/asset_filters_container.py,sha256=O15SC6u7HMGlViYnX7H8MRFttQrIXQd3a0oOrz7My5U,3411
+pycarlo/features/metadata/base_allow_block_list.py,sha256=c8zd0BXkNSfQ3LkNC_A0KrO2AsYtIowc8FjbdyDyDu0,4738
+pycarlo/features/metadata/metadata_allow_block_list.py,sha256=HzgXE0WhwDZoBHeV04e8dwe88rUSVVnOl8nFEPlb0jA,3496
+pycarlo/features/metadata/metadata_filters_container.py,sha256=p7FNg71KYZZrvgJmlx9rID2TAL_e9LKzNQZ9KKN5uGs,12812
 pycarlo/features/pii/__init__.py,sha256=w5X-oD8HWaL6fP2jt40AhlXO-MNzlVAlhRaZ5kQqAZY,247
 pycarlo/features/pii/constants.py,sha256=XWeiikXk9AtljdWsGfl49b9zI6w8EzK8F__Euc0vQ3w,70
 pycarlo/features/pii/pii_filterer.py,sha256=k53b_V_mddY4A17-DJ5vQKszFDlUaiP3E650JFHAeJA,6209
@@ -33,12 +36,13 @@ pycarlo/features/user/exceptions.py,sha256=Za5mPMynNDW_UQkfMbCSGjP1ht-xSUkwoI6hV
 pycarlo/features/user/models.py,sha256=fhvS7tBhTtx7p9624yN5tzebXs5ERrl1XQ9B_DYor0E,126
 pycarlo/features/user/queries.py,sha256=m97RvM0oiBlrU5xmOwe_JJ5N0G0NG5hIOeyQqN2O8_4,170
 pycarlo/features/user/service.py,sha256=DHkhuonySaHro07NTd0YNe3cNkDk62CiRTY77dhVaMs,2890
-pycarlo/lib/README.md,sha256=QGNeUefPzLKGyZqn5aITpcFgkC9WQTNS292BGisRFHk,139
+pycarlo/lib/README.md,sha256=CVVrPPgje7pkXNNsPvwLSeUOm5aktb22MlttmoxX08k,1677
 pycarlo/lib/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-pycarlo/lib/schema.json,sha256=gTQPDRzyEdhlDIMkKxcZQleskDMG5rowhyQbLonFBS0,6331382
-pycarlo/lib/schema.py,sha256=kjRJ_SQvyBIjdtowDhcr0YRFaAiw4pboyuw3DkEVumM,2756791
-pycarlo-0.10.186.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pycarlo-0.10.186.dist-info/METADATA,sha256=VKp9NrsS9BaQPq7qJo-a_iDNPWq6HBT8bXYfhDG7o18,8742
-pycarlo-0.10.186.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-pycarlo-0.10.186.dist-info/top_level.txt,sha256=TIE04H4pgzGaFxAB-gvkmVAUOAoHxxFfhnEcpuQ5bF4,8
-pycarlo-0.10.186.dist-info/RECORD,,
+pycarlo/lib/schema.json,sha256=zmXlnBKJcydi72WMc5L3jkHXFB6RMSqFCiO77z_SjCI,6605810
+pycarlo/lib/schema.py,sha256=2zNqYgWxNfQIw81-Xb1o5buAplNtGCakNcr4xluGj2E,2871673
+pycarlo/lib/types.py,sha256=lGOrm5Qm-SieDAkOkVOFSgyUJYGOjKnea961AD9Dv6s,2404
+pycarlo-0.12.18.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pycarlo-0.12.18.dist-info/METADATA,sha256=a4BpakA2kOIhQlsscluRvYuqwNYuWGhfqLMrX3GEee0,8718
+pycarlo-0.12.18.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+pycarlo-0.12.18.dist-info/top_level.txt,sha256=TIE04H4pgzGaFxAB-gvkmVAUOAoHxxFfhnEcpuQ5bF4,8
+pycarlo-0.12.18.dist-info/RECORD,,

{pycarlo-0.10.186.dist-info → pycarlo-0.12.18.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: bdist_wheel (0.43.0)
+Generator: setuptools (75.3.2)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pycarlo/features/metadata/allow_block_list.py

@@ -1,159 +0,0 @@
-import enum
-import re
-from dataclasses import dataclass, field
-from typing import Any, Callable, List, Optional
-
-from dataclasses_json import config, dataclass_json
-
-from pycarlo.common import get_logger
-
-logger = get_logger(__name__)
-
-# For documentation and samples check the link below:
-# https://www.notion.so/montecarlodata/Catalog-Schema-Filtering-59edd6eff7f74c94ab6bfca75d2e3ff1
-
-
-def _exclude_none_values(value: Any) -> bool:
-    return value is None
-
-
-class FilterEffectType(enum.Enum):
-    BLOCK = "block"
-    ALLOW = "allow"
-
-
-class FilterType(enum.Enum):
-    EXACT_MATCH = "exact_match"
-    PREFIX = "prefix"
-    SUFFIX = "suffix"
-    SUBSTRING = "substring"
-    REGEXP = "regexp"
-
-
-@dataclass_json
-@dataclass
-class MetadataFilter:
-    # we're using exclude=_exclude_none_values to prevent these properties to be serialized to json
-    # when None, to keep the json doc simpler
-    project: Optional[str] = field(metadata=config(exclude=_exclude_none_values), default=None)
-    dataset: Optional[str] = field(metadata=config(exclude=_exclude_none_values), default=None)
-    table_type: Optional[str] = field(metadata=config(exclude=_exclude_none_values), default=None)
-    table_name: Optional[str] = field(metadata=config(exclude=_exclude_none_values), default=None)
-    type: FilterType = FilterType.EXACT_MATCH
-    effect: FilterEffectType = FilterEffectType.BLOCK
-
-    def matches(self, force_regexp: bool = False, **kwargs: Any) -> bool:
-        """
-        Returns True if all properties specified in kwargs match the conditions specified in
-        properties of the same name in this object.
-        Supported keys in kwargs: 'project', 'dataset', 'table', 'table_type'
-        For example kwargs={'project': 'prj_1'} will evaluate if 'prj_1' matches the condition in
-        self.project. For kwargs={'project': 'prj_1', 'dataset': 'ds_1'} will evaluate if 'prj_1'
-        matches the condition in self.project and if 'ds_1' matches the condition in self.dataset.
-        If any of the conditions (for example self.project) is None, that condition will be matched.
-        """
-        if not kwargs:
-            raise ValueError("At least one field needs to be specified for matching")
-
-        # kwargs must match the field names in this class, if any of them do not,
-        # invalidate the filter.
-        try:
-            is_match = all(
-                self._safe_match(
-                    component=getattr(self, component),
-                    value=value,
-                    force_regexp=force_regexp,
-                    filter_type=self.type
-                    if self.filter_type_target_field() == component
-                    else FilterType.EXACT_MATCH,
-                )
-                for component, value in kwargs.items()
-            )
-        except AttributeError:
-            is_match = False
-
-        return is_match
-
-    def filter_type_target_field(self) -> str:
-        """
-        The field that is evaluated using filter type. Other fields should be
-        compared using exact match.
-        """
-        if self.table_name is not None:
-            return "table_name"
-        if self.dataset is not None:
-            return "dataset"
-        if self.project is not None:
-            return "project"
-
-        logger.exception("Invalid filter, missing target values")
-        return ""
-
-    @classmethod
-    def _safe_match(
-        cls,
-        component: Optional[str],
-        value: Optional[str],
-        force_regexp: bool,
-        filter_type: FilterType,
-    ) -> bool:
-        # Field not specified on this object, e.g. self.dataset=None, which matches everything
-        if component is None:
-            return True
-        # The value in kwargs is empty, it does not match the condition.
-        if value is None:
-            return False
-
-        # Convert it in lowercase. In the normalizer we are converting identifiers
-        # (like project/dataset) to lowercase so the metadata filters may be defined with
-        # lowercase on the UI, however on Snowflake the identifiers are usually in uppercase.
-        # Therefore, we perform the evaluation case-insensitive.
-        component = component.lower()
-        value = value.lower()
-
-        if force_regexp or filter_type == FilterType.REGEXP:
-            regexp = f"^{component}$"  # Anchor the regexp to be more strict about what to match.
-            return re.match(regexp, value) is not None
-        elif filter_type == FilterType.PREFIX:
-            return value.startswith(component)
-        elif filter_type == FilterType.SUFFIX:
-            return value.endswith(component)
-        elif filter_type == FilterType.SUBSTRING:
-            return component in value
-        else:
-            return component == value
-
-
-@dataclass_json
-@dataclass
-class AllowBlockList:
-    filters: List[MetadataFilter] = field(default_factory=list)
-    default_effect: FilterEffectType = FilterEffectType.ALLOW
-
-    @property
-    def other_effect(self) -> FilterEffectType:
-        return (
-            FilterEffectType.ALLOW
-            if self.default_effect == FilterEffectType.BLOCK
-            else FilterEffectType.BLOCK
-        )
-
-    def get_default_effect_filters(
-        self, condition: Optional[Callable[[MetadataFilter], bool]] = None
-    ) -> List[MetadataFilter]:
-        return list(
-            filter(
-                lambda f: f.effect == self.default_effect and (condition is None or condition(f)),
-                self.filters,
-            )
-        )
-
-    def get_other_effect_filters(
-        self, condition: Optional[Callable[[MetadataFilter], bool]] = None
-    ) -> List[MetadataFilter]:
-        return list(
-            filter(
-                lambda f: f.effect != self.default_effect and (condition is None or condition(f)),
-                self.filters,
-            )
-        )