GraphQL Base Module

The GraphQL module offers a simple yet flexible interface to wrap any Tenable GraphQL applications into the pyTenable SDK.

class GraphQLSession(url: str | None = None, api_key: str | None = None, verify: bool = True, schema_validation: bool = True, retries: int = 3, timeout: int = 300, vendor: str = 'unknown', product: str = 'unknown', build: str = 'unknown')

GraphQL API Session handler using the official GQL python library instead of Restfly.

_query_folder

The location to where stored query files exist. Because of how Parent-Child relationships work within python and how that effects file locations, this MUST be set within the child class. This should almost _always_ be set to: Path(__file__).parent.joinpath(‘queries’)

Type:

Path

_base_path

The URI path (excluding the root /) to where the GraphQL API resides.

Type:

str

_env_base

The environment variable prefix for the library.

Type:

str

_client

Set as part of initialization, however is the GQL library client that will be used to interface to the GQL API.

Type:

gql.Client

construct_query(query: str | StringIO | DocumentNode | None = None, stored_file: str | None = None) → DocumentNode

The query constructor takes any of the input types given and will return a DocumentNode containing the GraphQL query to be used with the query method.

As this method is called by both the query and validate methods directly, there generally isn’t a need to call this outside of those two methods.

Parameters:

• query (str | StringIO | DocumentNode, optional) – The query obj that we want to normalize into a DocumentNode.

• stored_file (str, optional) – The filename of a vendored (stored) graphql query to construct.

Returns:

DocumentNode

query(query: str | None = None, stored_file: str | None = None, keyword_arguments: Dict[str, Any] | None = None, iterator: GraphQLIterator | None = None, graphql_model: str | None = None, **variables: Any) → Dict[str, Any]

Query the GraphQL API

Parameters:

• query (str | StringIO | DocumentNode, optional) – The GraphQL query to pass to the remote API.

• stored_file (str, optional) –

  The filename of a vendored (stored) graphql query to construct.

  Note

  This parameter should not need to be used for outside of the library itself. All of the queries available with this parameter are also wrapped within the endpoint classes.

• iterator (GraphQLIterator, optional) – If specified, the response will be an instance of this iterable instead of the dictionary response. Useful for when the response data is expected to be larger datasets that would require multiple pages to collect all of the data.

• graphql_model (str, optional) – When using the iterator, we need to specify the base entity that is returned from the GraphQL response.

• keyword_argument (dict, optional) – Anything specified within this dictionary will be passed on to the gql libraries query method. While not expected to be commonly used, we’re exposing this here just incase we need it.

• **variables (dict, optional) – Any variable declarations that need to be passed along with the query.

Returns:

If no iterator is passed, then the response dictionary is

returned to the caller.

GraphQLIterator:

If an iterator class was passed, then the query is generated and the passed to the iterator nefore returning an instance of the iterator class.

Return type:

Dict

Example

A very basic example:

>>> session.query('{ hero { name } }')

An example using a variable within the query:

>>> query = '''
... query HeroNameAndFriends($episode: Episode) {
...   hero(episode: $episode) {
...     name
...     friends {
...       name
...     }
...   }
... }
>>> session.query(query, episode='JEDI')

validate(query: str | StringIO) → Dict[str, Any]

Validates the query against the schema and returns any validation errors that may have occured.

Parameters:

query (str | StringIO) – The query to validate against

Returns:

class GraphQLEndpoint(api: GraphQLSession)

A GraphQL Endpoint class to be used in-place of the Restfly-base endpoint adaptor.

_query(*args, **kwargs) → Dict[str, Any] | GraphQLIterator

Simple helper to call the api query

class GraphQLIterator(api, **kw)

An iterator class to be used with GraphQL paginated/iterable datasets.

next() → Any

Ask for the next record