Skip to content

Commit a342fc8

Browse files
Jon-BeckerJon-Becker
authored
Merge pull request #10 from TransposeData/new-docs
New documentation - much cooler than last time!
2 parents e9c74f5 + 51fe5ae commit a342fc8

File tree

6 files changed

+357
-2141
lines changed

6 files changed

+357
-2141
lines changed

‎docs/block.md‎

Lines changed: 65 additions & 464 deletions
Large diffs are not rendered by default.

‎docs/cdn.md‎

Lines changed: 40 additions & 97 deletions
Original file line numberDiff line numberDiff line change
@@ -3,10 +3,20 @@
33

44
The **Transpose CDN** provides supplementary data for endpoints across the Transpose API suite, including raw block data, NFT images, media, and metadata, collection images, and token symbols.
55

6-
## Data Models
7-
When querying the Transpose CDN, you will be dealing with the ``CDNResponse`` model.
6+
# Endpoint Specifications
7+
8+
## Query Endpoints
9+
10+
| SDK Method | Endpoint URL | Returns |
11+
| ---------------------- | ------------ | ------------- |
12+
| `cdn.query(endpoint)` | `*` | `CDNResponse` |
13+
| `cdn.bulk_query(endpoints, requests_per_second)` | `*` | `List[CDNResponse]` |
14+
815

916
### CDN Response Model
17+
<details>
18+
<summary>View Model Specification</summary>
19+
1020
The **CDN Response Model** contains the content type, content, and helper methods which can assist you in working with CDN data. The **CDN Record Model** follows the following structure:
1121

1222
#### Attributes
@@ -26,104 +36,37 @@ The **CDN Response Model** contains the content type, content, and helper method
2636
| json | Attempt to get the CDNResponse.contents as a dict. | `CDNResponse.json()` |
2737
| image | Attempt to parse the CDNResponse as a PIL image. | `CDNResponse.image()` |
2838

39+
</details>
2940

30-
# Endpoint Specifications
3141

32-
## Query Endpoints
42+
## Download Endpoints
3343

