Skip to content

Commit b25b4d1

Browse files
author
clickingbuttons
committed
add sphinx docs (#126)
* add sphinx docs * cleanup * fix some reference pydoc * fix code formatting * typos * fix lint
1 parent 9fe351a commit b25b4d1

File tree

15 files changed

+810
-17
lines changed

15 files changed

+810
-17
lines changed

‎.gitignore

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ venv/
5555
*.log
5656

5757
# Sphinx documentation
58-
docs/_build/
58+
docs/build/
5959

6060
# PyBuilder
6161
target/

‎docs/Makefile

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
POLYGON_API_KEY="POLYGON_API_KEY" $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/source/Getting-Started.rst

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
Getting Started
2+
===============
3+
4+
Requirements:
5+
- `Polygon.io API key <https://polygon.io/dashboard/api-keys>`_
6+
- `Python >= 3.7 <https://www.python.org/downloads/>`_
7+
- `This package <https://pypi.org/project/polygon-api-client/>`_
8+
9+
.. code-block:: shell
10+
11+
pip install polygon-api-client
12+
13+
HTTP client usage
14+
-----------------
15+
16+
.. automethod:: polygon.RESTClient.__init__
17+
18+
You can pass your API key via the environment variable :code:`POLYGON_API_KEY` or as the first parameter to the :code:`RESTClient` constructor:
19+
20+
.. code-block:: python
21+
22+
from polygon import RESTClient
23+
24+
client = RESTClient() # POLYGON_API_KEY is used
25+
client = RESTClient("api_key") # api_key is used
26+
27+
For non-paginated endpoints call :code:`get_*`:
28+
29+
.. code-block:: python
30+
31+
aggs = client.get_aggs("AAPL", 1, "day", "2022-04-01", "2022-04-04")
32+
print(aggs)
33+
34+
For paginated endpoints call :code:`list_*` and use the provided iterator:
35+
36+
.. code-block:: python
37+
38+
trades = []
39+
for t in client.list_trades("AAA", timestamp="2022-04-20", limit=5, sort=Sort.ASC)
40+
trades.append(t)
41+
print(trades)
42+
43+
For endpoints that have a set of parameters you can use the provided enums:
44+
45+
.. code-block:: python
46+
47+
from polygon.rest.models import Sort
48+
49+
client.list_trades(..., sort=Sort.ASC)
50+
51+
To handle the raw `urllib3 response <https://urllib3.readthedocs.io/en/stable/reference/urllib3.response.html?highlight=response#response) yourself, pass `raw=True>`_ yourself pass :code:`raw=True`:
52+
53+
.. code-block:: python
54+
55+
aggs = client.get_aggs("AAPL", 1, "day", "2022-04-01", "2022-04-04", raw=True)
56+
print(aggs.geturl())
57+
# https://api.polygon.io/v2/aggs/ticker/AAPL/range/1/day/2022-04-01/2022-04-04
58+
print(aggs.status)
59+
# 200
60+
print(aggs.data)
61+
# b'{
62+
# "ticker": "AAPL",
63+
# "queryCount": 2,
64+
# "resultsCount": 2,
65+
# "adjusted": true,
66+
# "results": [
67+
# {
68+
# "v": 78251328,
69+
# "vw": 173.4143,
70+
# "o": 174.03,
71+
# "c": 174.31,
72+
# "h": 174.88,
73+
# "l": 171.94,
74+
# "t": 1648785600000,
75+
# "n": 661160
76+
# },
77+
# {
78+
# "v": 76545983,
79+
# "vw": 177.4855,
80+
# "o": 174.57,
81+
# "c": 178.44,
82+
# "h": 178.49,
83+
# "l": 174.44,
84+
# "t": 1649044800000,
85+
# "n": 630374
86+
# }
87+
# ],
88+
# "status": "OK",
89+
# "request_id": "d8882a9d5194978819777f49c44b09c6",
90+
# "count": 2
91+
# }'
92+
93+
If it is a paginated :code:`list_*` response it's up to you to handle the "next_url" iteration:
94+
95+
.. code-block:: python
96+
97+
trades = client.list_trades("AAA", timestamp="2022-04-20", limit=5)
98+
print(aggs.data)
99+
# b'{
100+
# "results": [
101+
# {
102+
# "conditions": [
103+
# 15
104+
# ],
105+
# "exchange": 11,
106+
# "id": "52983575627601",
107+
# "participant_timestamp": 1650499200029279200,
108+
# "price": 24.875,
109+
# "sequence_number": 1591291,
110+
# "sip_timestamp": 1650499200029316600,
111+
# "size": 100,
112+
# "tape": 1
113+
# },
114+
# {
115+
# "conditions": [
116+
# 38,
117+
# 41
118+
# ],
119+
# "exchange": 11,
120+
# "id": "52983575627600",
121+
# "participant_timestamp": 1650499200029279200,
122+
# "price": 24.875,
123+
# "sequence_number": 1591290,
124+
# "sip_timestamp": 1650499200029316600,
125+
# "tape": 1
126+
# },
127+
# {
128+
# "conditions": [
129+
# 15
130+
# ],
131+
# "exchange": 11,
132+
# "id": "52983575622470",
133+
# "participant_timestamp": 1650493800003024000,
134+
# "price": 24.875,
135+
# "sequence_number": 1571279,
136+
# "sip_timestamp": 1650493800003645400,
137+
# "size": 100,
138+
# "tape": 1
139+
# },
140+
# {
141+
# "conditions": [
142+
# 38,
143+
# 41
144+
# ],
145+
# "exchange": 11,
146+
# "id": "52983575622469",
147+
# "participant_timestamp": 1650493800003024000,
148+
# "price": 24.875,
149+
# "sequence_number": 1571276,
150+
# "sip_timestamp": 1650493800003635500,
151+
# "tape": 1
152+
# },
153+
# {
154+
# "conditions": [
155+
# 15
156+
# ],
157+
# "exchange": 11,
158+
# "id": "52983575556178",
159+
# "participant_timestamp": 1650485400002987800,
160+
# "price": 24.875,
161+
# "sequence_number": 1536223,
162+
# "sip_timestamp": 1650485400003870000,
163+
# "size": 100,
164+
# "tape": 1
165+
# }
166+
# ],
167+
# "status": "OK",
168+
# "request_id": "618bb99e7a632ed9f55454a541404b44",
169+
# "next_url": "https://api.polygon.io/v3/trades/AAA?cursor=YXA9NSZhcz0mbGltaXQ9NSZvcmRlcj1kZXNjJnNvcnQ9dGltZXN0YW1wJnRpbWVzdGFtcC5ndGU9MjAyMi0wNC0yMFQwNCUzQTAwJTNBMDBaJnRpbWVzdGFtcC5sdGU9MjAyMi0wNC0yMFQyMCUzQTEwJTNBMDAuMDAzODY5OTUyWg"
170+
# }'
171+
172+
173+
Websocket client usage
174+
----------------------
175+
176+
Coming soon.

‎docs/source/Quotes.rst

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
.. _quotes_header:
2+
3+
Quotes
4+
==========
5+
6+
===========
7+
List quotes
8+
===========
9+
10+
.. automethod:: polygon.RESTClient.list_quotes
11+
12+
==============
13+
Get last quote
14+
==============
15+
.. automethod:: polygon.RESTClient.get_last_quote

‎docs/source/Reference.rst

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
.. _reference_header:
2+
3+
Reference
4+
===============
5+
6+
====================
7+
List market holidays
8+
====================
9+
.. automethod:: polygon.RESTClient.list_market_holidays
10+
11+
====================
12+
List tickers
13+
====================
14+
.. automethod:: polygon.RESTClient.list_tickers
15+
16+
====================
17+
List ticker details
18+
====================
19+
.. automethod:: polygon.RESTClient.get_ticker_details
20+
21+
====================
22+
Get ticker news
23+
====================
24+
.. automethod:: polygon.RESTClient.get_ticker_news
25+
26+
====================
27+
Get ticker types
28+
====================
29+
.. automethod:: polygon.RESTClient.get_ticker_types
30+
31+
====================
32+
List splits
33+
====================
34+
.. automethod:: polygon.RESTClient.list_splits
35+
36+
====================
37+
List dividends
38+
====================
39+
.. automethod:: polygon.RESTClient.list_dividends
40+

‎docs/source/Trades.rst

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
.. _trades_header:
2+
3+
Trades
4+
=============
5+
6+
===========
7+
List trades
8+
===========
9+
.. automethod:: polygon.RESTClient.list_trades

‎docs/source/conf.py

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Configuration file for the Sphinx documentation builder.
2+
#
3+
# This file only contains a selection of the most common options. For a full
4+
# list see the documentation:
5+
# https://www.sphinx-doc.org/en/master/usage/configuration.html
6+
7+
# -- Path setup --------------------------------------------------------------
8+
9+
# If extensions (or modules to document with autodoc) are in another directory,
10+
# add these directories to sys.path here. If the directory is relative to the
11+
# documentation root, use os.path.abspath to make it absolute, like shown here.
12+
#
13+
import os
14+
import sys
15+
sys.path.insert(0, os.path.abspath('../..'))
16+
print('docs path', sys.path[0])
17+
18+
19+
# -- Project information -----------------------------------------------------
20+
21+
project = 'polygon-api-client'
22+
copyright = '2022, Polygon.io'
23+
author = 'Polygon.io'
24+
25+
# The full version, including alpha/beta/rc tags
26+
release = '0.3.0'
27+
28+
29+
# -- General configuration ---------------------------------------------------
30+
31+
# Add any Sphinx extension module names here, as strings. They can be
32+
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
33+
# ones.
34+
extensions = [
35+
'sphinx.ext.autodoc',
36+
'sphinx_autodoc_typehints',
37+
'sphinx_rtd_theme',
38+
]
39+
40+
# Add any paths that contain templates here, relative to this directory.
41+
templates_path = ['_templates']
42+
43+
# List of patterns, relative to source directory, that match files and
44+
# directories to ignore when looking for source files.
45+
# This pattern also affects html_static_path and html_extra_path.
46+
exclude_patterns = []
47+
48+
49+
# -- Options for HTML output -------------------------------------------------
50+
51+
# The theme to use for HTML and HTML Help pages. See the documentation for
52+
# a list of builtin themes.
53+
#
54+
html_theme = 'sphinx_rtd_theme'
55+
56+
# Add any paths that contain custom static files (such as style sheets) here,
57+
# relative to this directory. They are copied after the builtin static files,
58+
# so a file named "default.css" will overwrite the builtin "default.css".
59+
html_static_path = ['_static']

‎docs/source/index.rst

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
Welcome to polygon-api-client's documentation!
2+
==============================================
3+
4+
This documentation is for the Python client only. For details about the responses see `the official docs <https://polygon.io/docs>`_.
5+
6+
.. toctree::
7+
:maxdepth: 1
8+
:caption: Contents:
9+
10+
Getting-Started
11+
Quotes
12+
Reference
13+
Trades
14+
15+
16+
Indices and tables
17+
==================
18+
19+
* :ref:`genindex`
20+
* :ref:`modindex`
21+
* :ref:`search`

0 commit comments

Comments
 (0)