Package: pycarlo
PycarloMonte Carlo's Alpha Python SDK!InstallationRequires Python 3.7 or greater. Normally you can install and update using pip. For instance:virtualenvvenv
.venv/bin/activate

pipinstall-UpycarloDevelopers of the SDK can use:makeinstall-with-tests
.venv/bin/activate
pre-commitinstallOverviewPycarlo comprises two components:coreandfeatures.All Monte Carlo API queries and mutations that you could execute via the API are supported via thecorelibrary. Operations can be executed as first class objects, usingsgqlc, 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.Thefeatureslibrary 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. Seeherefor details on how to generate one.Basic usageCorefrompycarlo.coreimportClient,Query,Mutation# First create a client. This creates a session using the 'default' profile from# '~/.mcd/profiles.ini'. This profile is created automatically via `montecarlo configure` on the# CLI. See the session subsection for customizations, options and alternatives (e.g. using the#  environment, params, named profiles, etc.)client=Client()# Now you can can execute a query. For instance, getUser (selecting the email field).# This would be like executing -#     curl --location --request POST 'https://api.getmontecarlo.com/graphql' \#     --header 'x-mcd-id: <ID>' \#     --header 'x-mcd-token: <TOKEN>' \#     --header 'Content-Type: application/json' \#     --data-raw '{"query": "query {getUser {email}}"}'# Notice how the CamelCase from the Graphql query is converted to snake_case in both the request# and response.query=Query()query.get_user.__fields__('email')print(client(query).get_user.email)# You can also execute a query that requires variables. For instance,# testTelnetConnection (selecting all fields).query=Query()query.test_telnet_connection(host='montecarlodata.com',port=443)print(client(query))# If necessary, you can always generate (e.g. print) the raw query that would be executed.print(query)# query {#   testTelnetConnection(host: "montecarlodata.com", port: 443) {#     success#     validations {#       type#       message#     }#     warnings {#       type#       message#     }#   }# }# If you are not a fan of sgqlc operations (Query and Mutation) you can also execute any# raw query using the client. For instance, if we want the first 10 tables from getTables.get_table_query="""query getTables{getTables(first: 10) {edges {node {fullTableId}}}}"""response=client(get_table_query)# This returns a Box object where fields can be accessed using dot notation.# Notice how unlike with the API the response uses the more Pythonic snake_case.foredgeinresponse.get_tables.edges:print(edge.node.full_table_id)# The response can still be processed as a standard dictionary.print(response['get_tables']['edges'][0]['node']['full_table_id'])# You can also execute any mutations too. For instance, generateCollectorTemplate# (selecting the templateLaunchUrl).mutation=Mutation()mutation.generate_collector_template().dc.template_launch_url()print(client(mutation))# Any errors will raise a GqlError with details. For instance, executing above with an# invalid region.mutation=Mutation()mutation.generate_collector_template(region='artemis')print(client(mutation))# pycarlo.common.errors.GqlError: [{'message': 'Region "\'artemis\'" not currently active.'...]Note that you can find Monte Carlo's API referencehere.For details and additional examples on how to map (convert) GraphQL queries tosgqlcoperations please refer to the docshere.FeaturesYou can usepydocto retrieve documentation on any feature packages (pydoc pycarlo.features).For instance forcircuit breakers:pydocpycarlo.features.circuit_breakers.serviceSession configurationBy default, when creating a client thedefaultprofile from~/.mcd/profiles.iniis used. This file created viamontecarlo configureon the CLI. Note that you can find Monte Carlo's CLI referencehere.You can override this usage by creating a customSession. For instance, if you want to pass the ID and Token:frompycarlo.coreimportClient,Sessionclient=Client(session=Session(mcd_id='foo',mcd_token='bar'))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_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:MCD_DEFAULT_API_IDMCD_DEFAULT_API_TOKENMCD_DEFAULT_PROFILEWhen creating a session any explicitly passedmcd_idandmcd_tokenparams 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.We do not recommend passingmcd_tokenas it is a secret and can be accidentally committed.Integration Gateway APIThere are features that require the Integration Gateway API instead of the regular GraphQL Application API, for example Airflow Callbacks invoked by theairflow-mcdlibrary.To use the Gateway you need to initialize theSessionobject passing ascopeparameter and then usemake_requestto invoke Gateway endpoints:frompycarlo.coreimportClient,Sessionclient=Client(session=Session(mcd_id='foo',mcd_token='bar',scope='AirflowCallbacks'))response=client.make_request(path='/airflow/callbacks',method='POST',body={},timeout_in_seconds=20)Advanced configurationThe 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 releasesTo update queries and mutations via introspection, usemake generate.make testcan be used to run all tests locally. CircleCI manages all testing for deployment. When ready for a review, create a PR againstmain.When ready to release, create a newGithub releasewith 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.ReferencesDashboard:https://getmontecarlo.comProduct docs:https://docs.getmontecarlo.comStatus page:https://status.getmontecarlo.comAPI (and SDK):https://apidocs.getmontecarlo.comCLI:https://clidocs.getmontecarlo.comLicenseApache 2.0 - See theLICENSEfor more information.