Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 4284be1

Browse filesBrowse files
areed1192areed1192
committed
Add filings Service
1 parent c07a750 commit 4284be1
Copy full SHA for 4284be1

5 files changed

+396-18Lines changed: 396 additions & 18 deletions

File tree

Expand file treeCollapse file tree
Open diff view settings
Filter options
Expand file treeCollapse file tree
Open diff view settings
Collapse file

‎edgar/client.py‎

Copy file name to clipboardExpand all lines: edgar/client.py
+11-11Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@
55
from edgar.mutual_funds import MutualFunds
66
from edgar.variable_insurance_products import VariableInsuranceProducts
77
from edgar.datasets import Datasets
8+
from edgar.filings import Filings
89
from edgar.current_events import CurrentEvents
910

1011

@@ -112,20 +113,19 @@ def datasets(self) -> Datasets:
112113

113114
return object
114115

115-
# def company_filings(self, cik: str = None, filing_type: str = None, sic_code: str = None, filing_number: str = None, company_name: str = None,
116-
# state: str = None, country: str = None, return_count: int = 100, start: int = 0, before: Union[str, date] = None,
117-
# after: Union[str, date] = None) -> List[dict]:
118-
# """Returns all the filings of certain type for a particular company.
116+
def filings(self) -> Filings:
117+
"""Used to access the `Filings` services.
119118
120-
# Arguments:
121-
# ----
122-
# cik {str} -- The company CIK Number.
119+
### Returns
120+
---
121+
Users:
122+
The `Filings` services Object.
123+
"""
123124

124-
# filing_type {str} -- The filing type ID.
125+
# Grab the `Filings` object.
126+
object = Filings(session=self.edgar_session)
125127

126-
# Returns:
127-
# ----
128-
# dict -- A Dictionary containing the filing items.
128+
return object
129129

