ilpost-api-wrapper 0.1.0__tar.gz → 0.3.0__tar.gz

{ilpost_api_wrapper-0.1.0/ilpost_api_wrapper.egg-info → ilpost_api_wrapper-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ilpost-api-wrapper
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python wrapper for Il Post newspaper API
 Author: Antonio Girasella
 License-Expression: MIT
@@ -166,7 +166,7 @@ for group in result.filters:
 
 ## CLI
 
-A command-line interface is provided via `main.py`:
+The `ilpost-search` command is included with the package:
 
 ```
 usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
@@ -179,19 +179,19 @@ usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
 
 ```bash
 # Basic search
-python main.py berlusconi
+ilpost-search berlusconi
 
 # Most recent articles in politics
-python main.py renzi --type articles --sort newest --category politica
+ilpost-search renzi --type articles --sort newest --category politica
 
 # Podcast search, past 30 days
-python main.py cacao --type podcasts --date month
+ilpost-search cacao --type podcasts --date month
 
 # Page 2, 5 results per page, oldest first
-python main.py sicilia --sort oldest --hits 5 --page 2
+ilpost-search sicilia --sort oldest --hits 5 --page 2
 
 # Fetch all pages of newsletter results (up to 3 pages)
-python main.py economia --type newsletters --all-pages --max-pages 3
+ilpost-search economia --type newsletters --all-pages --max-pages 3
 ```
 
 ## Notes

{ilpost_api_wrapper-0.1.0 → ilpost_api_wrapper-0.3.0}/README.md

@@ -140,7 +140,7 @@ for group in result.filters:
 
 ## CLI
 
-A command-line interface is provided via `main.py`:
+The `ilpost-search` command is included with the package:
 
 ```
 usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
@@ -153,19 +153,19 @@ usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
 
 ```bash
 # Basic search
-python main.py berlusconi
+ilpost-search berlusconi
 
 # Most recent articles in politics
-python main.py renzi --type articles --sort newest --category politica
+ilpost-search renzi --type articles --sort newest --category politica
 
 # Podcast search, past 30 days
-python main.py cacao --type podcasts --date month
+ilpost-search cacao --type podcasts --date month
 
 # Page 2, 5 results per page, oldest first
-python main.py sicilia --sort oldest --hits 5 --page 2
+ilpost-search sicilia --sort oldest --hits 5 --page 2
 
 # Fetch all pages of newsletter results (up to 3 pages)
-python main.py economia --type newsletters --all-pages --max-pages 3
+ilpost-search economia --type newsletters --all-pages --max-pages 3
 ```
 
 ## Notes

ilpost_api_wrapper-0.3.0/ilpost/cli.py

@@ -0,0 +1,164 @@
+import argparse
+import sys
+
+from .client import IlPostClient
+from .models import SortOrder, ContentType, DateRange
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="ilpost-search",
+        description="Search Il Post articles, podcasts, and newsletters.",
+    )
+
+    parser.add_argument("query", help="Search term")
+
+    parser.add_argument(
+        "--type", "-t",
+        dest="content_type",
+        choices=["articles", "podcasts", "newsletters"],
+        default=None,
+        help="Filter by content type (default: all)",
+    )
+    parser.add_argument(
+        "--sort", "-s",
+        choices=["relevance", "newest", "oldest"],
+        default="relevance",
+        help="Sort order (default: relevance)",
+    )
+    parser.add_argument(
+        "--date", "-d",
+        dest="date_range",
+        choices=["all", "year", "month"],
+        default=None,
+        help="Publication date filter: all / year (past 12 months) / month (past 30 days)",
+    )
+    parser.add_argument(
+        "--category", "-c",
+        default=None,
+        metavar="CATEGORY",
+        help="Editorial category, e.g. politica, cultura, economia (articles only)",
+    )
+    parser.add_argument(
+        "--page", "-p",
+        type=int,
+        default=1,
+        help="Page number, 1-based (default: 1)",
+    )
+    parser.add_argument(
+        "--hits", "-n",
+        type=int,
+        default=10,
+        help="Results per page (default: 10)",
+    )
+    parser.add_argument(
+        "--all-pages",
+        action="store_true",
+        help="Fetch and print all pages (ignores --page)",
+    )
+    parser.add_argument(
+        "--max-pages",
+        type=int,
+        default=None,
+        metavar="N",
+        help="Maximum number of pages to fetch when using --all-pages",
+    )
+
+    return parser
+
+
+_SORT_MAP = {
+    "relevance": SortOrder.RELEVANCE,
+    "newest": SortOrder.NEWEST,
+    "oldest": SortOrder.OLDEST,
+}
+
+_CTYPE_MAP = {
+    "articles": ContentType.ARTICLES,
+    "podcasts": ContentType.PODCASTS,
+    "newsletters": ContentType.NEWSLETTERS,
+}
+
+_DATE_MAP = {
+    "all": DateRange.ALL_TIME,
+    "year": DateRange.PAST_YEAR,
+    "month": DateRange.PAST_30_DAYS,
+}
+
+_TYPE_LABEL = {
+    "post": "article",
+    "episodes": "podcast",
+    "newsletter": "newsletter",
+}
+
+
+def print_result(result, *, show_header: bool = True) -> None:
+    if show_header:
+        print(f'\nQuery: "{result.query}"  |  '
+              f"Total: {result.total}  |  "
+              f"Page: {result.page}/{result.total_pages}  |  "
+              f"Sort: {result.sort}")
+        print("-" * 72)
+
+    if not result.docs:
+        print("No results.")
+        return
+
+    for doc in result.docs:
+        label = _TYPE_LABEL.get(doc.type, doc.type)
+        paywall = " [subscribers only]" if doc.is_paywalled else ""
+        score = f"  score={doc.score:.2f}" if doc.score else ""
+        category = f"  [{doc.category}]" if doc.category else ""
+        print(f"[{label}]{category}{paywall}{score}")
+        print(f"  {doc.title}")
+        print(f"  {doc.link}")
+        if doc.highlight:
+            # strip HTML span tags for plain-text display
+            snippet = doc.highlight.replace("<span>", ">>").replace("</span>", "<<")
+            print(f"  ...{snippet}...")
+        print()
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+
+    sort = _SORT_MAP[args.sort]
+    content_type = _CTYPE_MAP.get(args.content_type)
+    date_range = _DATE_MAP.get(args.date_range)
+
+    client = IlPostClient()
+
+    try:
+        if args.all_pages:
+            first = True
+            for page_result in client.paginate(
+                args.query,
+                hits=args.hits,
+                sort=sort,
+                content_type=content_type,
+                category=args.category,
+                date_range=date_range,
+                max_pages=args.max_pages,
+            ):
+                print_result(page_result, show_header=first)
+                first = False
+        else:
+            result = client.search(
+                args.query,
+                page=args.page,
+                hits=args.hits,
+                sort=sort,
+                content_type=content_type,
+                category=args.category,
+                date_range=date_range,
+            )
+            print_result(result)
+
+    except Exception as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

