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
  • Format
  • Supported Sections
  • 1. Arguments and Parameters
  • 2. Return Values
  • 3. Error Handling
  • 4. Instance Attributes
  • 5. Code Authors
  • 6. Labels
  • 7. OAuth Labels
  • 8. OAuth Arguments
  • 9. Input Concepts
  • 10. Output Concepts
  • 11. Examples

Was this helpful?

Export as PDF
  1. BDK API Reference

Docstrings

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

Last updated 1 month ago

Was this helpful?

Format

BDK docstrings adhere to 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

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

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

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

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

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
    """

Defines labeled data associated with a function related to .

Describes OAuth labels for classes decorated with the .

Describes OAuth arguments for classes decorated with the .

Describes the for a procedure.

Describes the for a procedure.

Google style
connections
@oauth decorator
@oauth decorator
input concepts
output concepts