feat: Add support for single forms

edgar_tool/url_generator.py

@@ -50,8 +50,18 @@ def __init__(self, **query_args: SearchQueryKwargs):
 
         self._keywords = keywords
         self.entity = entity
-        self._filing_category = query_args.get("filing_category", "all")
-        self.single_forms = query_args.get("single_forms")
+
+        filing_category = query_args.get("filing_category", "custom")
+        single_forms = query_args.get("single_forms")
+        if filing_category != "custom" and single_forms:
+            raise ValueError(
+                "Cannot specify both filing_category and single_forms. "
+                "Passing single_forms automatically sets the filing_category"
+                " to custom. Please choose one or the other."
+            )
+
+        self._filing_category = filing_category
+        self.single_forms = single_forms
         self.date_range_select = date_range_select
         self.start_date = start_date
         self.end_date = end_date
@@ -87,7 +97,7 @@ def filing_category(self):
             "tender_offers_and_going_private_tx": "form-cat9",
             "trust_indentures": "form-cat10",
         }
-        return filing_category_to_sec_form_id[self._filing_category]
+        return filing_category_to_sec_form_id.get(self._filing_category)
 
 
 def generate_search_url_for_kwargs(search_kwargs: SearchQueryKwargs) -> str:
@@ -111,6 +121,9 @@ def generate_search_url_for_kwargs(search_kwargs: SearchQueryKwargs) -> str:
             )
     if validated_params.filing_category:
         query_params["category"] = validated_params.filing_category
+    elif validated_params.single_forms:
+        query_params["category"] = "custom"
+        query_params["forms"] = validated_params.single_forms
     encoded_params = parse.urlencode(
         query_params, doseq=True, encoding="utf-8", quote_via=parse.quote
     )

tests/test_url_generator.py

@@ -161,3 +161,52 @@ def test_generates_correct_url_for_filing_category(filing_category, url_ending):
 
     # THEN
     assert actual_url == expected_url
+
+
+@pytest.mark.parametrize(
+    "single_forms, url_ending",
+    (
+        (["1"], "&forms=1"),
+        (["CORRESP"], "&forms=CORRESP"),
+        (
+            ["F-4, PREC14A, SEC STAFF ACTION"],
+            "&forms=F-4%2C%20PREC14A%2C%20SEC%20STAFF%20ACTION",
+        ),
+    ),
+)
+def test_generates_correct_url_for_single_forms(single_forms, url_ending):
+    # GIVEN
+    expected_url = (
+        f"https://www.sec.gov/edgar/search/#/q=Ignore&category=custom{url_ending}"
+    )
+    test_kwargs = {"keywords": ["Ignore"], "single_forms": single_forms}
+
+    # WHEN
+    actual_url = url_generator.generate_search_url_for_kwargs(test_kwargs)
+
+    # THEN
+    assert actual_url == expected_url
+
+
+def test_raises_an_exception_if_user_passes_both_filing_category_and_single_forms():
+    """When a user filters based on single form type the filing category is automatically
+    set to "custom." Therefore passing a filing category when using single forms both does
+    not make sense and will potentially give the user confusing results if the code ignores
+    the passed filing category and sets it as custom. It's best to raise an error and let
+    the user use either a filing category or single forms.
+    """
+    # GIVEN
+    test_kwargs = {
+        "keywords": ["Ignore"],
+        "single_forms": ["F-4, PREC14A, SEC STAFF ACTION"],
+        "filing_category": "beneficial_ownership_reports",
+    }
+    expected_error_msg = (
+        "Cannot specify both filing_category and single_forms. "
+        "Passing single_forms automatically sets the filing_category"
+        " to custom. Please choose one or the other."
+    )
+
+    # WHEN / THEN
+    with pytest.raises(ValueError, match=expected_error_msg):
+        url_generator.generate_search_url_for_kwargs(test_kwargs)