Expose the default retry policy for caller-managed Sessions

[Mattsface]

Expose the default retry policy for caller-managed Sessions

Why

Version 0.8.0 applies the default retry policy only to library-created Sessions.

This preserves ownership of caller-injected Sessions, but users who inject a Session for custom pooling, proxies, TLS configuration, or headers cannot reuse the library’s tested retry policy through a supported public API.

Parent release issue: #265

Scope

Expose the default retry policy through a stable public function.

Suggested usage:

import requests
import mlbstatsapi

session = requests.Session()

adapter = requests.adapters.HTTPAdapter(
    max_retries=mlbstatsapi.create_retry_policy(),
    pool_maxsize=20,
)

session.mount("https://", adapter)
session.mount("http://", adapter)

mlb = mlbstatsapi.Mlb(session=session)

The library must not automatically mount adapters on an injected Session.

Required behavior

The public policy must preserve the version 0.8.0 defaults:

Maximum retries: 3
Backoff factor: 0.5
Allowed methods: GET
Retry-After respected: yes

Retryable status codes:

429
500
502
503
504

Ordinary client errors such as 400, 401, 403, and 404 must remain non-retryable.

Public API

Suggested public name:

create_retry_policy()

Users should not need to import an underscore-prefixed private helper.

Testing requirements

• The function returns an urllib3 Retry instance
• The policy contains the documented status list
• Only GET is allowed
• Retry limits remain bounded
• Retry-After support remains enabled
• Separate calls return independent policy instances
• Library-created Sessions use the same public policy
• Injected Sessions remain unchanged unless the caller mounts it
• The function is available through the supported package API

Suggested branch

feat/public-retry-policy

The branch should start from and target:

release/0.9.0

Acceptance criteria

• The retry policy is publicly importable
• Library-created Sessions continue using the same behavior
• Caller-injected Sessions can explicitly opt in
• Caller-owned adapters are never silently replaced
• Existing version 0.8.0 retry tests continue passing
• Documentation includes an injected Session example

Not included

• Automatically modifying injected Sessions
• A custom retry implementation
• Async retries
• Global throttling
• Response caching
• Changing the default retry values