# Docstrings

## Format

BDK docstrings adhere to [**Google style**](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) 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**

```python
@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**

```python
@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**

```python
@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**

```python
@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**

```python
@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](/legacy/legacy-experience/books/custom-books/api-reference/connections.md).

**Supported Headers**: `Labels`

**Example**

```python
@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](/legacy/legacy-experience/books/custom-books/api-reference/decorators/oauth-decorator.md).

**Supported Headers**: `OAuth Labels`

**Example**

```python
@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](/legacy/legacy-experience/books/custom-books/api-reference/decorators/oauth-decorator.md).

**Supported Headers**: `OAuth Arguments`

**Example**

```python
@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**](/legacy/legacy-experience/books/custom-books/api-reference/concepts.md) for a procedure.

**Supported Headers**: `Input Concepts`

**Example**

```python
@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**](/legacy/legacy-experience/books/custom-books/api-reference/concepts.md) for a procedure.

**Supported Headers**: `Output Concepts`

**Example**

```python
@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**

```python
@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
    """
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.kognitos.com/legacy/legacy-experience/books/custom-books/api-reference/docstrings.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.