get_celonis

get_celonis(url=None, api_token=None, key_type=None, return_object=False, verify_ssl=True, read_only=False, user_agent='pycelonis/1.7.7', timeout=120, total_retry=0, backoff_factor=1, cookie=None, connect=True, permissions=True, **kwargs)

Get a Celonis object or pass a fully qualified URL to get a specific Celonis Resource object, e.g. https://<team>.<realm>.celonis.cloud/package-manager/api/spaces/{space_id} to get the Space object directly.

Parameters:

Name	Type	Description	Default
url	str	Celonis base URL.	None
api_token	str	Celonis API token.	None
key_type	Union[str, KeyType]	KeyType of API token. One of [APP_KEY, USER_KEY] or celonis_api.utils.KeyType.	None
return_object	bool	Weather or not to return the requested object.	False
verify_ssl	bool	Requiring requests to verify the TLS certificate at the remote end. For more details see requests.Session.	True
read_only	bool	If True only GET methods are allowed, set to False to enable PUT, POST and DELETE methods.	False
user_agent	str	Session header value for User-Agent.	'pycelonis/1.7.7'
timeout	int	How long to wait for the server to send data before giving up (in seconds, 300 for data push/pull, max 600). For more details see requests.Session.request.	120
total_retry	int	Total number of retries (by default disabled, max. 10). For more details see urllib3.Retry.	0
backoff_factor	float	Factor to apply between retry attempts after the second try (by default disabled). [0.5 < backoff_factor < 5] : ({backoff_factor} * (2 ** ({total_retry} - 1))). For more details see urllib3.Retry.	1
cookie	str	Session header value for x-celonis-api-scope.	None
connect	bool	If True connects to Celonis on initialization (initial request to check if the token & key_type combination is correct).	True
permissions	bool	If True provides permission information.	True

Returns:

Type	Description
Any	The Celonis API object.

Source code in pycelonis/__init__.py

def get_celonis(
    url: str = None,
    api_token: str = None,
    key_type: typing.Union[str, 'KeyType'] = None,
    return_object: bool = False,
    verify_ssl: bool = True,
    read_only: bool = False,
    user_agent: str = "pycelonis/" + __version__,
    timeout: int = 120,
    total_retry: int = 0,
    backoff_factor: float = 1,
    cookie: str = None,
    connect: bool = True,
    permissions: bool = True,
    **kwargs,
) -> typing.Any:
    """Get a [Celonis][celonis_api.celonis.Celonis] object or pass a fully qualified URL to get a specific
    Celonis Resource object, e.g. `https://<team>.<realm>.celonis.cloud/package-manager/api/spaces/{space_id}` to get
    the [Space][celonis_api.studio.space.Space] object directly.

    Args:
        url: Celonis base URL.
        api_token: Celonis API token.
        key_type: KeyType of API token. One of [`APP_KEY`, `USER_KEY`] or [celonis_api.utils.KeyType][].
        return_object: Weather or not to return the requested object.
        verify_ssl: Requiring requests to verify the TLS certificate at the remote end.<br />
            For more details see [`requests.Session`](https://docs.python-requests.org/en/latest/api/#requests.Session).
        read_only: If True only GET methods are allowed, set to False to enable PUT, POST and DELETE methods.
        user_agent: Session header value for `User-Agent`.
        timeout: How long to wait for the server to send data before giving up
            (in seconds, 300 for data push/pull, max 600).<br />
            For more details see
            [`requests.Session.request`](https://docs.python-requests.org/en/latest/api/#requests.Session.request).
        total_retry: Total number of retries (by default disabled, max. 10).<br />
            For more details see
            [`urllib3.Retry`](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#urllib3.util.Retry).
        backoff_factor: Factor to apply between retry attempts after the second try (by default disabled).<br />
            `[0.5 < backoff_factor < 5]` : (`{backoff_factor} * (2 ** ({total_retry} - 1))`).<br />
            For more details see
            [`urllib3.Retry`](https://urllib3.readthedocs.io/en/latest/reference/urllib3.util.html#urllib3.util.Retry).
        cookie: Session header value for `x-celonis-api-scope`.
        connect: If True connects to Celonis on initialization
            (initial request to check if the `token` & `key_type` combination is correct).
        permissions: If True provides permission information.

    Returns:
        The Celonis API object.
    """
    if "celonis_url" in kwargs:
        warnings.warn(
            "Using argument 'celonis_url' with get_celonis is deprecated and "
            "will be removed in version 2.0. Use 'url' instead.",
            DeprecationWarning,
            stacklevel=2,
        )
        url = kwargs.get("celonis_url")

    if not url:
        url = _read_url_from_env()

    if key_type is None:
        key_type = _read_key_type_from_env()

    if not api_token:
        api_token = _read_api_token_from_env()

    is_outdated, latest_version = check_outdated(__version__)
    if is_outdated:
        logger.info(
            f"Your PyCelonis Version {__version__} is outdated (Newest Version: {latest_version}). "
            "Please upgrade the package via: "
            "pip install --extra-index-url=https://pypi.celonis.cloud/ pycelonis --upgrade"
        )
        if latest_version.major == 2:
            logger.warning(
                f"Version {latest_version} is a major version change that includes breaking changes. "
                "Checkout the docs and read the migration guide first."
            )

    # EMS Cloud
    if ".celonis.cloud" in url:
        from pycelonis.celonis_api.celonis import Celonis

        celonis = Celonis(
            url=url,
            api_token=api_token,
            key_type=key_type,
            read_only=read_only,
            verify_ssl=verify_ssl,
            user_agent=user_agent,
            timeout=timeout,
            total_retry=total_retry,
            backoff_factor=backoff_factor,
            cookie=cookie,
            connect=connect,
            permissions=permissions,
        )
    else:
        from pycelonis.celonis_api.errors import PyCelonisError

        raise PyCelonisError(
            "Deprecation: The module objects_cmp4 is deprecated.\n"
            "To connect to Celonis from Python please refer to the "
            "python package celonis_tools which can be downloaded here:\n"
            "https://help.celonis.de/display/PYT/Python+API."
        )

    if return_object:
        return Celonis.from_url(
            url=url,
            api_token=api_token,
            key_type=key_type,
            read_only=read_only,
            verify_ssl=verify_ssl,
            user_agent=user_agent,
            timeout=timeout,
            total_retry=total_retry,
            backoff_factor=backoff_factor,
            cookie=cookie,
            connect=connect,
            permissions=permissions,
        )

    return celonis