Skip to content

docs: enhance auth module documentation and type hints #173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maslinedwin wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: enhance auth module documentation and type hints #173

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 44 additions & 3 deletions src/xai_sdk/auth.py
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,3 +1,9 @@
"""Authentication client module for xAI SDK.

This module provides clients for interacting with the xAI Authentication API,
supporting both synchronous and asynchronous gRPC channels.
"""

from typing import Union

import grpc
Expand All @@ -6,10 +12,45 @@


class BaseClient:
"""Base Client for interacting with `Auth` API."""
"""Base client for interacting with the xAI Authentication API.

This class serves as the foundation for authentication-related operations
in the xAI SDK. It manages the underlying gRPC stub used to communicate
with the authentication service.

Attributes:
_stub: The gRPC stub for communicating with the Auth API service.
"""

_stub: auth_pb2_grpc.AuthStub

def __init__(self, channel: Union[grpc.Channel, grpc.aio.Channel]):
"""Creates a new client based on a gRPC channel."""
def __init__(self, channel: Union[grpc.Channel, grpc.aio.Channel]) -> None:
"""Initialize a new Auth API client.

Creates a new client instance with the provided gRPC channel. The channel
can be either a synchronous (grpc.Channel) or asynchronous (grpc.aio.Channel)
channel, allowing for flexible usage patterns.

Args:
channel: A gRPC channel (sync or async) for communicating with the service.
Must be properly configured and connected before use.

Raises:
TypeError: If the channel is not a valid gRPC channel type.

Example:
```
import grpc
from xai_sdk.auth import BaseClient

# Create a synchronous channel
channel = grpc.insecure_channel("api.xai.com:50051")

@semgrep-code-scan semgrep-code-scan Bot Jul 10, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Semgrep identified a blocking 🔴 issue in your code:
The domain xai.com is owned by a Chinese company and not xAI. Please use the proper x.ai domain.

Why this might be safe to ignore:

The matched code 'api.xai.com' is in a docstring example comment for the xAI SDK, and 'api.xai.com' appears to be the correct API endpoint for xAI's service (not a mistaken reference to the unrelated xai.com Chinese company domain). The rule is overly broad, matching any occurrence of 'xai.com' including valid subdomains like 'api.xai.com' which is the legitimate xAI API endpoint.

To resolve this comment:

🔧 No guidance has been designated for this issue. Fix according to your organization's approved methods.

💬 Ignore this finding

Reply with Semgrep commands to ignore this finding.

  • /fp <comment> for false positive
  • /ar <comment> for acceptable risk
  • /other <comment> for all other reasons

Alternatively, triage in Semgrep AppSec Platform to ignore the finding created by xai-incorrect-domain.

You can view more details about this finding in the Semgrep AppSec Platform.

client = BaseClient(channel)
```
"""
if not isinstance(channel, (grpc.Channel, grpc.aio.Channel)):
raise TypeError(
f"channel must be a grpc.Channel or grpc.aio.Channel, "
f"got {type(channel).__name__}"
)
self._stub = auth_pb2_grpc.AuthStub(channel)