Update README and add example scripts.

jadchaar · Dec 25, 2021 · 687f9ed · 687f9ed
1 parent 860987a
commit 687f9ed
Show file tree

Hide file tree

Showing 7 changed files with 442 additions and 41 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,4 @@
-cik_mapping.csv
-test.py
+example_mappings.csv
 .vscode/
 .idea/
 

diff --git a/README.rst b/README.rst
diff --git a/examples/mutual_fund_mapper.py b/examples/mutual_fund_mapper.py
@@ -0,0 +1,69 @@
+"""MutualFundMapper usage example. Assumes current working directory
+is the examples folder.
+"""
+
+import sys
+
+sys.path.append("..")
+
+from pathlib import Path  # noqa: E402
+
+from sec_cik_mapper import MutualFundMapper  # noqa: E402
+
+FILENAME = "example_mappings.csv"
+N = 3
+
+mapper = MutualFundMapper()
+
+
+def print_n_items(_dict):
+    first_n_items = list(_dict.items())[:N]
+    new_dict = {}
+    for k, v in first_n_items:
+        if isinstance(v, set):
+            # Get first N items from list then convert back to set
+            # Required since sets are not subscriptable
+            new_dict[k] = set(list(v)[:N])
+        else:
+            new_dict[k] = v
+    print(new_dict)
+    print("====================")
+
+
+csv_path = Path(FILENAME)
+mapper.save_metadata_to_csv(csv_path)
+
+cik_to_tickers = mapper.cik_to_tickers
+print_n_items(cik_to_tickers)
+
+ticker_to_cik = mapper.ticker_to_cik
+print_n_items(ticker_to_cik)
+
+cik_to_series_ids = mapper.cik_to_series_ids
+print_n_items(cik_to_series_ids)
+
+ticker_to_series_id = mapper.ticker_to_series_id
+print_n_items(ticker_to_series_id)
+
+series_id_to_cik = mapper.series_id_to_cik
+print_n_items(series_id_to_cik)
+
+series_id_to_tickers = mapper.series_id_to_tickers
+print_n_items(series_id_to_tickers)
+
+series_id_to_class_ids = mapper.series_id_to_class_ids
+print_n_items(series_id_to_class_ids)
+
+ticker_to_class_id = mapper.ticker_to_class_id
+print_n_items(ticker_to_class_id)
+
+cik_to_class_ids = mapper.cik_to_class_ids
+print_n_items(cik_to_class_ids)
+
+class_id_to_cik = mapper.class_id_to_cik
+print_n_items(class_id_to_cik)
+
+class_id_to_ticker = mapper.class_id_to_ticker
+print_n_items(class_id_to_ticker)
+
+print(mapper.raw_dataframe)
diff --git a/examples/stock_mapper.py b/examples/stock_mapper.py
@@ -0,0 +1,60 @@
+"""StockMapper usage example. Assumes current working directory
+is the examples folder.
+"""
+
+import sys
+
+sys.path.append("..")
+
+from pathlib import Path  # noqa: E402
+
+from sec_cik_mapper import StockMapper  # noqa: E402
+
+FILENAME = "example_mappings.csv"
+N = 3
+
+mapper = StockMapper()
+
+
+def print_n_items(_dict):
+    first_n_items = list(_dict.items())[:N]
+    new_dict = {}
+    for k, v in first_n_items:
+        if isinstance(v, set):
+            # Get first N items from list then convert back to set
+            # Required since sets are not subscriptable
+            new_dict[k] = set(list(v)[:N])
+        else:
+            new_dict[k] = v
+    print(new_dict)
+    print("====================")
+
+
+csv_path = Path(FILENAME)
+mapper.save_metadata_to_csv(csv_path)
+
+cik_to_tickers = mapper.cik_to_tickers
+print_n_items(cik_to_tickers)
+
+ticker_to_cik = mapper.ticker_to_cik
+print_n_items(ticker_to_cik)
+
+cik_to_company_name = mapper.cik_to_company_name
+print_n_items(cik_to_company_name)
+
+ticker_to_company_name = mapper.ticker_to_company_name
+print_n_items(ticker_to_company_name)
+
+ticker_to_exchange = mapper.ticker_to_exchange
+print_n_items(ticker_to_exchange)
+
+exchange_to_tickers = mapper.exchange_to_tickers
+print_n_items(exchange_to_tickers)
+
+cik_to_exchange = mapper.cik_to_exchange
+print_n_items(cik_to_exchange)
+
+exchange_to_ciks = mapper.exchange_to_ciks
+print_n_items(exchange_to_ciks)
+
+print(mapper.raw_dataframe)
diff --git a/pyproject.toml b/pyproject.toml
@@ -55,4 +55,5 @@ Issues = "https://github.com/jadchaar/cik-mapper/issues"
 exclude = [
     "auto_generated_mappings/",
     "scripts/",
+    "examples/",
 ]
