Skip to content

Commit 4e0a4ec

Browse files
camodotggcamodotgg
committed
docs: auto-generate API reference from source code
1 parent 0028548 commit 4e0a4ec

13 files changed

Lines changed: 511 additions & 582 deletions

File tree

‎docs/api/client.md‎

Lines changed: 26 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,34 @@
11
# Client Reference
22

3-
## MCSRRanked
4-
5-
The synchronous client for the MCSR Ranked API.
6-
7-
```python
8-
from mcsrranked import MCSRRanked
9-
10-
client = MCSRRanked(
11-
api_key=None, # API key for expanded rate limits
12-
private_key=None, # Private key for live data
13-
base_url=None, # Custom API base URL
14-
timeout=30.0, # Request timeout in seconds
15-
max_retries=2, # Maximum retry attempts
16-
)
17-
```
18-
19-
### Constructor Parameters
20-
21-
| Parameter | Type | Default | Description |
22-
|-----------|------|---------|-------------|
23-
| `api_key` | `str \| None` | `None` | API key for expanded rate limits. Falls back to `MCSRRANKED_API_KEY` env var. |
24-
| `private_key` | `str \| None` | `None` | Private key for live data. Falls back to `MCSRRANKED_PRIVATE_KEY` env var. |
25-
| `base_url` | `str \| None` | `"https://api.mcsrranked.com"` | API base URL. |
26-
| `timeout` | `float \| None` | `30.0` | Request timeout in seconds. |
27-
| `max_retries` | `int \| None` | `2` | Maximum number of retries. |
28-
29-
### Resources
30-
31-
| Resource | Description |
32-
|----------|-------------|
33-
| `client.users` | User profiles, matches, versus stats |
34-
| `client.matches` | Match listings and details |
35-
| `client.leaderboards` | Elo, phase, and record leaderboards |
36-
| `client.live` | Online players and live streams |
37-
| `client.weekly_races` | Weekly race data |
38-
39-
### Methods
40-
41-
#### `with_options(**kwargs)`
42-
43-
Create a new client with modified options:
44-
45-
```python
46-
new_client = client.with_options(timeout=60.0)
47-
```
48-
49-
#### `close()`
50-
51-
Close the HTTP client:
52-
53-
```python
54-
client.close()
55-
```
56-
57-
### Context Manager
58-
59-
```python
60-
with MCSRRanked() as client:
61-
user = client.users.get("Feinberg")
62-
# Client automatically closed
63-
```
3+
## Synchronous Client
4+
5+
::: mcsrranked.MCSRRanked
6+
options:
7+
members:
8+
- __init__
9+
- users
10+
- matches
11+
- leaderboards
12+
- live
13+
- weekly_races
14+
- with_options
15+
- close
6416

6517
---
6618

67-
## AsyncMCSRRanked
68-
69-
The asynchronous client for the MCSR Ranked API.
70-
71-
```python
72-
from mcsrranked import AsyncMCSRRanked
73-
74-
client = AsyncMCSRRanked(
75-
api_key=None,
76-
private_key=None,
77-
base_url=None,
78-
timeout=30.0,
79-
max_retries=2,
80-
)
81-
```
82-
83-
### Async Context Manager
84-
85-
```python
86-
async with AsyncMCSRRanked() as client:
87-
user = await client.users.get("Feinberg")
88-
# Client automatically closed
89-
```
90-
91-
### Async Methods
92-
93-
All resource methods are async:
94-
95-
```python
96-
user = await client.users.get("Feinberg")
97-
matches = await client.matches.list()
98-
leaderboard = await client.leaderboards.elo()
99-
```
100-
101-
### Async Close
102-
103-
```python
104-
await client.close()
105-
```
19+
## Asynchronous Client
20+
21+
::: mcsrranked.AsyncMCSRRanked
22+
options:
23+
members:
24+
- __init__
25+
- users
26+
- matches
27+
- leaderboards
28+
- live
29+
- weekly_races
30+
- with_options
31+
- close
10632

10733
---
10834

‎docs/api/exceptions.md‎

