Add additional search query filters (#97)

.bumpversion.cfg

@@ -0,0 +1,10 @@
+[bumpversion]
+current_version = 0.10.0
+commit = True
+verbose = True
+
+[bumpversion:file:README.md]
+
+[bumpversion:file:meta.yaml]
+
+[bumpversion:file:pynytimes/__version__.py]

.github/workflows/python-full-tests.yaml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: [3.9, "3.10", "3.11", "pypy-3.9"]
+        python-version: [3.9, "3.10", "3.11", "3.12", "pypy-3.9"]
 
     steps:
       - uses: actions/checkout@v2

.github/workflows/python-small-tests.yaml

@@ -7,7 +7,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.10", "pypy-3.9"]
+        python-version: ["3.11", "pypy-3.9"]
 
     steps:
       - uses: actions/checkout@v2

README.md

@@ -99,8 +99,7 @@ Search articles using a query using:
 ```python
 articles = nyt.article_search(query="Obama")
 ```
-
-The definition of search query (using the ```query``` option), the amount of results (using ```results```) and the amount of results is optional. Read [the documentation](https://pynytimes.michadenheijer.com/search/article-search) to see how.
+In this example we have just defined the content of the search query (Obama), but we can add many more search parameters. Read [the documentation](https://pynytimes.michadenheijer.com/search/article-search) to see how.
 
 
 ### Book reviews
@@ -201,8 +200,8 @@ If you use ```pynytimes```, a citation would be very much appriciated. If you're
     license = {MIT},
     title = {{pynytimes}},
     url = {https://github.com/michadenheijer/pynytimes},
-    version = {[CITATION VERSION]},
-    year = {[CITATION YEAR]},
+    version = {0.10.0},
+    year = {2023},
     doi = {10.5281/zenodo.7821090}
 }
 ```

meta.yaml

@@ -1,9 +1,9 @@
 package:
   name: "pynytimes"
-  version: "0.8.0"
+  version: "0.10.0"
 
 source:
-  git_rev: v0.8.0
+  git_rev: v0.10.0
   git_url: https://github.com/michadenheijer/pynytimes
 
 requirements:
@@ -13,7 +13,7 @@ requirements:
   build:
     - python
   run:
-    - "python>=3.8,<4"
+    - "python>=3.9,<4"
     - requests
 
 about:

pynytimes/__version__.py

@@ -2,7 +2,7 @@
 __title__ = "pynytimes"
 __description__ = "A Python wrapper for (most) New York Times APIs"
 __url__ = "https://pynytimes.michadenheijer.com/"
-__version__ = "0.9.2"
+__version__ = "0.10.0"
 __author__ = "Micha den Heijer"
 __author_email__ = "[email protected]"
 __license__ = "MIT"

pynytimes/api.py

@@ -52,6 +52,10 @@
         "news_desk": "list[str]",
         "type_of_material": "list[str]",
         "section_name": "list[str]",
+        "subject": "list[str]",
+        "body": "list[str]",
+        "headline": "list[str]",
+        "fq": "str",
     },
     total=False,
 )
@@ -691,7 +695,7 @@ def article_search(
             dates (Optional[dict[Literal["begin", "end"], DateType]],
             optional): Dictionary with "begin" and "end" of search range.
             Defaults to None.
-            options (Optional[dict[str, Any]], optional): Options for the
+            options (Optional[ArticleSearchOptions], optional): Options for the
             search results.
             Defaults to None.
             results (int, optional): Load at most this many articles. Defaults to 10.

pynytimes/helpers/__init__.py

@@ -12,6 +12,9 @@
 from .most_shared import most_shared_check_method, most_shared_check_days
 from .most_shared import most_shared_get_url
 from .most_viewed import most_viewed_check_values
-from .movie_reviews import movie_reviews_check_input, movie_reviews_parse_dates
+from .movie_reviews import (
+    movie_reviews_check_input,
+    movie_reviews_parse_dates,
+)
 from .movie_reviews import movie_reviews_parse_params
 from .tag_query import tag_query_check_types, tag_query_get_filter_options

pynytimes/helpers/article_search.py

@@ -12,6 +12,20 @@
 LARGE_RESULTS_WARN = 100
 MAXIMUM_RESULTS = 2010
 
+# FIXME not all filters are implemented
+
+# Set query options that are currently supported
+CURRENT_FILTER_SUPPORT: list[str] = [
+    "source",
+    "news_desk",
+    "section_name",
+    "glocation",
+    "type_of_material",
+    "subject",
+    "body",
+    "headline",
+]
+
 
 def _article_search_result_warnings(results: int):
     # Show warnings when a lot of results are requested
@@ -109,6 +123,12 @@ def article_search_parse_dates(
 
 
 def _filter_input(values: list) -> str:
+    if not isinstance(values, list):
+        raise TypeError(
+            "One of the parameters in the Article Search function,"
+            " is not a list while it should be"
+        )
+
     input = ""
     # Add all the data in the list to the filter
     for i, value in enumerate(values):
@@ -125,22 +145,17 @@ def article_search_parse_options(options: dict[str, Any]) -> dict:
     # Get options already defined in fq (filter query)
     fq = options.get("fq", "")
 
-    # Set query options that are currently supported
-    current_filter_support = [
-        "source",
-        "news_desk",
-        "section_name",
-        "glocation",
-        "type_of_material",
-    ]
-
     # Run for every filter
-    for _filter in current_filter_support:
+    for _filter in CURRENT_FILTER_SUPPORT:
         # Get data for filter if it's not defined continue to next filter
         values = options.get(_filter)
         if values is None:
             continue
 
+        # Notice that this does not support OR statements, however
+        # implementing would complicate this function a lot.
+        # This may be worth it in the future, but not now.
+
         # Check if filter query is already defined. If it is then add
         # " AND " to the query
         if len(fq) != 0:

setup.py

@@ -38,6 +38,7 @@
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
         "Programming Language :: Python :: Implementation :: CPython",
         "Programming Language :: Python :: Implementation :: PyPy",
         "Topic :: Sociology",

tests.py

@@ -28,7 +28,9 @@ def test_top_stories(self):
 
         for top_story in top_stories:
             self.assertIsInstance(top_story, dict)
-            self.assertIsInstance(top_story["created_date"], datetime.datetime)
+            self.assertIsInstance(
+                top_story["created_date"], datetime.datetime
+            )
             self.assertIsInstance(
                 top_story["published_date"], datetime.datetime
             )
@@ -206,6 +208,16 @@ def test_article_search(self):
         for article in search:
             self.assertIsInstance(article, dict)
 
+    def test_article_search_headline(self):
+        headline_query = "Biden"
+        search = self.nyt.article_search(
+            options={"headline": [headline_query]}
+        )
+        self.assertIsInstance(search, list)
+        for article in search:
+            self.assertIsInstance(article, dict)
+            self.assertIn(headline_query, str(article["headline"]))
+
     def test_article_search_invalid(self):
         with self.assertRaises(TypeError):
             self.nyt.article_search(123)