pycarlo 0.11.15__py3-none-any.whl → 0.12.5__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.11.15.dist-info → pycarlo-0.12.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: pycarlo
-Version: 0.11.15
+Version: 0.12.5
 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.11.15.dist-info → pycarlo-0.12.5.dist-info}/RECORD

@@ -25,7 +25,7 @@ pycarlo/features/metadata/asset_allow_block_list.py,sha256=jXCS7HtUJhexEXZyRzyN4
 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=GCbk-t7Njq2IiQrre186aN3DT2ytN-8RTwBPnBmfgJA,12715
+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
@@ -36,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=QPrl1YZ0WF2HNxk4EJG3PuypjUEu6z9cT-zby0oXlqY,6521200
-pycarlo/lib/schema.py,sha256=6MMMErpEG-oFTgOfGBoZmQw5tgo4li7XFKXA-JqGY3k,2832020
-pycarlo-0.11.15.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-pycarlo-0.11.15.dist-info/METADATA,sha256=IiKzQSFemktwSfQa1MtnM2A2AeKeBxnbC_y4XwQaWx0,8741
-pycarlo-0.11.15.dist-info/WHEEL,sha256=GJ7t_kWBFywbagK5eo9IoUwLW6oyOeTKmQ-9iHFVNxQ,92
-pycarlo-0.11.15.dist-info/top_level.txt,sha256=TIE04H4pgzGaFxAB-gvkmVAUOAoHxxFfhnEcpuQ5bF4,8
-pycarlo-0.11.15.dist-info/RECORD,,
+pycarlo/lib/schema.json,sha256=AjbIWUdzPwAxpeqmZ8DoA-FSUPcxaAiPsM-J7ePlWN4,6593668
+pycarlo/lib/schema.py,sha256=uhhOjB4kbru-7tZT_O_TUW8jzSCBiCtGkxTyQNbt7Hg,2866352
+pycarlo/lib/types.py,sha256=lGOrm5Qm-SieDAkOkVOFSgyUJYGOjKnea961AD9Dv6s,2404
+pycarlo-0.12.5.dist-info/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+pycarlo-0.12.5.dist-info/METADATA,sha256=_jGoE6lB9pSjezfhXdXtXk-QWfv5Yh1_ucmBiega48g,8717
+pycarlo-0.12.5.dist-info/WHEEL,sha256=iAkIy5fosb7FzIOwONchHf19Qu7_1wCWyFNR5gu9nU0,91
+pycarlo-0.12.5.dist-info/top_level.txt,sha256=TIE04H4pgzGaFxAB-gvkmVAUOAoHxxFfhnEcpuQ5bF4,8
+pycarlo-0.12.5.dist-info/RECORD,,

{pycarlo-0.11.15.dist-info → pycarlo-0.12.5.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