Lines changed: 39 additions & 107 deletions
Original file line numberDiff line numberDiff line change
@@ -10,151 +10,83 @@ MCSRRankedError
1010
│ │ ├── AuthenticationError
1111
│ │ ├── NotFoundError
1212
│ │ └── RateLimitError
13-
│ ├── APIConnectionError
14-
│ └── APITimeoutError
13+
│ └── APIConnectionError
14+
│ └── APITimeoutError
1515
```
1616

1717
---
1818

1919
## Base Exceptions
2020

21-
### MCSRRankedError
21+
::: mcsrranked.MCSRRankedError
22+
options:
23+
show_docstring_attributes: true
2224

23-
Base exception for all SDK errors.
24-
25-
```python
26-
from mcsrranked import MCSRRankedError
27-
28-
try:
29-
user = mcsrranked.users.get("someone")
30-
except MCSRRankedError as e:
31-
print(f"SDK error: {e}")
32-
```
33-
34-
### APIError
35-
36-
Base exception for API-related errors.
37-
38-
| Attribute | Type | Description |
39-
|-----------|------|-------------|
40-
| `message` | `str` | Error message |
25+
::: mcsrranked.APIError
26+
options:
27+
show_docstring_attributes: true
4128

4229
---
4330

4431
## HTTP Status Exceptions
4532

46-
### APIStatusError
47-
48-
Exception for HTTP error responses.
33+
::: mcsrranked.APIStatusError
34+
options:
35+
show_docstring_attributes: true
4936

50-
| Attribute | Type | Description |
51-
|-----------|------|-------------|
52-
| `message` | `str` | Error message |
53-
| `status_code` | `int` | HTTP status code |
54-
| `response` | `httpx.Response` | Raw response object |
55-
| `body` | `object \| None` | Response body |
37+
::: mcsrranked.BadRequestError
5638

57-
### BadRequestError
39+
::: mcsrranked.AuthenticationError
5840

59-
Raised for HTTP 400 responses (invalid parameters).
41+
::: mcsrranked.NotFoundError
6042

61-
```python
62-
from mcsrranked import BadRequestError
43+
::: mcsrranked.RateLimitError
6344

64-
try:
65-
matches = mcsrranked.matches.list(count=1000)
66-
except BadRequestError as e:
67-
print(f"Status: {e.status_code}") # 400
68-
print(f"Message: {e.message}")
69-
```
45+
---
7046

71-
### AuthenticationError
47+
## Connection Exceptions
7248

73-
Raised for HTTP 401 responses (invalid credentials).
49+
::: mcsrranked.APIConnectionError
7450

75-
```python
76-
from mcsrranked import AuthenticationError
51+
::: mcsrranked.APITimeoutError
7752

78-
try:
79-
live = mcsrranked.users.live("uuid")
80-
except AuthenticationError as e:
81-
print(f"Status: {e.status_code}") # 401
82-
```
53+
---
8354

84-
### NotFoundError
55+
## Usage Examples
8556

86-
Raised for HTTP 404 responses (resource not found).
57+
### Catching all SDK errors
8758

8859
```python
89-
from mcsrranked import NotFoundError
60+
from mcsrranked import MCSRRankedError
9061

9162
try:
92-
user = mcsrranked.users.get("nonexistent")
93-
except NotFoundError as e:
94-
print(f"Status: {e.status_code}") # 404
63+
user = mcsrranked.users.get("someone")
64+
except MCSRRankedError as e:
65+
print(f"SDK error: {e}")
9566
```
9667

97-
### RateLimitError
98-
99-
Raised for HTTP 429 responses (too many requests).
68+
### Catching specific errors
10069

10170
```python
102-
from mcsrranked import RateLimitError
71+
from mcsrranked import NotFoundError, RateLimitError
10372

10473
try:
105-
# Too many requests
106-
for i in range(1000):
107-
mcsrranked.users.get("Feinberg")
74+
user = mcsrranked.users.get("nonexistent")
75+
except NotFoundError as e:
76+
print(f"User not found: {e.status_code}")
10877
except RateLimitError as e:
109-
print(f"Status: {e.status_code}") # 429
110-
```
111-
112-
---
113-
114-
## Connection Exceptions
115-
116-
### APIConnectionError
117-
118-
Raised for network-related errors.
119-
120-
```python
121-
from mcsrranked import APIConnectionError
122-
123-
try:
124-
user = mcsrranked.users.get("Feinberg")
125-
except APIConnectionError as e:
126-
print(f"Connection failed: {e.message}")
78+
print(f"Rate limited: {e.status_code}")
12779
```
12880

129-
### APITimeoutError
130-
131-
Raised when a request times out. Inherits from `APIConnectionError`.
81+
### Accessing error details
13282

13383
```python
134-
from mcsrranked import APITimeoutError, MCSRRanked
135-
136-
client = MCSRRanked(timeout=1.0)
84+
from mcsrranked import APIStatusError
13785

13886
try:
139-
user = client.users.get("Feinberg")
140-
except APITimeoutError as e:
141-
print(f"Request timed out: {e.message}")
142-
```
143-
144-
---
145-
146-
## Import All Exceptions
147-
148-
```python
149-
from mcsrranked import (
150-
MCSRRankedError,
151-
APIError,
152-
APIStatusError,
153-
APIConnectionError,
154-
APITimeoutError,
155-
BadRequestError,
156-
AuthenticationError,
157-
NotFoundError,
158-
RateLimitError,
159-
)
87+
user = mcsrranked.users.get("invalid")
88+
except APIStatusError as e:
89+
print(f"Status: {e.status_code}")
90+
print(f"Message: {e.message}")
91+
print(f"Body: {e.body}")
16092
```

0 commit comments

Comments
 (0)