{ilpost_api_wrapper-0.1.0 → ilpost_api_wrapper-0.3.0}/ilpost/client.py

@@ -13,17 +13,19 @@ _BASE_URL = "https://api.ilpost.org/search/api/site_search/"
 
 def _build_filters(
     content_type: Optional[ContentType] = None,
-    category: Optional[str] = None,
+    category: Optional[Union[str, list[str]]] = None,
     date_range: Optional[DateRange] = None,
 ) -> str:
     parts: list[str] = []
     if content_type is not None:
         parts.append(f"ctype:{content_type.value}")
     if category is not None:
-        parts.append(f"category:{category}")
+        cats = [category] if isinstance(category, str) else category
+        for cat in cats:
+            parts.append(f"category:{cat}")
     if date_range is not None:
         parts.append(f"pub_date:{date_range.value}")
-    return ",".join(parts)
+    return ";".join(parts)
 
 
 class IlPostClient:
@@ -52,7 +54,7 @@ class IlPostClient:
         hits: int = 10,
         sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
         content_type: Optional[ContentType] = None,
-        category: Optional[str] = None,
+        category: Optional[Union[str, list[str]]] = None,
         date_range: Optional[DateRange] = None,
         filters: Optional[str] = None,
     ) -> SearchResult:
@@ -61,7 +63,18 @@ class IlPostClient:
         Parameters
         ----------
         query:
-            Search term.
+            Search term. Supports:
+
+            - Exact phrase: ``'"goffredo fofi"'``
+            - Boolean OR: ``"fofi | berlusconi"`` (``|`` and ``OR`` both work)
+            - Boolean AND: ``"fofi AND berlusconi"`` or just ``"fofi berlusconi"``
+            - Boolean NOT: ``"berlusconi NOT fininvest"``
+
+            The following syntax does **not** work and should be avoided:
+
+            - Field prefix (``title:fofi``, ``content:fofi``) — treated as literal tokens
+            - Boost operator (``berlusconi^10``) — the numeric value becomes a search token
+            - Proximity queries (``"goffredo fofi"~5``) — inflates results unpredictably
         page:
             1-based page number (default: 1).
         hits:
@@ -73,15 +86,17 @@ class IlPostClient:
             Filter by content type: ``ContentType.ARTICLES``, ``ContentType.PODCASTS``,
             or ``ContentType.NEWSLETTERS``.
         category:
