Connections

Learn how to connect with third-party tools and services in your custom book project.

Implementing Connections

Connections enable you to connect to third-party tools and services in your custom Book. To implement a connection, define a Python function in your Book class and decorate it with the @connect decorator. This decorated function serves as the connection handler and defines the syntax for writing a connection command.

Note: Implementing an OAuth connection in a custom BDK Book is not supported at this time.

Multiple Connections

You can define multiple connections within a Book, each with its own handler method. Use the noun_phrase keyword argument in the @connect decorator to assign a unique label to each connection and differentiate between authentication methods.

Method Docstrings

In your connection method docstring, include the following sections in addition to a brief summary:

1. Arguments

Specify the Python function's parameters.

2. Labels

Define labels for the connection arguments (e.g., API key, credentials) that will be used in your connection command. Labels correspond to parameters in your function's definition.

When a label is provided in the docstring, the lowercase form is used in a connection command. When not provided, the label will be inferred from the Python variable name.

Example

@connect(noun_phrase="api keys")
def connect(self, api_key: str):
    """
    Authenticate to Open Weather API using the specified API key. You can obtain your own API key by visiting
    Open Weather's website at https://openweathermap.org/appid.

    Arguments:
        api_key: The API key to be used for connecting

    Labels:
        api_key: API Key
    """

    api_key = os.getenv("API_KEY", api_key)
    test_url = f"{self._base_url}?appid={api_key}&q=London"
    response = requests.get(test_url, timeout=self._timeout)
    if response.status_code == 401:
        response_data = response.json()
        if "Invalid API key" in response_data.get("message", ""):
            raise ValueError("Invalid API key")

    self._api_key = api_key

In this example, API Key is the label for the api_key connection argument. The lowercase version of the label is used in a connection command (api key):

connect openweather via some api keys method with
    the api key is "aBcDefg1234"

Additional Examples

1. api_key: ApI kEy

In this example, the connection command uses the lowercase form of ApI kEy:

connect openweather via some api keys method with
    the api key is "aBcDefg1234"

1. api_key: aPi_KeY

In this example, the connection command uses the lowercase version of aPi_KeY:

connect openweather via some api keys method with
    the api_key is "aBcDefg1234"

1. No Label

If a label is not provided in the docstring, it is inferred from the Python variable name, api_key:

connect openweather via some api keys method with
    the api key is "aBcDefg1234"