130130
def current_events(self) -> CurrentEvents:
131131
"""Used to access the `CurrentEvents` services.
Collapse file

‎edgar/filings.py‎

Copy file name to clipboard
+327Lines changed: 327 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,327 @@
1+
from typing import Dict
2+
from typing import List
3+
from typing import Union
4+
from enum import Enum
5+
from datetime import datetime
6+
from datetime import date
7+
from edgar.session import EdgarSession
8+
from edgar.utilis import EdgarUtilities
9+
from edgar.parser import EdgarParser
10+
11+
12+
class Filings():
13+
14+
"""
15+
## Overview:
16+
----
17+
Public companies submit multiple types of filing
18+
through out the year. The `Filings` client helps
19+
easily query these filings and allows you to build
20+
custom queries.
21+
"""
22+
23+
def __init__(self, session: EdgarSession) -> None:
24+
"""Initializes the `Filings` object.
25+
26+
### Parameters
27+
----
28+
session : `EdgarSession`
29+
An initialized session of the `EdgarSession`.
30+
31+
### Usage
32+
----
33+
>>> edgar_client = EdgarClient()
34+
>>> filings_services = edgar_client.Filings()
35+
"""
36+
37+
# Set the session.
38+
self.edgar_session: EdgarSession = session
39+
self.edgar_utilities: EdgarUtilities = EdgarUtilities()
40+
self.edgar_parser: EdgarParser = EdgarParser()
41+
42+
# Set the endpoint.
43+
self.filings_endpoint = '/cgi-bin/filings'
44+
self.browse_endpoint = '/cgi-bin/browse-edgar'
45+
46+
self.params = {
47+
'action': 'getcompany',
48+
'output': 'atom',
49+
'CIK': '',
50+
'start': '0',
51+
'count': '100'
52+
}
53+
54+
def __repr__(self) -> str:
55+
"""String representation of the `EdgarClient.Filings` object."""
56+
57+
# define the string representation
58+
str_representation = '<EdgarClient.Filings (active=True, connected=True)>'
59+
60+
return str_representation
61+
62+
def get_filings_by_cik(self, cik: str, start: int = 0, number_of_filings: int = 100) -> Dict:
63+
"""Returns a list of filings that fall under a specific CIK number.
64+
65+
### Arguments:
66+
----
67+
cik : str
68+
The company CIK number, defined by the SEC.
69+
70+
number_of_filings : int (optional, Default=1000)
71+
Specifices the number of filings to return. If you want all filings
72+
then set to `None`. Be cautious though becuase you may be requesting
73+
100s of URLs.
74+
75+
start: int (optional, Default=None)
76+
If you want to pick up where you left off from a previous parse, then
77+
set the `start` argument. This will start parsing the filings that come
78+
after this and up until the `number_of_filings`.
79+
80+
### Returns:
81+
----
82+
dict :
83+
A collection of `Filings` resources.
84+
85+
### Usage:
86+
----
87+
>>> edgar_client = EdgarClient()
88+
>>> filings_services = edgar_client.filings()
89+
>>> filings_services.get_filings_by_cik(cik='814679')
90+
"""
91+
92+
self.params['CIK'] = cik
93+
self.params['start'] = start
94+
95+
# Grab the Data.
96+
response = self.edgar_session.make_request(
97+
method='get',
98+
endpoint=self.browse_endpoint,
99+
params=self.params
100+
)
101+
102+
# Parse it.
103+
response = self.edgar_parser.parse_entries(
104+
response_text=response,
105+
start=start,
106+
num_of_items=number_of_filings
107+
)
108+
109+
self.params['CIK'] = ''
110+
111+
return response
112+
113+
def get_filings_by_type(self, cik: str, filing_type: Union[str, Enum], start: int = 0, number_of_filings: int = 100) -> Dict:
114+
"""Returns a list of filings that fall under a specific CIK number.
115+
116+
### Arguments:
117+
----
118+
cik : str
119+
The company CIK number, defined by the SEC.
120+
121+
filing_type : Union[str, Enum] (optional, Default=None)
122+
The type of filing you want to query. The type is
123+
defined by the Filing code you pass through. For example,
124+
`10-k` represents annual filings.
125+
126+
number_of_filings : int (optional, Default=1000)
127+
Specifices the number of filings to return. If you want all filings
128+
then set to `None`. Be cautious though becuase you may be requesting
129+
100s of URLs.
130+
131+
start: int (optional, Default=None)
132+
If you want to pick up where you left off from a previous parse, then
133+
set the `start` argument. This will start parsing the filings that come
134+
after this and up until the `number_of_filings`.
135+
136+
### Returns:
137+
----
138+
dict :
139+
A collection of `Filings` resources.
140+
141+
### Usage:
142+
----
143+
>>> edgar_client = EdgarClient()
144+
>>> filings_services = edgar_client.filings()
145+
>>> filings_services.get_filings_by_type(
146+
cik='814679',
147+
filing_type='10-k'
148+
)
149+
"""
150+
151+
if isinstance(filing_type, Enum):
152+
filing_type = filing_type.value
153+
154+
self.params['CIK'] = cik
155+
self.params['type'] = filing_type
156+
self.params['start'] = start
157+
158+
# Grab the Data.
159+
response = self.edgar_session.make_request(
160+
method='get',
161+
endpoint=self.browse_endpoint,
162+
params=self.params
163+
)
164+
165+
# Parse it.
166+
response = self.edgar_parser.parse_entries(
167+
response_text=response,
168+
start=start,
169+
num_of_items=number_of_filings
170+
)
171+
172+
self.params['CIK'] = ''
173+
self.params['type'] = ''
174+
175+
return response
176+
177+
def query(
178+
self,
179+
cik: str = None,
180+
sic: str = None,
181+
filing_type: Union[str, Enum] = None,
182+
company_name: str = None,
183+
start: int = 0,
184+
number_of_filings: int = 100,
185+
after_date: Union[str, datetime, date] = None,
186+
before_date: Union[str, datetime, date] = None
187+
) -> List[dict]:
188+
"""Allows for complex queries by giving access to all query parameters.
189+
190+
### Parameters
191+
----
192+
cik : str (optional, Default=None)
193+
The CIK ID that you want to query.
194+
195+
filing_type : Union[str, Enum] (optional, Default=None)
196+
The type of filing you want to query. The type is
197+
defined by the Filing code you pass through. For example,
198+
`10-k` represents annual filings.
199+
200+
company_name : str (optional, Default=None)
201+
The company name you want to use as the basis of your search.
202+
203+
number_of_filings : int (optional, Default=1000)
204+
Specifices the number of filings to return. If you want all filings
205+
then set to `None`. Be cautious though becuase you may be requesting
206+
100s of URLs.
207+
208+
start: int (optional, Default=None)
209+
If you want to pick up where you left off from a previous parse, then
210+
set the `start` argument. This will start parsing the filings that come
211+
after this and up until the `number_of_filings`.
212+
213+
before_date: Union[str, datetime, date] (optional, Default=None)
214+
Represents filings that you want before a certain date. For example,
215+
`2019-12-01` means return all the filings `BEFORE` Decemeber 1, 2019.
216+
217+
after_date : Union[str, datetime, date] (optional, Default=None)
218+
Represents filings that you want after a certain date. For example,
219+
`2019-12-01` means return all the filings `AFTER` Decemeber 1, 2019.
220+
221+
### Returns:
222+
----
223+
List[dict]:
224+
A collection of `Filing` resources.
225+
226+
### Usage
227+
----
228+
>>> edgar_client = EdgarClient()
229+
>>> filings_services = edgar_client.filings()
230+
>>> filings_services.query(
231+
cik='C000005193'
232+
filing_type='10-k'
233+
)
234+
"""
235+
236+
if isinstance(filing_type, Enum):
237+
filing_type = filing_type.value
238+
239+
if before_date:
240+
before_date = self.edgar_utilities.parse_dates(
241+
date_or_datetime=before_date
242+
)
243+
244+
if after_date:
245+
after_date = self.edgar_utilities.parse_dates(
246+
date_or_datetime=after_date
247+
)
248+
249+
self.params['start'] = start
250+
self.params['CIK'] = cik
251+
self.params['SIC'] = sic
252+
self.params['type'] = filing_type
253+
self.params['company'] = company_name
254+
self.params['datea'] = after_date
255+
self.params['dateb'] = before_date
256+
257+
# Grab the Data.
258+
response = self.edgar_session.make_request(
259+
method='get',
260+
endpoint=self.browse_endpoint,
261+
params=self.params
262+
)
263+
264+
# Parse the entries.
265+
entries = self.edgar_parser.parse_entries(
266+
response_text=response,
267+
num_of_items=number_of_filings,
268+
start=start
269+
)
270+
271+
self.params['start'] = start
272+
self.params['CIK'] = cik
273+
self.params['SIC'] = sic
274+
self.params['type'] = filing_type
275+
self.params['company'] = company_name
276+
self.params['datea'] = after_date
277+
self.params['dateb'] = before_date
278+
279+
return entries
280+
281+
def get_filings_by_company_name(
282+
self,
283+
company_name: str,
284+
number_of_filings : int = 100,
285+
start : int = 0
286+
) -> List[dict]:
287+
"""Returns all the filings (ownership and non-ownership).
288+
289+
### Parameters
290+
----
291+
company_name : str (optional, Default=None)
292+
The company name you want to use as the basis of your search.
293+
294+
number_of_filings : int (optional, Default=1000)
295+
Specifices the number of filings to return. If you want all filings
296+
then set to `None`. Be cautious though becuase you may be requesting
297+
100s of URLs.
298+
299+
start: int (optional, Default=None)
300+
If you want to pick up where you left off from a previous parse, then
301+
set the `start` argument. This will start parsing the filings that come
302+
after this and up until the `number_of_filings`.
303+
304+
Returns:
305+
----
306+
List[dict] -- A list of ownership filings.
307+
"""
308+
309+
self.params['company'] = company_name
310+
311+
# Grab the Data.
312+
response = self.edgar_session.make_request(
313+
method='get',
314+
endpoint=self.browse_endpoint,
315+
params=self.params
316+
)
317+
318+
# Parse the entries.
319+
entries = self.edgar_parser.parse_entries(
320+
response_text=response,
321+
num_of_items=number_of_filings,
322+
start=start
323+
)
324+
325+
self.params['company'] = ''
326+
327+
return entries
Collapse file

‎samples/use_filings_service.py‎

Copy file name to clipboard
+30Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
from pprint import pprint
2+
from edgar.client import EdgarClient
3+
from edgar.enums import FilingTypeCodes
4+
5+
# Initialize the Edgar Client
6+
edgar_client = EdgarClient()
7+
8+
# Initialize the `Filings` Services.
9+
filings_service = edgar_client.filings()
10+
11+
# Grab some filings for Facebook.
12+
pprint(
13+
filings_service.get_filings_by_cik(cik='1326801')
14+
)
15+
16+
# Grab the 10-Ks for Facebook,
17+
pprint(
18+
filings_service.get_filings_by_type(
19+
cik='1326801',
20+
filing_type=FilingTypeCodes.FILING_10K
21+
)
22+
)
23+
24+
# Grab some filings for Facebook using the advance query.
25+
pprint(
26+
filings_service.query(
27+
cik='1326801',
28+
filing_type='10-k'
29+
)
30+
)

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.