ilpost-api-wrapper 0.1.0__tar.gz

ilpost_api_wrapper-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Antonio Girasella
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ilpost_api_wrapper-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ilpost-api-wrapper
+Version: 0.1.0
+Summary: Python wrapper for Il Post newspaper API
+Author: Antonio Girasella
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/girasella/ilpost-api-wrapper
+Project-URL: Repository, https://github.com/girasella/ilpost-api-wrapper
+Project-URL: Issues, https://github.com/girasella/ilpost-api-wrapper/issues
+Keywords: ilpost,api,news,italy,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ilpost-api-wrapper
+
+A Python wrapper for the [Il Post](https://www.ilpost.it) public search API.
+Searches articles, podcast episodes, and newsletters — no authentication required.
+
+## Installation
+
+```bash
+pip install ilpost-api-wrapper
+```
+
+Requires Python 3.9+. No third-party dependencies.
+
+## Quick start
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+result = client.search("berlusconi")
+for doc in result.docs:
+    print(doc.title, doc.link)
+```
+
+## API reference
+
+### `IlPostClient(timeout=10)`
+
+| Method | Description |
+|--------|-------------|
+| `search(query, ...)` | General search across all content types |
+| `search_articles(query, ...)` | Articles only |
+| `search_podcasts(query, ...)` | Podcast episodes only |
+| `search_newsletters(query, ...)` | Newsletter issues only |
+| `paginate(query, ...)` | Generator that yields one `SearchResult` per page |
+
+#### Common parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `str` | — | Search term |
+| `page` | `int` | `1` | Page number (1-based) |
+| `hits` | `int` | `10` | Results per page |
+| `sort` | `SortOrder` | `RELEVANCE` | Sort order |
+| `content_type` | `ContentType` | `None` | Filter by content type |
+| `category` | `str` | `None` | Editorial category (articles only) |
+| `date_range` | `DateRange` | `None` | Publication date filter |
+
+#### Enums
+
+**`SortOrder`**
+| Value | Description |
+|-------|-------------|
+| `RELEVANCE` | Sort by relevance score (default) |
+| `NEWEST` | Most recent first |
+| `OLDEST` | Oldest first |
+
+**`ContentType`**
+| Value | Description |
+|-------|-------------|
+| `ARTICLES` | Articles and news posts |
+| `PODCASTS` | Podcast episodes |
+| `NEWSLETTERS` | Newsletter issues |
+
+**`DateRange`**
+| Value | Description |
+|-------|-------------|
+| `ALL_TIME` | Entire archive (default) |
+| `PAST_YEAR` | Past 12 months |
+| `PAST_30_DAYS` | Past 30 days |
+
+### `SearchResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `total` | `int` | Total number of matching results |
+| `docs` | `list[Document]` | Results for this page |
+| `filters` | `list[FilterGroup]` | Available filters with counts |
+| `sort` | `str` | Active sort value |
+| `hits` | `int` | Page size |
+| `page` | `int` | Current page number |
+| `total_pages` | `int` | Total number of pages |
+| `has_next_page` | `bool` | Whether a next page exists |
+| `has_prev_page` | `bool` | Whether a previous page exists |
+
+### `Document`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `id` | `int` | Unique content identifier |
+| `type` | `str` | `"post"`, `"episodes"`, or `"newsletter"` |
+| `title` | `str` | Content title |
+| `link` | `str` | URL to the content page |
+| `timestamp` | `str` | Publication date (ISO 8601, Italian local time) |
+| `summary` | `str` | Short excerpt |
+| `image` | `str` | Cover image URL |
+| `score` | `float` | Relevance score (`0.0` when sorting by date) |
+| `subscriber` | `bool` | `True` if content is paywalled |
+| `highlight` | `str \| None` | Snippet with matched term in `<span>` tags |
+| `category` | `str \| None` | Editorial category (articles only) |
+| `post_tag_text` | `list[str]` | Tags (articles only) |
+| `derived_info` | `dict` | Extra data: episode or newsletter metadata |
+| `is_article` | `bool` | Convenience property |
+| `is_podcast` | `bool` | Convenience property |
+| `is_newsletter` | `bool` | Convenience property |
+| `is_paywalled` | `bool` | Alias for `subscriber` |
+
+## Examples
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+# Most recent articles in politics
+result = client.search_articles(
+    "renzi",
+    sort=SortOrder.NEWEST,
+    category="politica",
+    date_range=DateRange.PAST_30_DAYS,
+)
+
+# Podcast search
+result = client.search_podcasts("cacao", sort=SortOrder.NEWEST)
+
+# Paginate through all results, 5 per page
+for page in client.paginate("sicilia", hits=5, max_pages=10):
+    print(f"Page {page.page}/{page.total_pages}")
+    for doc in page.docs:
+        print(f"  [{doc.type}] {doc.title}")
+
+# Access filter counts from a response
+result = client.search("europa")
+for group in result.filters:
+    print(f"{group.label}:")
+    for opt in group.options:
+        print(f"  {opt.label}: {opt.doc_count}")
+```
+
+## CLI
+
+A command-line interface is provided via `main.py`:
+
+```
+usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
+                     [--sort {relevance,newest,oldest}]
+                     [--date {all,year,month}] [--category CATEGORY]
+                     [--page PAGE] [--hits HITS] [--all-pages]
+                     [--max-pages N]
+                     query
+```
+
+```bash
+# Basic search
+python main.py berlusconi
+
+# Most recent articles in politics
+python main.py renzi --type articles --sort newest --category politica
+
+# Podcast search, past 30 days
+python main.py cacao --type podcasts --date month
+
+# Page 2, 5 results per page, oldest first
+python main.py 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
+```
+
+## Notes
+
+- Paywalled content (`subscriber: true`) is included in search results — title, summary, and highlight are visible, but the full article requires an active ilpost.it subscription.
+- When sorting by date (`NEWEST` or `OLDEST`), `score` is always `0.0`.
+- The `category` filter only applies to articles. It is ignored by the server when `content_type=PODCASTS`.
+- Timestamps are in Italian local time (CET/CEST) with no UTC offset.

ilpost_api_wrapper-0.1.0/README.md

@@ -0,0 +1,176 @@
+# ilpost-api-wrapper
+
+A Python wrapper for the [Il Post](https://www.ilpost.it) public search API.
+Searches articles, podcast episodes, and newsletters — no authentication required.
+
+## Installation
+
+```bash
+pip install ilpost-api-wrapper
+```
+
+Requires Python 3.9+. No third-party dependencies.
+
+## Quick start
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+result = client.search("berlusconi")
+for doc in result.docs:
+    print(doc.title, doc.link)
+```
+
+## API reference
+
+### `IlPostClient(timeout=10)`
+
+| Method | Description |
+|--------|-------------|
+| `search(query, ...)` | General search across all content types |
+| `search_articles(query, ...)` | Articles only |
+| `search_podcasts(query, ...)` | Podcast episodes only |
+| `search_newsletters(query, ...)` | Newsletter issues only |
+| `paginate(query, ...)` | Generator that yields one `SearchResult` per page |
+
+#### Common parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `str` | — | Search term |
+| `page` | `int` | `1` | Page number (1-based) |
+| `hits` | `int` | `10` | Results per page |
+| `sort` | `SortOrder` | `RELEVANCE` | Sort order |
+| `content_type` | `ContentType` | `None` | Filter by content type |
+| `category` | `str` | `None` | Editorial category (articles only) |
+| `date_range` | `DateRange` | `None` | Publication date filter |
+
+#### Enums
+
+**`SortOrder`**
+| Value | Description |
+|-------|-------------|
+| `RELEVANCE` | Sort by relevance score (default) |
+| `NEWEST` | Most recent first |
+| `OLDEST` | Oldest first |
+
+**`ContentType`**
+| Value | Description |
+|-------|-------------|
+| `ARTICLES` | Articles and news posts |
+| `PODCASTS` | Podcast episodes |
+| `NEWSLETTERS` | Newsletter issues |
+
+**`DateRange`**
+| Value | Description |
+|-------|-------------|
+| `ALL_TIME` | Entire archive (default) |
+| `PAST_YEAR` | Past 12 months |
+| `PAST_30_DAYS` | Past 30 days |
+
+### `SearchResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `total` | `int` | Total number of matching results |
+| `docs` | `list[Document]` | Results for this page |
+| `filters` | `list[FilterGroup]` | Available filters with counts |
+| `sort` | `str` | Active sort value |
+| `hits` | `int` | Page size |
+| `page` | `int` | Current page number |
+| `total_pages` | `int` | Total number of pages |
+| `has_next_page` | `bool` | Whether a next page exists |
+| `has_prev_page` | `bool` | Whether a previous page exists |
+
+### `Document`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `id` | `int` | Unique content identifier |
+| `type` | `str` | `"post"`, `"episodes"`, or `"newsletter"` |
+| `title` | `str` | Content title |
+| `link` | `str` | URL to the content page |
+| `timestamp` | `str` | Publication date (ISO 8601, Italian local time) |
+| `summary` | `str` | Short excerpt |
+| `image` | `str` | Cover image URL |
+| `score` | `float` | Relevance score (`0.0` when sorting by date) |
+| `subscriber` | `bool` | `True` if content is paywalled |
+| `highlight` | `str \| None` | Snippet with matched term in `<span>` tags |
+| `category` | `str \| None` | Editorial category (articles only) |
+| `post_tag_text` | `list[str]` | Tags (articles only) |
+| `derived_info` | `dict` | Extra data: episode or newsletter metadata |
+| `is_article` | `bool` | Convenience property |
+| `is_podcast` | `bool` | Convenience property |
+| `is_newsletter` | `bool` | Convenience property |
+| `is_paywalled` | `bool` | Alias for `subscriber` |
+
+## Examples
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+# Most recent articles in politics
+result = client.search_articles(
+    "renzi",
+    sort=SortOrder.NEWEST,
+    category="politica",
+    date_range=DateRange.PAST_30_DAYS,
+)
+
+# Podcast search
+result = client.search_podcasts("cacao", sort=SortOrder.NEWEST)
+
+# Paginate through all results, 5 per page
+for page in client.paginate("sicilia", hits=5, max_pages=10):
+    print(f"Page {page.page}/{page.total_pages}")
+    for doc in page.docs:
+        print(f"  [{doc.type}] {doc.title}")
+
+# Access filter counts from a response
+result = client.search("europa")
+for group in result.filters:
+    print(f"{group.label}:")
+    for opt in group.options:
+        print(f"  {opt.label}: {opt.doc_count}")
+```
+
+## CLI
+
+A command-line interface is provided via `main.py`:
+
+```
+usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
+                     [--sort {relevance,newest,oldest}]
+                     [--date {all,year,month}] [--category CATEGORY]
+                     [--page PAGE] [--hits HITS] [--all-pages]
+                     [--max-pages N]
+                     query
+```
+
+```bash
+# Basic search
+python main.py berlusconi
+
+# Most recent articles in politics
+python main.py renzi --type articles --sort newest --category politica
+
+# Podcast search, past 30 days
+python main.py cacao --type podcasts --date month
+
+# Page 2, 5 results per page, oldest first
+python main.py 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
+```
+
+## Notes
+
+- Paywalled content (`subscriber: true`) is included in search results — title, summary, and highlight are visible, but the full article requires an active ilpost.it subscription.
+- When sorting by date (`NEWEST` or `OLDEST`), `score` is always `0.0`.
+- The `category` filter only applies to articles. It is ignored by the server when `content_type=PODCASTS`.
+- Timestamps are in Italian local time (CET/CEST) with no UTC offset.

ilpost_api_wrapper-0.1.0/ilpost/__init__.py

@@ -0,0 +1,13 @@
+from .client import IlPostClient
+from .models import SearchResult, Document, FilterGroup, FilterOption, SortOrder, ContentType, DateRange
+
+__all__ = [
+    "IlPostClient",
+    "SearchResult",
+    "Document",
+    "FilterGroup",
+    "FilterOption",
+    "SortOrder",
+    "ContentType",
+    "DateRange",
+]

ilpost_api_wrapper-0.1.0/ilpost/client.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+from typing import Optional, Union
+from urllib.parse import urlencode, quote
+
+import urllib.request
+import json
+
+from .models import SearchResult, SortOrder, ContentType, DateRange
+
+_BASE_URL = "https://api.ilpost.org/search/api/site_search/"
+
+
+def _build_filters(
+    content_type: Optional[ContentType] = None,
+    category: Optional[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}")
+    if date_range is not None:
+        parts.append(f"pub_date:{date_range.value}")
+    return ",".join(parts)
+
+
+class IlPostClient:
+    """Thin wrapper around the Il Post public search API.
+
+    Parameters
+    ----------
+    timeout:
+        HTTP request timeout in seconds (default: 10).
+    """
+
+    def __init__(self, timeout: int = 10) -> None:
+        self.timeout = timeout
+
+    def _get(self, params: dict) -> dict:
+        qs = urlencode(params, quote_via=quote)
+        url = f"{_BASE_URL}?{qs}"
+        with urllib.request.urlopen(url, timeout=self.timeout) as response:
+            return json.loads(response.read().decode("utf-8"))
+
+    def search(
+        self,
+        query: str,
+        *,
+        page: int = 1,
+        hits: int = 10,
+        sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
+        content_type: Optional[ContentType] = None,
+        category: Optional[str] = None,
+        date_range: Optional[DateRange] = None,
+        filters: Optional[str] = None,
+    ) -> SearchResult:
+        """Search Il Post content.
+
+        Parameters
+        ----------
+        query:
+            Search term.
+        page:
+            1-based page number (default: 1).
+        hits:
+            Results per page (default: 10).
+        sort:
+            Sort order. ``SortOrder.RELEVANCE`` (default), ``SortOrder.NEWEST``,
+            or ``SortOrder.OLDEST``.
+        content_type:
+            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.
+        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``.
+
+        Returns
+        -------
+        SearchResult
+        """
+        if filters is None:
+            filters = _build_filters(content_type, category, date_range)
+
+        sort_value = sort.value if isinstance(sort, SortOrder) else sort
+
+        params = {
+            "qs": query,
+            "pg": page,
+            "sort": sort_value,
+            "filters": filters,
+            "hits": hits,
+        }
+
+        data = self._get(params)
+        return SearchResult.from_dict(data, page=page, query=query)
+
+    def search_articles(
+        self,
+        query: str,
+        *,
+        page: int = 1,
+        hits: int = 10,
+        sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
+        category: Optional[str] = None,
+        date_range: Optional[DateRange] = None,
+    ) -> SearchResult:
+        """Search articles only. Convenience wrapper around :meth:`search`."""
+        return self.search(
+            query,
+            page=page,
+            hits=hits,
+            sort=sort,
+            content_type=ContentType.ARTICLES,
+            category=category,
+            date_range=date_range,
+        )
+
+    def search_podcasts(
+        self,
+        query: str,
+        *,
+        page: int = 1,
+        hits: int = 10,
+        sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
+        date_range: Optional[DateRange] = None,
+    ) -> SearchResult:
+        """Search podcast episodes only. Convenience wrapper around :meth:`search`."""
+        return self.search(
+            query,
+            page=page,
+            hits=hits,
+            sort=sort,
+            content_type=ContentType.PODCASTS,
+            date_range=date_range,
+        )
+
+    def search_newsletters(
+        self,
+        query: str,
+        *,
+        page: int = 1,
+        hits: int = 10,
+        sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
+        date_range: Optional[DateRange] = None,
+    ) -> SearchResult:
+        """Search newsletter issues only. Convenience wrapper around :meth:`search`."""
+        return self.search(
+            query,
+            page=page,
+            hits=hits,
+            sort=sort,
+            content_type=ContentType.NEWSLETTERS,
+            date_range=date_range,
+        )
+
+    def paginate(
+        self,
+        query: str,
+        *,
+        hits: int = 10,
+        sort: Union[SortOrder, str] = SortOrder.RELEVANCE,
+        content_type: Optional[ContentType] = None,
+        category: Optional[str] = None,
+        date_range: Optional[DateRange] = None,
+        max_pages: Optional[int] = None,
+    ):
+        """Iterate over all pages of search results, yielding one :class:`SearchResult`
+        per page.
+
+        Parameters
+        ----------
+        max_pages:
+            Stop after this many pages. ``None`` means iterate until exhausted.
+
+        Yields
+        ------
+        SearchResult
+        """
+        page = 1
+        while True:
+            result = self.search(
+                query,
+                page=page,
+                hits=hits,
+                sort=sort,
+                content_type=content_type,
+                category=category,
+                date_range=date_range,
+            )
+            yield result
+            if not result.has_next_page:
+                break
+            if max_pages is not None and page >= max_pages:
+                break
+            page += 1

ilpost_api_wrapper-0.1.0/ilpost/models.py

@@ -0,0 +1,145 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class SortOrder(str, Enum):
+    RELEVANCE = "default"
+    NEWEST = "date_d"
+    OLDEST = "date_a"
+
+
+class ContentType(str, Enum):
+    ARTICLES = "articoli"
+    PODCASTS = "podcast"
+    NEWSLETTERS = "newsletter"
+
+
+class DateRange(str, Enum):
+    ALL_TIME = "da_sempre"
+    PAST_YEAR = "ultimo_anno"
+    PAST_30_DAYS = "ultimi_30_giorni"
+
+
+@dataclass
+class FilterOption:
+    key: str
+    label: str
+    doc_count: int
+    selected: bool
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FilterOption:
+        return cls(
+            key=data["key"],
+            label=data["label"],
+            doc_count=data["doc_count"],
+            selected=data["selected"],
+        )
+
+
+@dataclass
+class FilterGroup:
+    name: str
+    label: str
+    multi: bool
+    options: list[FilterOption]
+
+    @classmethod
+    def from_dict(cls, data: dict) -> FilterGroup:
+        return cls(
+            name=data["name"],
+            label=data["label"],
+            multi=data["multi"],
+            options=[FilterOption.from_dict(c) for c in data.get("contents", [])],
+        )
+
+
+@dataclass
+class Document:
+    id: int
+    type: str
+    title: str
+    link: str
+    timestamp: str
+    summary: str
+    image: str
+    score: float
+    subscriber: bool
+    highlight: Optional[str] = None
+    category: Optional[str] = None
+    post_tag_text: list[str] = field(default_factory=list)
+    derived_info: dict = field(default_factory=dict)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Document:
+        return cls(
+            id=data["id"],
+            type=data["type"],
+            title=data["title"],
+            link=data["link"],
+            timestamp=data["timestamp"],
+            summary=data.get("summary", ""),
+            image=data.get("image", ""),
+            score=data.get("score", 0.0),
+            subscriber=data.get("subscriber", False),
+            highlight=data.get("highlight", {}).get("content"),
+            category=data.get("category"),
+            post_tag_text=data.get("post_tag_text", []),
+            derived_info=data.get("derived_info", {}),
+        )
+
+    @property
+    def is_article(self) -> bool:
+        return self.type == "post"
+
+    @property
+    def is_podcast(self) -> bool:
+        return self.type == "episodes"
+
+    @property
+    def is_newsletter(self) -> bool:
+        return self.type == "newsletter"
+
+    @property
+    def is_paywalled(self) -> bool:
+        return self.subscriber
+
+
+@dataclass
+class SearchResult:
+    total: int
+    docs: list[Document]
+    filters: list[FilterGroup]
+    sort: str
+    hits: int
+    page: int
+    query: str
+
+    @classmethod
+    def from_dict(cls, data: dict, page: int, query: str) -> SearchResult:
+        return cls(
+            total=data["total"],
+            docs=[Document.from_dict(d) for d in data.get("docs", [])],
+            filters=[FilterGroup.from_dict(f) for f in data.get("filters", [])],
+            sort=data.get("sort", "default"),
+            hits=data.get("hits", 10),
+            page=page,
+            query=query,
+        )
+
+    @property
+    def total_pages(self) -> int:
+        if self.hits == 0:
+            return 0
+        return -(-self.total // self.hits)  # ceiling division
+
+    @property
+    def has_next_page(self) -> bool:
+        return self.page < self.total_pages
+
+    @property
+    def has_prev_page(self) -> bool:
+        return self.page > 1

ilpost_api_wrapper-0.1.0/ilpost_api_wrapper.egg-info/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.4
+Name: ilpost-api-wrapper
+Version: 0.1.0
+Summary: Python wrapper for Il Post newspaper API
+Author: Antonio Girasella
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/girasella/ilpost-api-wrapper
+Project-URL: Repository, https://github.com/girasella/ilpost-api-wrapper
+Project-URL: Issues, https://github.com/girasella/ilpost-api-wrapper/issues
+Keywords: ilpost,api,news,italy,search
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# ilpost-api-wrapper
+
+A Python wrapper for the [Il Post](https://www.ilpost.it) public search API.
+Searches articles, podcast episodes, and newsletters — no authentication required.
+
+## Installation
+
+```bash
+pip install ilpost-api-wrapper
+```
+
+Requires Python 3.9+. No third-party dependencies.
+
+## Quick start
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+result = client.search("berlusconi")
+for doc in result.docs:
+    print(doc.title, doc.link)
+```
+
+## API reference
+
+### `IlPostClient(timeout=10)`
+
+| Method | Description |
+|--------|-------------|
+| `search(query, ...)` | General search across all content types |
+| `search_articles(query, ...)` | Articles only |
+| `search_podcasts(query, ...)` | Podcast episodes only |
+| `search_newsletters(query, ...)` | Newsletter issues only |
+| `paginate(query, ...)` | Generator that yields one `SearchResult` per page |
+
+#### Common parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `query` | `str` | — | Search term |
+| `page` | `int` | `1` | Page number (1-based) |
+| `hits` | `int` | `10` | Results per page |
+| `sort` | `SortOrder` | `RELEVANCE` | Sort order |
+| `content_type` | `ContentType` | `None` | Filter by content type |
+| `category` | `str` | `None` | Editorial category (articles only) |
+| `date_range` | `DateRange` | `None` | Publication date filter |
+
+#### Enums
+
+**`SortOrder`**
+| Value | Description |
+|-------|-------------|
+| `RELEVANCE` | Sort by relevance score (default) |
+| `NEWEST` | Most recent first |
+| `OLDEST` | Oldest first |
+
+**`ContentType`**
+| Value | Description |
+|-------|-------------|
+| `ARTICLES` | Articles and news posts |
+| `PODCASTS` | Podcast episodes |
+| `NEWSLETTERS` | Newsletter issues |
+
+**`DateRange`**
+| Value | Description |
+|-------|-------------|
+| `ALL_TIME` | Entire archive (default) |
+| `PAST_YEAR` | Past 12 months |
+| `PAST_30_DAYS` | Past 30 days |
+
+### `SearchResult`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `total` | `int` | Total number of matching results |
+| `docs` | `list[Document]` | Results for this page |
+| `filters` | `list[FilterGroup]` | Available filters with counts |
+| `sort` | `str` | Active sort value |
+| `hits` | `int` | Page size |
+| `page` | `int` | Current page number |
+| `total_pages` | `int` | Total number of pages |
+| `has_next_page` | `bool` | Whether a next page exists |
+| `has_prev_page` | `bool` | Whether a previous page exists |
+
+### `Document`
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `id` | `int` | Unique content identifier |
+| `type` | `str` | `"post"`, `"episodes"`, or `"newsletter"` |
+| `title` | `str` | Content title |
+| `link` | `str` | URL to the content page |
+| `timestamp` | `str` | Publication date (ISO 8601, Italian local time) |
+| `summary` | `str` | Short excerpt |
+| `image` | `str` | Cover image URL |
+| `score` | `float` | Relevance score (`0.0` when sorting by date) |
+| `subscriber` | `bool` | `True` if content is paywalled |
+| `highlight` | `str \| None` | Snippet with matched term in `<span>` tags |
+| `category` | `str \| None` | Editorial category (articles only) |
+| `post_tag_text` | `list[str]` | Tags (articles only) |
+| `derived_info` | `dict` | Extra data: episode or newsletter metadata |
+| `is_article` | `bool` | Convenience property |
+| `is_podcast` | `bool` | Convenience property |
+| `is_newsletter` | `bool` | Convenience property |
+| `is_paywalled` | `bool` | Alias for `subscriber` |
+
+## Examples
+
+```python
+from ilpost import IlPostClient, SortOrder, ContentType, DateRange
+
+client = IlPostClient()
+
+# Most recent articles in politics
+result = client.search_articles(
+    "renzi",
+    sort=SortOrder.NEWEST,
+    category="politica",
+    date_range=DateRange.PAST_30_DAYS,
+)
+
+# Podcast search
+result = client.search_podcasts("cacao", sort=SortOrder.NEWEST)
+
+# Paginate through all results, 5 per page
+for page in client.paginate("sicilia", hits=5, max_pages=10):
+    print(f"Page {page.page}/{page.total_pages}")
+    for doc in page.docs:
+        print(f"  [{doc.type}] {doc.title}")
+
+# Access filter counts from a response
+result = client.search("europa")
+for group in result.filters:
+    print(f"{group.label}:")
+    for opt in group.options:
+        print(f"  {opt.label}: {opt.doc_count}")
+```
+
+## CLI
+
+A command-line interface is provided via `main.py`:
+
+```
+usage: ilpost-search [-h] [--type {articles,podcasts,newsletters}]
+                     [--sort {relevance,newest,oldest}]
+                     [--date {all,year,month}] [--category CATEGORY]
+                     [--page PAGE] [--hits HITS] [--all-pages]
+                     [--max-pages N]
+                     query
+```
+
+```bash
+# Basic search
+python main.py berlusconi
+
+# Most recent articles in politics
+python main.py renzi --type articles --sort newest --category politica
+
+# Podcast search, past 30 days
+python main.py cacao --type podcasts --date month
+
+# Page 2, 5 results per page, oldest first
+python main.py 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
+```
+
+## Notes
+
+- Paywalled content (`subscriber: true`) is included in search results — title, summary, and highlight are visible, but the full article requires an active ilpost.it subscription.
+- When sorting by date (`NEWEST` or `OLDEST`), `score` is always `0.0`.
+- The `category` filter only applies to articles. It is ignored by the server when `content_type=PODCASTS`.
+- Timestamps are in Italian local time (CET/CEST) with no UTC offset.

ilpost_api_wrapper-0.1.0/ilpost_api_wrapper.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+ilpost/__init__.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/top_level.txt

ilpost_api_wrapper-0.1.0/ilpost_api_wrapper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ilpost_api_wrapper-0.1.0/ilpost_api_wrapper.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+dist
+ilpost

ilpost_api_wrapper-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=64"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ilpost-api-wrapper"
+version = "0.1.0"
+description = "Python wrapper for Il Post newspaper API"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Antonio Girasella" },
+]
+keywords = ["ilpost", "api", "news", "italy", "search"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+
+[project.urls]
+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"
+
+[tool.setuptools.packages.find]
+where = ["."]

ilpost_api_wrapper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+