LogoLogo
About
  • Home
  • Guides
  • BDK
  • REST API
  • BDK Overview
  • Planning Guide
  • Setup Guide
  • Development Guide
  • Deployment
  • Learning a BDK Book
  • Connection Commands
  • BDK API Reference
    • Concepts
    • Connections
    • Decorators
      • @book
      • @concept
      • @config
      • @connect
      • @oauth
      • @oauthtoken
      • @procedure
    • Docstrings
    • Enums
      • FilterBinaryOperator
      • FilterUnaryOperator
    • Filter Expressions
    • Noun Phrases
    • Procedures
Powered by GitBook
On this page
  • Implementing Connections
  • Multiple Connections
  • Method Docstrings

Was this helpful?

Export as PDF
  1. BDK API Reference

Connections

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

Last updated 1 month ago

Was this helpful?

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 decorator. This decorated function serves as the connection handler and defines the syntax for writing a .

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 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 . 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"
@connect
connection command
@connect
connection command