Route Functions and Python Function Style Guide

What is a Route Function?

A route function is a Python function designed to handle API calls through Domo endpoints. Key points include:

  • Decorator: Every route function must be decorated with @gd.route_function which helps standardize the behavior and error handling across the codebase.
  • Asynchronous Execution: Route functions are defined as async def to allow non-blocking HTTP requests via httpx.AsyncClient.
  • API Communication: They rely on the helper function gd.get_data to send requests. The response from gd.get_data is always an instance of rgd.ResponseGetData.
  • Response Validation: After making an API call, each function must verify the response by testing res.is_success. If the request fails, a custom exception (typically a subclass of dmde.RouteError) must be raised.
  • Parameters: Route functions expect at least the following:
    • auth: a dmda.DomoAuth (or dmda.DomoFullAuth) object for authentication.
    • session: an optional httpx.AsyncClient for managing requests.
    • debug_api: a boolean flag to enable extra logging or debugging.
    • parent_class: an optional parameter for passing context in error tracebacks.

Python Function Style Guide

General Guidelines:

  1. Function Naming:

    • Use snake_case for names.
    • Choose descriptive and concise names (e.g., get_application_by_id).

  2. Type Annotations:

    • Always include type hints for parameters and the return type.

    • Example:

      async def get_application_by_id(auth: dmda.DomoAuth, application_id: str) -> rgd.ResponseGetData:

  3. Docstrings:

    • Every function should have a docstring that describes its purpose, input arguments, and return value.

    • Example:

      """
Retrieves an application by its ID.

Args:
    auth (dmda.DomoAuth): Authentication object.
    application_id (str): The ID of the application to retrieve.

Returns:
    rgd.ResponseGetData: The response object containing application data.
"""

  4. Error Handling:

    • Always validate the response from gd.get_data by checking res.is_success.

    • On failure, raise a custom exception (typically an instance of a class derived from dmde.RouteError).

    • Example:

      if not res.is_success:
    raise dmde.RouteError(
        domo_instance=auth.domo_instance,
        function_name=res.traceback_details.function_name,
        message="API call failed",
    )

  5. Parameter Defaults and Optional Arguments:

    • Provide default values for optional parameters (e.g., debug_api: bool = False, session: httpx.AsyncClient = None).
    • Ensure defaults do not hide required information for API requests.

  6. API Request Pattern:

    • Route functions should always make API calls using gd.get_data (or similar helper functions such as gd.looper when pagination is needed).
    • Consistently map the response to a structured format or raise errors if the response indicates failure.

  7. Code Readability:

    • Use 4 spaces per indentation level.
    • Limit line lengths to 79 characters for readability.
    • Keep functions focused and avoid overly long implementations.

  8. Return Values:

    • Return only instances of rgd.ResponseGetData or restructured responses.
    • Ensure that a function either returns a valid response or raises an exception without returning ambiguous results.

By following these guidelines, route functions and other Python functions in the project will be consistent, maintainable, and convey clear intent. This style is based on the patterns exhibited in various modules (e.g., instance_config.py, appdb.py, group.py, etc.) where standardized error handling, response checking, and usage of the gd.get_data helper are consistently applied.