Add API Endpoints, clean up documentation.

Author: areed1192

edgar/client.py

@@ -9,6 +9,8 @@
 from edgar.current_events import CurrentEvents
 from edgar.issuers import Issuers
 from edgar.ownership_filings import OwnershipFilings
+from edgar.submissions import Submissions
+from edgar.xbrl import Xbrl
 
 
 class EdgarClient():
@@ -36,7 +38,7 @@ def archives(self) -> Archives:
 
         ### Returns
         ---
-        Users:
+        Archives:
             The `Archives` services Object.
         """
 
@@ -50,7 +52,7 @@ def companies(self) -> Companies:
 
         ### Returns
         ---
-        Users:
+        Companies:
             The `Companies` services Object.
         """
 
@@ -64,7 +66,7 @@ def series(self) -> Series:
 
         ### Returns
         ---
-        Users:
+        Series:
             The `Series` services Object.
         """
 
@@ -78,7 +80,7 @@ def mutual_funds(self) -> MutualFunds:
 
         ### Returns
         ---
-        Users:
+        MutualFunds:
             The `MutualFunds` services Object.
         """
 
@@ -92,7 +94,7 @@ def variable_insurance_products(self) -> VariableInsuranceProducts:
 
         ### Returns
         ---
-        Users:
+        VariableInsuranceProducts:
             The `VariableInsuranceProducts` services Object.
         """
 
@@ -106,7 +108,7 @@ def datasets(self) -> Datasets:
 
         ### Returns
         ---
-        Users:
+        Datasets:
             The `Datasets` services Object.
         """
 
@@ -120,7 +122,7 @@ def filings(self) -> Filings:
 
         ### Returns
         ---
-        Users:
+        Filings:
             The `Filings` services Object.
         """
 
@@ -134,7 +136,7 @@ def current_events(self) -> CurrentEvents:
 
         ### Returns
         ---
-        Users:
+        CurrentEvents:
             The `CurrentEvents` services Object.
         """
 
@@ -148,7 +150,7 @@ def issuers(self) -> Issuers:
 
         ### Returns
         ---
-        Users:
+        Issuers:
             The `Issuers` services Object.
         """
 
@@ -162,11 +164,39 @@ def ownership_filings(self) -> OwnershipFilings:
 
         ### Returns
         ---
-        Users:
+        OwnershipFilings:
             The `OwnershipFilings` services Object.
         """
 
         # Grab the `OwnershipFilings` object.
         object = OwnershipFilings(session=self.edgar_session)
 
         return object
+
+    def submissions(self) -> Submissions:
+        """Used to access the `Submissions` services.
+
+        ### Returns
+        ---
+        Submissions:
+            The `Submissions` services Object.
+        """
+
+        # Grab the `Submissions` object.
+        object = Submissions(session=self.edgar_session)
+
+        return object
+
+    def xbrl(self) -> Xbrl:
+        """Used to access the `Xbrl` services.
+
+        ### Returns
+        ---
+        Xbrl:
+            The `Xbrl` services Object.
+        """
+
+        # Grab the `Xbrl` object.
+        object = Xbrl(session=self.edgar_session)
+
+        return object

edgar/session.py

@@ -1,13 +1,10 @@
 import json
 import time
-from pprint import pprint
 import requests
 import logging
 import pathlib
 
 from typing import Dict
-from datetime import datetime
-from datetime import date
 
 
 class EdgarSession():
@@ -40,6 +37,8 @@ def __init__(self, client: object) -> None:
 
         self.client: EdgarClient = client
         self.resource = 'https://www.sec.gov'
+        self.api_resource = 'https://data.sec.gov'
+        self.total_requests = 0
 
         if not pathlib.Path('logs').exists():
             pathlib.Path('logs').mkdir()
@@ -60,21 +59,28 @@ def __repr__(self) -> str:
 
         return str_representation
 