-            Filter articles by editorial category (e.g. ``"politica"``, ``"cultura"``).
-            Only meaningful when ``content_type=ContentType.ARTICLES`` or no content
-            type filter is set.
+            Filter articles by editorial category. Pass a single string
+            (e.g. ``"politica"``) or a list to AND multiple categories together
+            (e.g. ``["cultura", "libri"]``). Only meaningful when
+            ``content_type=ContentType.ARTICLES`` or no content type filter is set.
         date_range:
             Filter by publication date: ``DateRange.ALL_TIME``, ``DateRange.PAST_YEAR``,
             or ``DateRange.PAST_30_DAYS``.
         filters:
-            Raw pre-encoded filter string (e.g. ``"ctype:articoli,pub_date:ultimo_anno"``).
-            When provided, overrides ``content_type``, ``category``, and ``date_range``.
+            Raw pre-encoded filter string (e.g. ``"ctype:articoli;pub_date:ultimo_anno"``).
+            Filters are separated by ``;``. When provided, overrides ``content_type``,
+            ``category``, and ``date_range``.
 
         Returns
         -------
@@ -110,7 +125,7 @@ class IlPostClient:
         page: int = 1,
         hits: int = 10,
         sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
-        category: Optional[str] = None,
+        category: Optional[Union[str, list[str]]] = None,
         date_range: Optional[DateRange] = None,
     ) -> SearchResult:
         """Search articles only. Convenience wrapper around :meth:`search`."""
@@ -169,7 +184,7 @@ class IlPostClient:
         hits: int = 10,
         sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
         content_type: Optional[ContentType] = None,
-        category: Optional[str] = None,
+        category: Optional[Union[str, list[str]]] = None,
         date_range: Optional[DateRange] = None,
         max_pages: Optional[int] = None,
     ):

{ilpost_api_wrapper-0.1.0 → ilpost_api_wrapper-0.3.0/ilpost_api_wrapper.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ilpost-api-wrapper
-Version: 0.1.0
+Version: 0.3.0
 Summary: Python wrapper for Il Post newspaper API
 Author: Antonio Girasella
 License-Expression: MIT
@@ -166,7 +166,7 @@ for group in result.filters:
 
 ## CLI
 
-A command-line interface is provided via `main.py`:
+The `ilpost-search` command is included with the package:
 
 ```
 usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
@@ -179,19 +179,19 @@ usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
 
 ```bash
 # Basic search
-python main.py berlusconi
+ilpost-search berlusconi
 
 # Most recent articles in politics
-python main.py renzi --type articles --sort newest --category politica
+ilpost-search renzi --type articles --sort newest --category politica
 
 # Podcast search, past 30 days
-python main.py cacao --type podcasts --date month
+ilpost-search cacao --type podcasts --date month
 
 # Page 2, 5 results per page, oldest first
-python main.py sicilia --sort oldest --hits 5 --page 2
+ilpost-search sicilia --sort oldest --hits 5 --page 2
 
 # Fetch all pages of newsletter results (up to 3 pages)
-python main.py economia --type newsletters --all-pages --max-pages 3
+ilpost-search economia --type newsletters --all-pages --max-pages 3
 ```
 
 ## Notes

{ilpost_api_wrapper-0.1.0 → ilpost_api_wrapper-0.3.0}/ilpost_api_wrapper.egg-info/SOURCES.txt

@@ -2,10 +2,12 @@ LICENSE
 README.md
 pyproject.toml
 ilpost/__init__.py
+ilpost/cli.py
 ilpost/client.py
 ilpost/models.py
 ilpost/py.typed
 ilpost_api_wrapper.egg-info/PKG-INFO
 ilpost_api_wrapper.egg-info/SOURCES.txt
 ilpost_api_wrapper.egg-info/dependency_links.txt
+ilpost_api_wrapper.egg-info/entry_points.txt
 ilpost_api_wrapper.egg-info/top_level.txt

ilpost_api_wrapper-0.3.0/ilpost_api_wrapper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ilpost-search = ilpost.cli:main

{ilpost_api_wrapper-0.1.0 → ilpost_api_wrapper-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ilpost-api-wrapper"
-version = "0.1.0"
+version = "0.3.0"
 description = "Python wrapper for Il Post newspaper API"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -33,5 +33,8 @@ Homepage = "https://github.com/girasella/ilpost-api-wrapper"
 Repository = "https://github.com/girasella/ilpost-api-wrapper"
 Issues = "https://github.com/girasella/ilpost-api-wrapper/issues"
 
+[project.scripts]
+ilpost-search = "ilpost.cli:main"
+
 [tool.setuptools.packages.find]
 where = ["."]