34-
### Single Query
35-
This endpoint returns the CDN response for a given query.
36-
37-
#### Usage
38-
```
39-
cdn.query(endpoint)
40-
```
41-
42-
#### Query Parameters
43-
| Parameter | Required | Description | Type |
44-
| --------- | -------- | ---------------------- | ------ |
45-
| endpoint | Yes | The endpoint to query. | string |
46-
47-
#### Responses
48-
| Code | Title | Model |
49-
| ---- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
50-
| 200 | Success | [CDN Response](https://github.com/TransposeData/transpose-python-sdk/tree/main/docs/cdn.md#CDN-Response-Model) |
51-
| 400 | Bad Request | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
52-
| 403 | Forbidden | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
53-
| 404 | Not Found | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
54-
| 500 | Internal Server Error | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
55-
56-
57-
### Bulk Query
58-
This endpoint returns the CDN responses for a given query.
59-
60-
#### Usage
61-
```
62-
cdn.query(endpoints, requests_per_second)
63-
```
64-
65-
#### Query Parameters
66-
| Parameter | Required | Description | Type |
67-
| ------------------- | -------- | ------------------------------------------ | -------- |
68-
| endpoints | Yes | The endpoint to query. | string[] |
69-
| requests_per_second | No | The number of requests to send per second. | int |
70-
71-
#### Responses
72-
| Code | Title | Model |
73-
| ---- | --------------------- | -------------------------------------------------------------------------------------------------------------- |
74-
| 200 | Success | [CDN Response](https://github.com/TransposeData/transpose-python-sdk/tree/main/docs/cdn.md#CDN-Response-Model) |
75-
| 400 | Bad Request | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
76-
| 403 | Forbidden | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
77-
| 404 | Not Found | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
78-
| 500 | Internal Server Error | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
44+
| SDK Method | Endpoint URL | Returns |
45+
| ---------------------- | ------------ | ------------- |
46+
| `cdn.save(endpoint)` | `*` | `None` |
47+
| `cdn.bulk_save(endpoints, requests_per_second, dir)` | `*` | `None` |
7948

49+
### CDN Response Model
50+
<details>
51+
<summary>View Model Specification</summary>
8052

81-
## Download Endpoints
53+
The **CDN Response Model** contains the content type, content, and helper methods which can assist you in working with CDN data. The **CDN Record Model** follows the following structure:
54+
55+
#### Attributes
56+
57+
| Name | Description | Type |
58+
| ------------ | ----------------------------- | ------ |
59+
| content_type | The content type of the data. | string |
60+
| content | The data returned by the CDN. | string |
61+
62+
#### Methods
63+
64+
| Name | Description | Usage |
65+
| ------------ | -------------------------------------------------- | -------------------------------- |
66+
| to_dict | Returns a dictionary representation of the model. | `CDNResponse.to_dict()` |
67+
| \_\_dict\_\_ | Returns a dictionary representation of the model. | `CDNResponse.__dict__()` |
68+
| save | Saves to model to the disk | `CDNResponse.save(path: string)` |
69+
| json | Attempt to get the CDNResponse.contents as a dict. | `CDNResponse.json()` |
70+
| image | Attempt to parse the CDNResponse as a PIL image. | `CDNResponse.image()` |
8271

83-
### Single Save
84-
This endpoint saves a file from the CDN to the local disc.
85-
86-
#### Usage
87-
```
88-
cdn.query(endpoint, path)
89-
```
90-
91-
#### Query Parameters
92-
| Parameter | Required | Description | Type |
93-
| --------- | -------- | ----------------------------- | ------ |
94-
| endpoint | Yes | The endpoint to query. | string |
95-
| path | No | The path to save the file to. | string |
96-
97-
#### Responses
98-
| Code | Title | Model |
99-
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
100-
| 200 | Success | None |
101-
| 400 | Bad Request | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
102-
| 403 | Forbidden | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
103-
| 404 | Not Found | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
104-
| 500 | Internal Server Error | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
105-
106-
107-
### Bulk Query
108-
This endpoint saves multiple files from the CDN to the local disc.
109-
110-
#### Usage
111-
```
112-
cdn.query(endpoints, requests_per_second, dir)
113-
```
114-
115-
#### Query Parameters
116-
| Parameter | Required | Description | Type |
117-
| ------------------- | -------- | ------------------------------------------ | -------- |
118-
| endpoints | Yes | The endpoint to query. | string[] |
119-
| requests_per_second | No | The number of requests to send per second. | int |
120-
| dir | No | The directory to save the files to. | string |
121-
122-
#### Responses
123-
| Code | Title | Model |
124-
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------ |
125-
| 200 | Success | None |
126-
| 400 | Bad Request | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
127-
| 403 | Forbidden | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
128-
| 404 | Not Found | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
129-
| 500 | Internal Server Error | [Error](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/documentation.md#Error-Classes) |
72+
</details>

‎docs/documentation.md‎

Lines changed: 22 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ You can find specific documentation on a per-product basis below.
99
| <img src="https://assets.website-files.com/624cc12cbb8535a77bafc47d/628d465b6551e284a9ae73e4_Wallet_Logo_ENS.png" width="50" height="50"><br> ENS API | The ENS API provides endpoints for looking up ENS names (both historical and primary), resolving ENS names and records, and monitoring ENS transfers and sales. | [ENS API Docs](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/ens.md) |
1010
| <img src="https://assets.website-files.com/624cc12cbb8535a77bafc47d/6286795ef57a1412d6d767fc_NFT_Logo_Solid.png" width="50" height="50"><br> NFT API | The NFT API provides endpoints for retrieving any collection and NFT in existence, as well as NFT images, operators, owners, transfers, approvals, and much more (fully supports both ERC-721 and ERC-1155 NFTs). | [NFT API Docs](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/nft.md) |
1111
| <img src="https://assets.website-files.com/624cc12cbb8535a77bafc47d/628fb0f77f6279a920577119_Token_Logo2_Solid.png" width="50" height="50"><br>Token API | The Token API provides endpoints for retrieving any token, token balance, transfer, and symbol in existence, including full support for native token transfers and balances (fully supports both ERC-20 and ERC-777 tokens). | [Token API Docs](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/token.md) |
12-
| <img src="https://assets.website-files.com/624c8536aa7f872fe6829dbd/628feeeb8eb1204a1c701cd1_CDN_Logo_Red-p-500.png" width="50" height="50"><br>CDN | The Transpose CDN provides supplementary data for endpoints across the Transpose API suite, including raw block data, NFT images, media, and metadata, collection images, and token symbols. | [CDN Docs](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/cdn.md) |
12+
| <img src="https://assets.website-files.com/624c8536aa7f872fe6829dbd/628feeeb8eb1204a1c701cd1_CDN_Logo_Red-p-500.png" width="50" height="50"><br>CDN | The Transpose CDN provides supplementary data for endpoints across the Transpose API suite, including raw block data, NFT images, media, and metadata, collection images, and token symbols. | [CDN Docs](https://github.com/TransposeData/transpose-python-sdk/blob/main/docs/cdn.md) |
1313

1414
## SDK Documentation
1515
You can learn more about the Transpose SDK and how it works below.
@@ -18,7 +18,10 @@ You can learn more about the Transpose SDK and how it works below.
1818
The Transpose SDK uses custom classes to represent API responses:
1919

2020
#### Error Classes
21+
<details>
22+
<summary>SDK Error Class Specifications</summary>
2123
The SDK uses the following error classes to represent API errors:
24+
2225
- ``TransposeBadRequest``
2326
- Represents a 400 Bad Request error from the Transpose API.
2427
- ``TransposeRateLimit``
@@ -31,8 +34,12 @@ The SDK uses the following error classes to represent API errors:
3134
- Represents a 404 Not Found error from the Transpose API.
3235

3336
These errors will be raised when the SDK encounters an error from the Transpose API.
37+
</details>
3438

3539
#### Response Classes
40+
<details>
41+
<summary>Response Class Specifications</summary>
42+
3643
The SDK will always return a list of response objects from the Transpose API. For example, calling the ``ens.records_by_date`` endpoint will return a list of ``ENSRecord`` objects.
3744

3845
These response objects can be accessed in the following ways:
@@ -42,12 +49,13 @@ These response objects can be accessed in the following ways:
4249
All response objects can also be accessed as a dictionary by calling ``.to_dict()`` on them:
4350
- ``ENSRecord[0].to_dict()`` will return the first record as a dictionary.
4451
- ``ENSRecord[i].to_dict()`` retrieves the i-th record as a dictionary.
52+
</details>
4553

4654
### Pagination
55+
<details>
56+
<summary>Pagination with the Transpose SDK.</summary>
4757

48-
Pagination on the Transpose API is straightforward.
49-
50-
Transpose API endpoints will return a maximum of 500 results in a single query. To return the next page, simply call ``api.next()``. If ``api.next()`` returns ``None``, then there are no more pages.
58+
Transpose endpoints will return a maximum of 500 results in a single query. To return the next page, simply call ``api.next()``. If ``api.next()`` returns ``None``, then there are no more pages.
5159

5260
Here is a standard pagination implementation:
5361

@@ -64,9 +72,13 @@ while True:
6472
# otherwise, print length of data
6573
else: print(len(data))
6674
```
75+
</details>
76+
6777

6878
### Bulk Requests
79+
<details>
6980

81+
<summary>Bulk requesting data with the Transpose SDK</summary>
7082
Alongside pagination, we also offer a convenience method for iterating over all pages. This method will handle pagination for you, and will return a list of all results.
7183

7284
#### Usage:
@@ -97,6 +109,7 @@ print(len(all_blocks_by_miner))
97109

98110
>>> 53046
99111
```
112+
</details>
100113

101114
---
102115

@@ -109,6 +122,9 @@ from transpose.extras import <MODULE>
109122
```
110123

111124
### Plotting
125+
<details>
126+
<summary>Transpose Plotting Specifications</summary>
127+
112128
The SDK natively includes a plotting library which implements [plotly](https://plot.ly/python/). Using it, you can quickly create plots of data obtained through the Transpose API.
113129

114130
For a plotting example, check out the [demo](https://github.com/TransposeData/transpose-python-sdk/blob/main/demo/plotting.py) file, which will graph the past hour's gas prices in a bar chart.
@@ -153,4 +169,5 @@ This will return an object on which you can call the following methods:
153169
- ``shape`` -> OPTIONAL: The shape of the line. Can be either ``linear``, ``spline``, ``vh``, ``hv``, ``vhv``, or ``hvh``.
154170
- ``smoothing`` -> OPTIONAL: The number of points to smooth the data with.
155171
- For ``line``, this will calculate a moving average of the data with a period of ``smoothing``.
156-
- For ``bar``, this will group and average the data over ``smoothing`` points.
172+
- For ``bar``, this will group and average the data over ``smoothing`` points.
173+
</details>

0 commit comments

Comments
 (0)