Skip to content

Commit 1c66ed9

Browse files
andrewkittredgeandrewkittredge
committed
improving face-statement documentation
1 parent f3349c3 commit 1c66ed9

17 files changed

+445
-53
lines changed

‎calcbench/__init__.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@
3838
DocumentSearchResults,
3939
raw_data,
4040
raw_data_raw,
41+
face_statement,
4142
)
4243

4344
from .listener import handle_filings

‎calcbench/api_client.py‎

Lines changed: 54 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,7 @@ def _rig_for_testing(domain="localhost:444", suppress_http_warnings=True):
8686
_SESSION_STUFF["session"] = None
8787
if suppress_http_warnings:
8888
from requests.packages.urllib3.exceptions import InsecureRequestWarning
89+
8990
requests.packages.urllib3.disable_warnings(InsecureRequestWarning)
9091

9192

@@ -657,56 +658,62 @@ def mapped_raw(
657658
return _json_POST("mappedData", payload)
658659

659660

660-
def as_reported_raw(
661+
662+
663+
def face_statement(
661664
company_identifier,
662665
statement_type,
663666
period_type="annual",
664667
all_periods=False,
665668
descending_dates=False,
666669
):
667-
"""
668-
As-Reported Data.
670+
"""Face Statements.
669671
670-
Get statements as reported by the filing company
672+
face statements as reported by the filing company
671673
672-
Args:
673-
company_identifier: a ticker or a CIK code, eg 'msft'
674-
statement_type: one of ('income', 'balance', 'cash', 'change-in-equity', 'comprehensive-income')
675-
period_type: either 'annual' or 'quarterly'
676-
all_periods: get all history or only the last four, True or False.
677-
descending_dates: return columns in oldest -> newest order.
674+
675+
:param string company_identifier: a ticker or a CIK code, eg 'msft'
676+
:param string statement_type: one of ('income', 'balance', 'cash', 'change-in-equity', 'comprehensive-income')
677+
:param string period_type: 'annual' or 'quarterly'
678+
:param string all_periods: get all history or only the last four, True or False.
679+
:param bool descending_dates: return columns in oldest -> newest order.
678680
681+
:rtype: object
682+
679683
Returns:
680-
An object with columns and line items lists. The columns have fiscal_period, period_start, period_end and instant values.
681-
The line items have label, local_name (the XBRL tag name), tree_depth (the indent amount), is_subtotal (whether or not the line item is computed from above metrics) and facts.
682-
The facts are in the same order as the columns and have fact_ids (an internal Calcbench ID), unit_of_measure (USD etc), effective_value (the reported value), and format_type.
683-
684-
Example:
685-
{
686-
"entity_name": "Microsoft Corp",
687-
"name": "INCOME STATEMENTS",
688-
"period_type": 2,
689-
"columns": [
690-
{"fiscal_period": "Y 2008",
691-
"period_start": "2007-07-01",
692-
"period_end": "2008-06-30",
693-
"instant": false
694-
},...],
695-
"line_items" : [
696-
{"label": "Revenue",
697-
"local_name": "SalesRevenueNet",
698-
"tree_depth": 3,
699-
"is_subtotal": false,
700-
"facts": [
701-
{
702-
"fact_id": 5849672,
703-
"unit_of_measure": "USD",
704-
"effective_value": 60420000000,
705-
"format_type": "currency",
706-
"text_fact_id": 5849351
707-
},...]}
708-
...]
709-
}
684+
An object with columns and line items lists. The columns have fiscal_period, period_start, period_end and instant values.
685+
The line items have label, local_name (the XBRL tag name), tree_depth (the indent amount), is_subtotal (whether or not the line item is computed from above metrics) and facts.
686+
The facts are in the same order as the columns and have fact_ids (an internal Calcbench ID), unit_of_measure (USD etc), effective_value (the reported value), and format_type.
687+
688+
Example:
689+
{
690+
"entity_name": "Microsoft Corp",
691+
"name": "INCOME STATEMENTS",
692+
"period_type": 2,
693+
"columns": [
694+
{"fiscal_period": "Y 2008",
695+
"period_start": "2007-07-01",
696+
"period_end": "2008-06-30",
697+
"instant": false
698+
},...],
699+
"line_items" : [
700+
{"label": "Revenue",
701+
"local_name": "SalesRevenueNet",
702+
"tree_depth": 3,
703+
"is_subtotal": false,
704+
"facts": [
705+
{
706+
"fact_id": 5849672,
707+
"unit_of_measure": "USD",
708+
"effective_value": 60420000000,
709+
"format_type": "currency",
710+
"text_fact_id": 5849351
711+
},...]}
712+
...]
713+
}
714+
Usage::
715+
>>> calcbench.face_statement('msft', 'income')
716+
710717
"""
711718
url = _SESSION_STUFF["api_url_base"].format("asReported")
712719
payload = {
@@ -726,6 +733,7 @@ def as_reported_raw(
726733
data = response.json()
727734
return data
728735

736+
as_reported_raw = face_statement
729737

730738
def dimensional_raw(
731739
company_identifiers=None,
@@ -1039,7 +1047,11 @@ def tickers(
10391047
10401048
"""
10411049
companies = _companies(
1042-
SIC_codes, index, company_identifiers, entire_universe, NAICS_codes=NAICS_codes
1050+
SIC_codes,
1051+
index,
1052+
list(company_identifiers),
1053+
entire_universe,
1054+
NAICS_codes=NAICS_codes,
10431055
)
10441056
tickers = [co["ticker"] for co in companies]
10451057
return tickers
@@ -1065,7 +1077,7 @@ def companies(
10651077
companies = _companies(
10661078
SIC_codes,
10671079
index,
1068-
company_identifiers,
1080+
list(company_identifiers),
10691081
entire_universe,
10701082
include_most_recent_filing_dates,
10711083
NAICS_codes=NAICS_codes,

‎docs/html/companies.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -143,7 +143,7 @@ <h3 id="searchlabel">Quick search</h3>
143143
<div class="clearer"></div>
144144
</div>
145145
<div class="footer">
146-
&copy;2019, Andrew Kittredge.
146+
&copy;2020, Andrew Kittredge.
147147

148148
|
149149
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>

‎docs/html/disclosures.html‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ <h3 id="searchlabel">Quick search</h3>
170170
<div class="clearer"></div>
171171
</div>
172172
<div class="footer">
173-
&copy;2019, Andrew Kittredge.
173+
&copy;2020, Andrew Kittredge.
174174

175175
|
176176
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>

‎docs/html/face-statements.html‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
2+
<!DOCTYPE html>
3+
4+
<html xmlns="http://www.w3.org/1999/xhtml">
5+
<head>
6+
<meta charset="utf-8" />
7+
<title>Face Statements &#8212; Calcbench API Client documentation</title>
8+
<link rel="stylesheet" href="_static/alabaster.css" type="text/css" />
9+
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
10+
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
11+
<script src="_static/jquery.js"></script>
12+
<script src="_static/underscore.js"></script>
13+
<script src="_static/doctools.js"></script>
14+
<script src="_static/language_data.js"></script>
15+
<link rel="index" title="Index" href="genindex.html" />
16+
<link rel="search" title="Search" href="search.html" />
17+
<link rel="prev" title="Low-latency New Data Notification" href="push-notification.html" />
18+
19+
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
20+
21+
22+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
23+
24+
</head><body>
25+
26+
27+
<div class="document">
28+
<div class="documentwrapper">
29+
<div class="bodywrapper">
30+
31+
32+
<div class="body" role="main">
33+
34+
<div class="section" id="face-statements">
35+
<h1>Face Statements<a class="headerlink" href="#face-statements" title="Permalink to this headline"></a></h1>
36+
<dl class="function">
37+
<dt id="calcbench.face_statement">
38+
<code class="sig-prename descclassname">calcbench.</code><code class="sig-name descname">face_statement</code><span class="sig-paren">(</span><em class="sig-param">company_identifier</em>, <em class="sig-param">statement_type</em>, <em class="sig-param">period_type='annual'</em>, <em class="sig-param">all_periods=False</em>, <em class="sig-param">descending_dates=False</em><span class="sig-paren">)</span><a class="headerlink" href="#calcbench.face_statement" title="Permalink to this definition"></a></dt>
39+
<dd><p>Face Statements.</p>
40+
<p>face statements as reported by the filing company</p>
41+
<dl class="field-list simple">
42+
<dt class="field-odd">Parameters</dt>
43+
<dd class="field-odd"><ul class="simple">
44+
<li><p><strong>company_identifier</strong> (<em>string</em>) – a ticker or a CIK code, eg ‘msft’</p></li>
45+
<li><p><strong>statement_type</strong> (<em>string</em>) – one of (‘income’, ‘balance’, ‘cash’, ‘change-in-equity’, ‘comprehensive-income’)</p></li>
46+
<li><p><strong>period_type</strong> (<em>string</em>) – ‘annual’ or ‘quarterly’</p></li>
47+
<li><p><strong>all_periods</strong> (<em>string</em>) – get all history or only the last four, True or False.</p></li>
48+
<li><p><strong>descending_dates</strong> (<em>bool</em>) – return columns in oldest -&gt; newest order.</p></li>
49+
</ul>
50+
</dd>
51+
<dt class="field-even">Return type</dt>
52+
<dd class="field-even"><p>object</p>
53+
</dd>
54+
</dl>
55+
<p>Returns:
56+
An object with columns and line items lists. The columns have fiscal_period, period_start, period_end and instant values.
57+
The line items have label, local_name (the XBRL tag name), tree_depth (the indent amount), is_subtotal (whether or not the line item is computed from above metrics) and facts.
58+
The facts are in the same order as the columns and have fact_ids (an internal Calcbench ID), unit_of_measure (USD etc), effective_value (the reported value), and format_type.</p>
59+
<blockquote>
60+
<div><dl>
61+
<dt>Example:</dt><dd><p>{
62+
“entity_name”: “Microsoft Corp”,
63+
“name”: “INCOME STATEMENTS”,
64+
“period_type”: 2,
65+
“columns”: [</p>
66+
<blockquote>
67+
<div><blockquote>
68+
<div><p>{“fiscal_period”: “Y 2008”,
69+
“period_start”: “2007-07-01”,
70+
“period_end”: “2008-06-30”,
71+
“instant”: false</p>
72+
</div></blockquote>
73+
<p>},…],</p>
74+
</div></blockquote>
75+
<dl>
76+
<dt>“line_items”<span class="classifier">[</span></dt><dd><blockquote>
77+
<div><p>{“label”: “Revenue”,
78+
“local_name”: “SalesRevenueNet”,
79+
“tree_depth”: 3,
80+
“is_subtotal”: false,
81+
“facts”: [</p>
82+
<blockquote>
83+
<div><dl class="simple">
84+
<dt>{</dt><dd><p>“fact_id”: 5849672,
85+
“unit_of_measure”: “USD”,
86+
“effective_value”: 60420000000,
87+
“format_type”: “currency”,
88+
“text_fact_id”: 5849351</p>
89+
</dd>
90+
</dl>
91+
<p>},…]}</p>
92+
</div></blockquote>
93+
</div></blockquote>
94+
<p>…]</p>
95+
</dd>
96+
</dl>
97+
<p>}</p>
98+
</dd>
99+
</dl>
100+
</div></blockquote>
101+
<dl>
102+
<dt>Usage::</dt><dd><div class="doctest highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">calcbench</span><span class="o">.</span><span class="n">face_statement</span><span class="p">(</span><span class="s1">&#39;msft&#39;</span><span class="p">,</span> <span class="s1">&#39;income&#39;</span><span class="p">)</span>
103+
</pre></div>
104+
</div>
105+
</dd>
106+
</dl>
107+
</dd></dl>
108+
109+
</div>
110+
111+
112+
</div>
113+
114+
</div>
115+
</div>
116+
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
117+
<div class="sphinxsidebarwrapper">
118+
<h1 class="logo"><a href="index.html">Calcbench API Client</a></h1>
119+
120+
121+
122+
123+
124+
125+
126+
127+
<h3>Navigation</h3>
128+
<ul class="current">
129+
<li class="toctree-l1"><a class="reference internal" href="getting-started.html">Getting Started</a></li>
130+
<li class="toctree-l1"><a class="reference internal" href="numeric-data.html">Numeric Data</a></li>
131+
<li class="toctree-l1"><a class="reference internal" href="disclosures.html">Disclosures/Text</a></li>
132+
<li class="toctree-l1"><a class="reference internal" href="filings.html">Filings</a></li>
133+
<li class="toctree-l1"><a class="reference internal" href="companies.html">Companies</a></li>
134+
<li class="toctree-l1"><a class="reference internal" href="push-notification.html">Low-latency New Data Notification</a></li>
135+
<li class="toctree-l1 current"><a class="current reference internal" href="#">Face Statements</a></li>
136+
</ul>
137+
138+
<div class="relations">
139+
<h3>Related Topics</h3>
140+
<ul>
141+
<li><a href="index.html">Documentation overview</a><ul>
142+
<li>Previous: <a href="push-notification.html" title="previous chapter">Low-latency New Data Notification</a></li>
143+
</ul></li>
144+
</ul>
145+
</div>
146+
<div id="searchbox" style="display: none" role="search">
147+
<h3 id="searchlabel">Quick search</h3>
148+
<div class="searchformwrapper">
149+
<form class="search" action="search.html" method="get">
150+
<input type="text" name="q" aria-labelledby="searchlabel" />
151+
<input type="submit" value="Go" />
152+
</form>
153+
</div>
154+
</div>
155+
<script>$('#searchbox').show(0);</script>
156+
157+
158+
159+
160+
161+
162+
163+
164+
</div>
165+
</div>
166+
<div class="clearer"></div>
167+
</div>
168+
<div class="footer">
169+
&copy;2020, Andrew Kittredge.
170+
171+
|
172+
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.4.4</a>
173+
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
174+
175+
|
176+
<a href="_sources/face-statements.rst.txt"
177+
rel="nofollow">Page source</a>
178+
</div>
179+
180+
181+
182+
183+
</body>
184+
</html>

0 commit comments

Comments
 (0)