Docstrings

Understand how to format and write docstrings to ensure your Book is well-documented.

Format

BDK docstrings adhere to Google style formatting:

• Docstrings are placed immediately after function, class, or method definitions.

• A brief summary that describes the functionality begins the docstring.

• The summary is followed by organized sections, separated by blank lines and labeled with headers.

In BDK projects, docstrings are applied to decorated methods and classes.

---

Supported Sections

The following sections are supported in BDK docstrings, with alternative headers available for labeling flexibility.

1. Arguments and Parameters

Documents the arguments or parameters that a function or class accepts.

Supported Headers: Args, Arguments, Parameters, Params

Example

@procedure("to add two numbers")
def add_numbers(a: int, b: int = 0) -> int:
    """
    Adds two numbers together.

    Args:
        a: The first number.
        b: The second number. Defaults to 0.
    """
    return a + b

2. Return Values

Documents the return value of a function or method.

Supported Headers: Returns

Example

@procedure("to send an *SMS* message")
def send_sms_message(self, sender_number: str, recipient_number: str, message_body: str) -> Optional[str]:
    """
    Sends an SMS message using the Twilio API.

    Returns:
        The SID of the sent message if successful, otherwise None.
    """

3. Error Handling

Lists any exceptions or errors that a function might raise.

Supported Headers: Raises, Exceptions, Except

Example

@timeout.setter
def timeout(self, timeout: float):
    """
    Sets the timeout value in milliseconds.

    Args:
        timeout (int): The timeout value to set. Must be a positive integer.

    Raises:
        ValueError: If the timeout value is less than or equal to 0.

    """
    if timeout <= 0:
        raise ValueError("timeout must be positive")
    self._timeout = timeout

4. Instance Attributes

List instance attributes in a class.

Supported Headers: Attributes

Example

@concept(is_a="office user")
@dataclass
class OfficeUser:
    """
    An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,
    email address, and job title.

    Attributes:
        id: The unique identifier for the user.
        display_name: The name displayed in the address book for the user.
        email_address: The user's email address (usually their user principal name).
        job_title: The user's job title.
    """

    id: str
    display_name: Optional[str] = None
    email_address: Optional[str] = None
    job_title: Optional[str] = None

5. Code Authors

Attributes the author(s) of the code.

Supported Headers: Author

Example

@book(name="Sample Book")
class SampleBook:
    """
    A book shown as an example.

    Author:
      Kognitos
    """

6. Labels

Defines labeled data associated with a function related to connections.

Supported Headers: Labels

Example

@connect(noun_phrase="api keys")
def connect(self, api_key: str):
    """
    Authenticate to Open Weather API using the specified API key.

    Labels:
        api_key: API Key
    """

7. OAuth Labels

Describes OAuth labels for classes decorated with the @oauth decorator.

Supported Headers: OAuth Labels

Example

@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.Manage.All",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
        "https://graph.microsoft.com/User.ReadWrite.All",
        "https://graph.microsoft.com/Directory.ReadWrite.All",
        "https://graph.microsoft.com/Group.ReadWrite.All",
        "https://graph.microsoft.com/GroupMember.ReadWrite.All",
        "https://graph.microsoft.com/Mail.ReadWrite",
        "https://graph.microsoft.com/Mail.ReadWrite.Shared",
        "https://graph.microsoft.com/Mail.Send",
        "https://graph.microsoft.com/Calendars.ReadWrite",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
    """
    Base class for all Microsoft Books.

    OAuth Arguments:
        TENANT_ID: The tenant ID of the Azure AD directory.

    OAuth Labels:
        TENANT_ID: Tenant ID
    """

8. OAuth Arguments

Describes OAuth arguments for classes decorated with the @oauth decorator.

Supported Headers: OAuth Arguments

Example

@oauth(
    id="oauth",
    provider=OAuthProvider.MICROSOFT,
    flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
    authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
    token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
    scopes=[
        "https://graph.microsoft.com/Files.ReadWrite",
        "https://graph.microsoft.com/Sites.Manage.All",
        "https://graph.microsoft.com/Sites.ReadWrite.All",
        "https://graph.microsoft.com/User.ReadWrite.All",
        "https://graph.microsoft.com/Directory.ReadWrite.All",
        "https://graph.microsoft.com/Group.ReadWrite.All",
        "https://graph.microsoft.com/GroupMember.ReadWrite.All",
        "https://graph.microsoft.com/Mail.ReadWrite",
        "https://graph.microsoft.com/Mail.ReadWrite.Shared",
        "https://graph.microsoft.com/Mail.Send",
        "https://graph.microsoft.com/Calendars.ReadWrite",
    ],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
    """
    Base class for all Microsoft Books.

    OAuth Arguments:
        TENANT_ID: The tenant ID of the Azure AD directory.

    OAuth Labels:
        TENANT_ID: Tenant ID
    """

9. Input Concepts

Describes the input concepts for a procedure.

Supported Headers: Input Concepts

Example

@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Input Concepts:
        the city: The name of the city. Please refer to ISO 3166 for the state codes or country codes.
        the unit: Unit of measurement. standard, metric and imperial units are available. If you do
            not specify the units, metric units will be applied by default.
    """

10. Output Concepts

Describes the output concepts for a procedure.

Supported Headers: Output Concepts

Example

@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Output Concepts:
        the current temperature: The current temperature in the specified units of measurement, or None if an error occurs.
    """

11. Examples

Outlines usage examples for a procedure.

Supported Headers: Example, Examples, Example [1-5]

Example

@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
    """
    Fetch the current temperature for a specified city.

    Example 1:
        Retrieve the current temperature at London

        >>> get the current temperature at London

    Example 2:
        Retrieve the current temperature at London in Celsius

        >>> get the current temperature at Buenos Aires with
        ...     the unit is metric
    """