> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-extend-api-reference-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# openhands.sdk.utils

> API reference for openhands.sdk.utils module

Utility functions for the OpenHands SDK.

### deprecated()

Return a decorator that deprecates a callable with explicit metadata.

Use this helper when you can annotate a function, method, or property with
@deprecated(…). It transparently forwards to `deprecation.deprecated()`
while filling in the SDK’s current version metadata unless custom values are
supplied.

### maybe\_truncate()

Truncate the middle of content if it exceeds the specified length.

Keeps the head and tail of the content to preserve context at both ends.
Optionally saves the full content to a file for later investigation.

* Parameters:
  * `content` – The text content to potentially truncate
  * `truncate_after` – Maximum length before truncation. If None, no truncation occurs
  * `truncate_notice` – Notice to insert in the middle when content is truncated
  * `save_dir` – Working directory to save full content file in
  * `tool_prefix` – Prefix for the saved file (e.g., “bash”, “browser”, “editor”)
* Returns:
  Original content if under limit, or truncated content with head and tail
  preserved and reference to saved file if applicable

### page\_iterator()

Iterate over items from paginated search results.

This utility function handles pagination automatically by calling the search
function repeatedly with updated page\_id parameters until all pages are
exhausted.

* Parameters:
  * `search_func` – An async function that returns a PageProtocol\[T] object
    with ‘items’ and ‘next\_page\_id’ attributes
    `args`\*\* – Positional arguments to pass to the search function
    `kwargs`\* – Keyword arguments to pass to the search function
* Yields:
  Individual items of type T from each page

#### Example

```python theme={null}
async for event in page_iterator(event_service.search_events, limit=50):
await send_event(event, websocket)

async for conversation in page_iterator(
conversation_service.search_conversations,
  execution_status=ConversationExecutionStatus.RUNNING

):
print(conversation.title)
```

### sanitize\_openhands\_mentions()

Sanitize @OpenHands mentions in text to prevent self-mention loops.

This function inserts a zero-width joiner (ZWJ) after the @ symbol in
@OpenHands mentions, making them non-clickable in GitHub comments while
preserving readability. The original case of the mention is preserved.

* Parameters:
  `text` – The text to sanitize
* Returns:
  Text with sanitized @OpenHands mentions (e.g., “@OpenHands” -> “@‍OpenHands”)

### Examples

```pycon theme={null}
>>> sanitize_openhands_mentions("Thanks @OpenHands for the help!")
'Thanks @u200dOpenHands for the help!'
>>> sanitize_openhands_mentions("Check @openhands and @OPENHANDS")
'Check @u200dopenhands and @u200dOPENHANDS'
>>> sanitize_openhands_mentions("No mention here")
'No mention here'
```

### sanitized\_env()

Return a copy of env with sanitized values.

PyInstaller-based binaries rewrite `LD_LIBRARY_PATH` so their vendored
libraries win. This function restores the original value so that subprocess
will not use them.

### warn\_deprecated()

Emit a deprecation warning for dynamic access to a legacy feature.

Prefer this helper when a decorator is not practical—e.g. attribute accessors,
data migrations, or other runtime paths that must conditionally warn. Provide
explicit version metadata so the SDK reports consistent messages and upgrades
to `deprecation.UnsupportedWarning` after the removal threshold.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.