docs: improve Python SDK public docstrings

[cesarenaldi]

Summary

• Add high-impact docstrings to sync and async public/secure clients for discovery, market data, trading, approvals, gasless wallet, and position workflows
• Document pagination helpers, transaction handles, and stream subscription specs
• Add concise class docstrings for core market, order, trade, balance, and position models

Linear

• Parent: DEV-118
• Child: DEV-122

Verification

• uv run ruff format src/polymarket/clients/public.py src/polymarket/clients/async_public.py src/polymarket/clients/secure.py src/polymarket/clients/async_secure.py src/polymarket/pagination.py src/polymarket/transactions.py src/polymarket/streams/_specs.py src/polymarket/models/clob/account.py src/polymarket/models/data/portfolio.py src/polymarket/models/gamma/market.py
• uv run ruff check src/polymarket/clients/public.py src/polymarket/clients/async_public.py src/polymarket/clients/secure.py src/polymarket/clients/async_secure.py src/polymarket/pagination.py src/polymarket/transactions.py src/polymarket/streams/_specs.py src/polymarket/models/clob/account.py src/polymarket/models/data/portfolio.py src/polymarket/models/gamma/market.py
• uv run pyright
• uv run pytest

---

Note

Low Risk
Documentation and test-only factory calls; no production API or business-logic changes.

Overview
This PR improves public API documentation across the Python SDK without changing runtime behavior for callers who use the documented entry points.

Clients (PublicClient, AsyncPublicClient, SecureClient, AsyncSecureClient): class-level docstrings, property docs, and method docstrings for discovery, market/CLOB reads, pagination, subscriptions, trading (sign/post/cancel), wallet approvals, gasless setup, and position lifecycle. Paginated methods document return types and include Examples on some async/sync list helpers. SecureClient.create / AsyncSecureClient.create gain full Args/Raises docs; factory logic stays on a new _create helper used by tests to skip credential validation.

Supporting modules: Page, Paginator, AsyncPaginator, transaction handle types, and stream specs (MarketSpec, CommentsSpec, etc.) get clearer descriptions. Core models (OpenOrder, ClobTrade, Position, Market nested types, etc.) get short class docstrings.

Tests only switch from create to _create where fake credentials are injected.

^{Reviewed by Cursor Bugbot for commit b02b53e. Bugbot is set up for automated code reviews on this repo. Configure here.}

[linear]

DEV-118 Open source the Python SDK repository

Plan

Start with a clear intake funnel and widen it gradually as we understand the volume and team capacity.

Initial open source launch

Make the Python SDK repository public. This phase is already in progress.

Before launch:

• Review the README and CONTRIBUTING guidelines.
• Review the security guidelines.
• Carefully review the GitHub history to make sure nothing sensitive is exposed.
• Enable GitHub Issues with templates for bug reports, feature requests, and general questions/feedback.
• Coordinate with David on a process to route GitHub Issues into Linear tickets, ideally with screening before issue creation or assignment.

External contributions

Open the repository to external contributions only once the SDK is stable and out of beta.

Before accepting external PRs:

• Provide secure sandboxing for running integration tests before accepting incoming PRs.
• Define strong CONTRIBUTING guidelines for how changes are accepted.
• Require large contributions to be discussed up front and agreed with the team.
• Flag selected GitHub Issues as good first PRs for external contributors to pick up.

Public feedback channel

Do not enable GitHub Discussions for the initial launch. Discussions may fragment the conversation. GitHub Issues should be the main public feedback channel for now.

DEV-122 Improve Python SDK public docstrings for open source launch

Context

The TypeScript SDK exposes rich TSDoc on public client methods and helpers. The Python SDK had strong typing but sparse docstrings on the user-facing surface, which reduced IDE discoverability for open source users.

Completed in this session

• Added high-impact docstrings across public and secure sync/async clients.
• Documented pagination helpers, transaction handles, and stream subscription specs.
• Added concise class docstrings for core market, order, trade, balance, and position models.
• Verified with formatting, linting, type checking, and the full test suite.

Verification

• uv run ruff check ...
• uv run pyright
• uv run pytest

Review in Linear