diff --git a/scripts/generate_curl_commands.py b/scripts/generate_curl_commands.py
@@ -0,0 +1,91 @@
+"""Generate curl commands for docs."""
+
+import csv
+import sys
+from pathlib import Path
+
+import requests
+
+GENERATED_MAPPINGS_PATH = Path("../auto_generated_mappings")
+
+if not GENERATED_MAPPINGS_PATH.exists():
+    print(f"Folder does not exist: {GENERATED_MAPPINGS_PATH.resolve()}")
+    print("Ensure that your current working directory is the scripts folder.")
+    sys.exit(1)
+
+BASE_URL_GH_RAW = "https://raw.githubusercontent.com/jadchaar/sec-cik-mapper/main/auto_generated_mappings"  # noqa: B950
+BASE_URL_JSDELIVR = (
+    "https://cdn.jsdelivr.net/gh/jadchaar/sec-cik-mapper@main/auto_generated_mappings"
+)
+CURL_TEMPLATE = "curl {0} -O"
+
+RST_TEMPLATE = """
+**GitHub**
+
+.. code-block:: console
+
+{0}
+
+**jsDelivr**
+
+.. code-block:: console
+
+{1}
+"""
+
+
+def generate_urls():
+    print("Generating URLs...", end=" ")
+    url_map = {
+        "gh": [],
+        "jsdelivr": [],
+    }
+    for mapping_type in GENERATED_MAPPINGS_PATH.glob("*"):
+        mapping_folder = GENERATED_MAPPINGS_PATH / mapping_type
+        for file_path in mapping_folder.glob("*"):
+            full_url_gh_raw = f"{BASE_URL_GH_RAW}/{mapping_type.name}/{file_path.name}"
+            full_url_jsdelivr = (
+                f"{BASE_URL_JSDELIVR}/{mapping_type.name}/{file_path.name}"
+            )
+            validate_urls([full_url_gh_raw, full_url_jsdelivr])
+            url_map["gh"].append(full_url_gh_raw)
+            url_map["jsdelivr"].append(full_url_jsdelivr)
+    print("✓")
+    return url_map
+
+
+def print_curl_commands(url_map):
+    print("Generating RST output...", end=" ")
+    output_gh = []
+    for gh_url in url_map["gh"]:
+        curl_cmd = CURL_TEMPLATE.format(gh_url)
+        output_gh.append(f"\t$ {curl_cmd}")
+
+    output_jsdelivr = []
+    for jsdelivr_url in url_map["jsdelivr"]:
+        curl_cmd = CURL_TEMPLATE.format(jsdelivr_url)
+        output_jsdelivr.append(f"\t$ {curl_cmd}")
+
+    formatted_rst = RST_TEMPLATE.format(
+        "\n".join(output_gh), "\n".join(output_jsdelivr)
+    )
+    print("✓")
+    print(formatted_rst)
+
+
+def validate_urls(urls):
+    """Validate URLs by making a GET request, checking status code, and attempting to parse."""
+    for url in urls:
+        resp = requests.get(url)
+        resp.raise_for_status()
+        if url.endswith(".json"):
+            # Parse JSON
+            assert resp.json() is not None, f"Invalid URL: {url}"
+        else:
+            # Parse CSV
+            assert csv.DictReader(resp.iter_lines()) is not None, f"Invalid URL: {url}"
+
+
+if __name__ == "__main__":
+    url_map = generate_urls()
+    print_curl_commands(url_map)
diff --git a/scripts/generate_mappings.py b/scripts/generate_mappings.py
@@ -1,3 +1,5 @@
+"""Fetch and transform mapping data from SEC."""
+
 import json
 import sys
 from pathlib import Path