-    def build_url(self, endpoint: str) -> str:
+    def build_url(self, endpoint: str, use_api: bool = False) -> str:
         """Builds the full url for the endpoint.
 
         ### Parameters
         ----
         endpoint : str
             The endpoint being requested.
 
+        use_api : bool (optional, Default=False)
+            If `True` use the API resource URL, `False`
+            use the filings resource URL.
+
         ### Returns
         ----
         str:
             The full URL with the endpoint needed.
         """
 
-        url = self.resource + endpoint
+        if use_api:
+            url = self.api_resource + endpoint
+        else:
+            url = self.resource + endpoint
 
         return url
 
@@ -84,7 +90,8 @@ def make_request(
         endpoint: str,
         params: dict = None,
         data: dict = None,
-        json_payload: dict = None
+        json_payload: dict = None,
+        use_api: bool = False
     ) -> Dict:
         """Handles all the requests in the library.
 
@@ -112,13 +119,17 @@ def make_request(
         json : dict (optional, Default=None)
             A json data payload for a request
 
+        use_api : bool (optional, Default=False)
+            If `True` use the API resource URL, `False`
+            use the filings resource URL.
+
         ### Returns:
         ----
             A Dictionary object containing the JSON values.
         """
 
         # Build the URL.
-        url = self.build_url(endpoint=endpoint)
+        url = self.build_url(endpoint=endpoint, use_api=use_api)
 
         logging.info(
             "URL: {url}".format(url=url)
@@ -144,11 +155,18 @@ def make_request(
 
         print(request_request.url)
 
+        self.total_requests += 1
+
         # Send the request.
         response: requests.Response = request_session.send(
             request=request_request
         )
 
+        if self.total_requests == 9:
+            print("sleeping for 5 seconds.")
+            time.sleep(5)
+            self.total_requests = 0
+
         # Keep going.
         while response.status_code != 200:
 
@@ -157,6 +175,7 @@ def make_request(
                     request=request_request
                 )
             except:
+                print("Sleeping for five seconds")
                 time.sleep(5)
 
         # Close the session.
@@ -166,8 +185,6 @@ def make_request(
         response_headers = response.headers
         content_type = response_headers['Content-Type']
 
-
-
         # If it's okay and no details.
         if response.ok and len(response.content) > 0:
 

edgar/submissions.py

@@ -0,0 +1,73 @@
+from edgar.session import EdgarSession
+from edgar.utilis import EdgarUtilities
+
+
+class Submissions():
+
+    """
+    ## Overview:
+    ----
+    Allows a user to query each entity’s current filing
+    history using the SEC Restful API.
+    """
+
+    def __init__(self, session: EdgarSession) -> None:
+        """Initializes the `Submissions` object.
+
+        ### Parameters
+        ----
+        session : `EdgarSession`
+            An initialized session of the `EdgarSession`.
+
+        ### Usage
+        ----
+            >>> edgar_client = EdgarClient()
+            >>> submissions_service = edgar_client.submissions()
+        """
+
+        # Set the session.
+        self.edgar_session: EdgarSession = session
+        self.edgar_utilities: EdgarUtilities = EdgarUtilities()
+
+    def __repr__(self) -> str:
+        """String representation of the `EdgarClient.Submissions` object."""
+
+        # define the string representation
+        str_representation = '<EdgarClient.Submissions(active=True, connected=True)>'
+
+        return str_representation
+
+    def get_submissions(self, cik: str) -> dict:
+        """Returns all the ownership filings for a given CIK number.
+
+        ### Arguments:
+        ----
+        cik : str
+            The CIK number you want to query.
+
+        ### Returns:
+        ----
+        dict :
+            A collection of `Submission` resource objects.
+
+        ### Usage:
+        ----
+            >>> edgar_client = EdgarClient()
+            >>> submissions_service = edgar_client.submissions()
+            >>> submissions_service.get_submissions(
+                cik='1326801'
+            )
+        """
+
+        if len(cik) < 10:
+            num_of_zeros = 10 - len(cik)
+            cik = num_of_zeros*"0" + cik
+
+        # Grab the Data.
+        response = self.edgar_session.make_request(
+            method='get',
+            endpoint=f'/submissions/CIK{cik}.json',
+            use_api=True
+        )
+
+        return response