vlrdevapi 2.2.0__tar.gz → 2.3.0__tar.gz

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/CHANGELOG.md

@@ -5,6 +5,57 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [2.3.0] - 2026-08-11
+
+### Added
+
+- **News namespace** — `vlrdevapi.news(page=1)` lists news items from
+  vlr.gg/news, each with `title`, `subtitle`, `link`, `country_name`,
+  `date`, and `author`, plus `has_next_page` and `page_number` on the
+  returned page.
+- **News article content** — `vlrdevapi.news.article(article_id)` fetches
+  a single news article with its `title`, `author`, `date`, associated
+  `event_name`/`event_link`, and the full `content` body text. The body
+  is also available as Markdown via `content_md`, preserving headings,
+  lists, links, emphasis, and clip embeds.
+- **News out-of-range pages** — requesting a news page beyond the last
+  available page (e.g. `page=176`) now raises `NotFoundError` instead of
+  silently returning an empty result.
+
+### Changed
+
+- **News article Markdown links are absolute** — links in `content_md` are
+  prefixed with `https://www.vlr.gg` when they were relative (e.g.
+  `/player/5132/mada` → `https://www.vlr.gg/player/5132/mada`). Absolute
+  and `www.`-prefixed URLs are left untouched. `NewsArticle.event_link` is
+  now an absolute URL as well.
+
+### Fixed
+
+- **News article clip embeds** — `content_md` clip embeds now link to the
+  directly openable watch URL (e.g. `https://clips.twitch.tv/<slug>`) for
+  Twitch clips, Twitch VODs, YouTube, and Soop embeds, instead of the embed
+  URL which could not be opened in a new tab.
+- **News article Markdown whitespace/emphasis** — inline emphasis and bold
+  render correctly around links: source indentation whitespace no longer
+  produces double spaces, and `*`/`**` markers no longer wrap whitespace.
+- **News article dates are timezone-aware** — the article date is parsed
+  through the shared `commons.parse_vlr_iso_datetime` helper. Offset-aware
+  `datetime` attributes are converted to UTC as-is; naive values are
+  localised to the client's `source_tz` (or UTC) instead of the local
+  machine timezone.
+- **Unknown article IDs raise `NotFoundError`** — vlr.gg returns a generic
+  HTTP 200 page for non-existent article IDs; `news.article()` now detects
+  the missing article card and raises `NotFoundError` instead of returning
+  an empty article.
+- **News article Markdown fidelity** — `content_md` now renders nested
+  lists, tables (as pipe tables), and inline `code` verbatim (whitespace
+  preserved). Links whose href is `www.`-prefixed are upgraded to
+  `https://`, fixing broken relative links in Markdown.
+- **Documentation** — news reference pages updated (article, list, index),
+  plus the getting-started guide, main docs index, and README now cover the
+  news namespace; model/parser docstrings describe the current behaviour.
+
 ## [2.2.0] - 2026-08-11
 
 ### Changed
@@ -142,6 +193,7 @@ The API surface, module structure, and type system are all new.
 - `aiohttp` and `asyncio` dependencies.
 - v1.x match/event/team parsing modules.
 
+[2.3.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.2.0...v2.3.0
 [2.2.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.1.0...v2.2.0
 [2.1.0]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.0.1...v2.1.0
 [2.0.1]: https://github.com/Vanshbordia/vlrdevapi/compare/v2.0.0...v2.0.1

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vlrdevapi
-Version: 2.2.0
+Version: 2.3.0
 Summary: A Python library to scrape data from vlr.gg
 Project-URL: Homepage, https://vlrdevapi.pages.dev/
 Project-URL: Repository, https://github.com/Vanshbordia/vlrdevapi
@@ -68,7 +68,7 @@ Access Valorant esports data from VLR.gg with a clean, type-safe Python API. Get
 
 ## Features
 
-- **Complete Data Access** - Events, matches, players, teams, and series
+- **Complete Data Access** - Events, matches, players, teams, series, and news
 - **Type-Safe** - Pydantic models with rich type hints and field descriptions
 - **Production-Ready** - Retry logic, rate limiting, and LRU-cached enrichment
 - **Curried Access** - Bind a player/team/series ID once, then call sub-methods without re-passing
@@ -181,6 +181,17 @@ performance = s.performance()            # Advanced performance stats
 economy = s.economy(game_id=1)           # Economy data
 ```
 
+### News
+
+```python
+page = client.news(page=1)               # Browse the news listing
+for item in page.news[:5]:
+    print(item.title)
+
+article = client.news.article(734100)    # Fetch a full article
+print(article.content_md)                # Article body as Markdown
+```
+
 ## Documentation
 
 - **Official Docs** - [vlrdevapi.pages.dev/docs](https://vlrdevapi.pages.dev/docs)

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/README.md

@@ -20,7 +20,7 @@ Access Valorant esports data from VLR.gg with a clean, type-safe Python API. Get
 
 ## Features
 
-- **Complete Data Access** - Events, matches, players, teams, and series
+- **Complete Data Access** - Events, matches, players, teams, series, and news
 - **Type-Safe** - Pydantic models with rich type hints and field descriptions
 - **Production-Ready** - Retry logic, rate limiting, and LRU-cached enrichment
 - **Curried Access** - Bind a player/team/series ID once, then call sub-methods without re-passing
@@ -133,6 +133,17 @@ performance = s.performance()            # Advanced performance stats
 economy = s.economy(game_id=1)           # Economy data
 ```
 
+### News
+
+```python
+page = client.news(page=1)               # Browse the news listing
+for item in page.news[:5]:
+    print(item.title)
+
+article = client.news.article(734100)    # Fetch a full article
+print(article.content_md)                # Article body as Markdown
+```
+
 ## Documentation
 
 - **Official Docs** - [vlrdevapi.pages.dev/docs](https://vlrdevapi.pages.dev/docs)

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vlrdevapi"
-version = "2.2.0"
+version = "2.3.0"
 description = "A Python library to scrape data from vlr.gg"
 readme = "README.md"
 requires-python = ">=3.11"

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/scripts/check_mdx_examples.py

@@ -39,7 +39,7 @@ REPO_ROOT = Path(__file__).resolve().parent.parent
 DOCS_DIR = REPO_ROOT / "official-docs" / "content"
 DEFAULT_FIXTURES_DIR = REPO_ROOT / ".cache" / "mdx-html"
 
-DYNAMIC_PATHS = frozenset({"/matches", "/matches/results", "/events"})
+DYNAMIC_PATHS = frozenset({"/matches", "/matches/results", "/events", "/news"})
 
 
 class Result(NamedTuple):

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/scripts/download_fixtures.py

@@ -29,6 +29,16 @@ ROUTES += [
     ("/matches/results/?page=2", "matches/results_page2.html", {}),
 ]
 
+# ── News ───────────────────────────────────────────────────────
+ROUTES += [
+    ("/news", "news/news.html", {}),
+    ("/news/?page=2", "news/news_page2.html", {}),
+    ("/news/?page=126", "news/news_page126.html", {}),
+    ("/news/?page=176", "news/news_page176.html", {}),
+    ("/734100", "news/article_734100.html", {}),
+    ("/720033/americas-recent-victors-start-strong-in-week-1", "news/article_720033.html", {}),
+]
+
 # ── Events ─────────────────────────────────────────────────────
 ROUTES += [
     ("/events", "events/events.html", {}),

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/src/vlrdevapi/__init__.py

@@ -1,8 +1,8 @@
 """vlrdevapi — A Python library to scrape data from vlr.gg.
 
 Provides a synchronous, typed interface for accessing match listings,
-event data, tournament info, team/player profiles, and statistics
-from vlr.gg.
+event data, tournament info, team/player profiles, statistics, and
+news from vlr.gg.
 
 Examples:
     Module-level access (using a default client):
@@ -23,17 +23,25 @@ Examples:
     >>> matches.matches[0].score
     '2-1'
 
+    News listing and articles:
+
+    >>> page = vlrdevapi.news(page=1)
+    >>> article = vlrdevapi.news.article(page.news[0].id)
+    >>> article.title != ''
+    True
+
 """
 
 import atexit as _atexit
+import contextlib
 from typing import TYPE_CHECKING
 
 from vlrdevapi._client import VLRClient
-import contextlib
 
 if TYPE_CHECKING:
     from vlrdevapi._event.namespace import EventNamespace
     from vlrdevapi._matches.namespace import MatchesNamespace
+    from vlrdevapi._news.namespace import NewsNamespace
     from vlrdevapi._player.namespace import PlayerNamespace
     from vlrdevapi._series.namespace import SeriesNamespace
     from vlrdevapi._team.namespace import TeamNamespace
@@ -43,22 +51,23 @@ if TYPE_CHECKING:
     player: PlayerNamespace
     team: TeamNamespace
     matches: MatchesNamespace
+    news: NewsNamespace
     client: type[VLRClient]
 
-__version__ = "2.2.0"
+__version__ = "2.3.0"
 
 _default_client: "VLRClient | None" = None
 
 
 def _get_default_client() -> "VLRClient":
-    global _default_client  # noqa: PLW0603
+    global _default_client
     if _default_client is None:
         _default_client = VLRClient()
     return _default_client
 
 
 def _cleanup_default_client() -> None:
-    global _default_client  # noqa: PLW0603
+    global _default_client
     if _default_client is not None:
         with contextlib.suppress(OSError):
             _default_client.close()
@@ -67,7 +76,7 @@ def _cleanup_default_client() -> None:
 
 _atexit.register(_cleanup_default_client)
 
-_BOUND_NAMES = frozenset({"event", "series", "player", "team", "matches"})
+_BOUND_NAMES = frozenset({"event", "series", "player", "team", "matches", "news"})
 
 
 def __getattr__(name: str) -> object:
@@ -89,6 +98,7 @@ __all__ = [
     "client",
     "event",
     "matches",
+    "news",
     "player",
     "series",
     "team",

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/src/vlrdevapi/__init__.pyi

@@ -1,6 +1,7 @@
 from vlrdevapi._client import VLRClient
 from vlrdevapi._event.namespace import EventNamespace
 from vlrdevapi._matches.namespace import MatchesNamespace
+from vlrdevapi._news.namespace import NewsNamespace
 from vlrdevapi._player.namespace import PlayerNamespace
 from vlrdevapi._series.namespace import SeriesNamespace
 from vlrdevapi._team.namespace import TeamNamespace
@@ -69,6 +70,20 @@ Examples:
     >>> completed = vlrdevapi.matches.completed()
 """
 
+news: NewsNamespace
+"""Access news from vlr.gg: news listings and full article content.
+
+Returns:
+    NewsNamespace instance bound to the default client. Call it with a
+    ``page`` number to browse the news listing, or use ``.article()`` to
+    fetch a single article (plain text and Markdown).
+
+Examples:
+    >>> page = vlrdevapi.news(page=1)
+    >>> article = vlrdevapi.news.article(734100)
+    >>> print(article.content_md)
+"""
+
 client: type[VLRClient]
 """Create an explicit VLRClient for connection management.
 

{vlrdevapi-2.2.0 → vlrdevapi-2.3.0}/src/vlrdevapi/_client.py

@@ -12,6 +12,7 @@ import httpx
 from vlrdevapi.commons.timezone import REFERENCE_MATCH_PATH, detect_vlr_timezone
 from vlrdevapi._event.namespace import EventNamespace
 from vlrdevapi._matches.namespace import MatchesNamespace
+from vlrdevapi._news.namespace import NewsNamespace
 from vlrdevapi._player.namespace import PlayerNamespace
 from vlrdevapi._series.namespace import SeriesNamespace
 from vlrdevapi._team.namespace import TeamNamespace
@@ -111,6 +112,7 @@ class VLRClient:
         self.matches = MatchesNamespace(self._client, self.timeout, self.retry_config, self._rate_limiter, merged_headers, self._source_tz)
         self.team = TeamNamespace(self._client, self.timeout, self.retry_config, self._rate_limiter, merged_headers, self._source_tz)
         self.event = EventNamespace(self._client, self.timeout, self.retry_config, self._rate_limiter, merged_headers, self._source_tz)
+        self.news = NewsNamespace(self._client, self.timeout, self.retry_config, self._rate_limiter, merged_headers, self._source_tz)
 
     def _detect_timezone(self) -> ZoneInfo | tzinfo | None:
         """Detect the viewer timezone VLR.gg renders for this client session."""

vlrdevapi-2.3.0/src/vlrdevapi/_news/__init__.py

@@ -0,0 +1,5 @@
+from vlrdevapi._news.article.models import NewsArticle
+from vlrdevapi._news.list.models import News, NewsPage
+from vlrdevapi._news.namespace import NewsNamespace
+
+__all__ = ["News", "NewsArticle", "NewsNamespace", "NewsPage"]

vlrdevapi-2.3.0/src/vlrdevapi/_news/article/__init__.py

@@ -0,0 +1,4 @@
+from vlrdevapi._news.article.models import NewsArticle
+from vlrdevapi._news.article.namespace import NewsArticleNamespace
+
+__all__ = ["NewsArticle", "NewsArticleNamespace"]

vlrdevapi-2.3.0/src/vlrdevapi/_news/article/models.py

@@ -0,0 +1,41 @@
+from datetime import datetime as datetime_
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class NewsArticle(BaseModel):
+    """A full news article from vlr.gg.
+
+    Attributes:
+        id: Unique identifier for the news article.
+        title: Title of the news article.
+        author: Author of the news article.
+        date: Publication date as a timezone-aware UTC datetime.
+        event_name: Event the article is associated with.
+        event_link: Link to the associated event page.
+        content: Full body text of the article as plain text.
+        content_md: Full body of the article converted to Markdown, with
+            headings, nested lists, tables, links, verbatim code, emphasis,
+            and Twitch clip embeds preserved.
+    """
+
+    model_config = ConfigDict(
+        json_schema_extra={"description": "A full news article from vlr.gg."}
+    )
+
+    id: int = Field(default=0, description="Unique identifier for the news article")
+    title: str = Field(default="", description="Title of the news article")
+    author: str = Field(default="", description="Author of the news article")
+    date: datetime_ | None = Field(
+        default=None, description="Publication date as a timezone-aware UTC datetime"
+    )
+    event_name: str = Field(
+        default="", description="Event the article is associated with"
+    )
+    event_link: str = Field(default="", description="Link to the associated event page")
+    content: str = Field(
+        default="", description="Full text content of the news article"
+    )
+    content_md: str = Field(
+        default="", description="Full content of the news article converted to Markdown"
+    )

vlrdevapi-2.3.0/src/vlrdevapi/_news/article/namespace.py

@@ -0,0 +1,86 @@
+"""News article namespace."""
+
+from datetime import tzinfo
+from zoneinfo import ZoneInfo
+
+import httpx
+
+from vlrdevapi._base import SyncNamespace
+from vlrdevapi._news.article.models import NewsArticle
+from vlrdevapi._news.article.parser import parse_news_article
+from vlrdevapi._utils.paths import news_article
+from vlrdevapi.exceptions import NotFoundError
+from vlrdevapi.fetcher import (
+    DEFAULT_RETRY_CONFIG,
+    DEFAULT_TIMEOUT,
+    RateLimiter,
+    RetryConfig,
+)
+from vlrdevapi.validators import sanitize_and_validate
+
+
+class NewsArticleNamespace:
+    """Access individual news articles from vlr.gg.
+
+    Call the instance with an article ID to fetch the full article::
+
+        article = vlrdevapi.news.article(734100)
+        print(article.title)
+
+    The namespace is reachable via ``vlrdevapi.news.article``. There is
+    no need to instantiate it directly.
+    """
+
+    __slots__ = ("_source_tz", "_sync")
+
+    def __init__(
+        self,
+        client: httpx.Client,
+        timeout: int = DEFAULT_TIMEOUT,
+        retry_config: RetryConfig = DEFAULT_RETRY_CONFIG,
+        rate_limiter: RateLimiter | None = None,
+        extra_headers: dict[str, str] | None = None,
+        source_tz: ZoneInfo | tzinfo | None = None,
+    ):
+        self._source_tz = source_tz
+        self._sync = SyncNamespace(
+            client, timeout, retry_config, rate_limiter, extra_headers
+        )
+
+    @sanitize_and_validate
+    def __call__(self, article_id: int) -> NewsArticle:
+        """Get a single news article from vlr.gg.
+
+        Args:
+            article_id: The news article ID. Use the ``id`` field of a
+                ``News`` item from a listing, or the numeric prefix of
+                its ``link``.
+
+        Returns:
+            NewsArticle: The article with ``title``, ``author``, ``date``,
+                ``event_name``, ``event_link``, ``content`` (plain text),
+                and ``content_md`` (Markdown).
+
+        Raises:
+            ValidationError: If ``article_id`` is not a valid positive integer.
+            NotFoundError: If the article does not exist. vlr.gg returns a
+                generic page (HTTP 200) for unknown article IDs, so this
+                is detected from the page content.
+            RequestError: If the HTTP request fails.
+            RateLimitError: If the rate limit is exceeded.
+
+        Examples:
+            >>> article = vlrdevapi.news.article(734100)
+            >>> article.title
+            'Gen.G, Global, VARREL, PRX bypass Pacific Stage 2 Play-Ins'
+            >>> article.content_md.startswith('The [Pacific Stage 2]')
+            True
+
+        """
+        html = self._sync._fetch(news_article(article_id))
+        article = parse_news_article(html, source_tz=self._source_tz)
+        if article.id == 0:
+            raise NotFoundError(
+                f"News article {article_id} not found (page contains no article content)."
+            )
+        return article

vlrdevapi-2.3.0/src/vlrdevapi/_news/article/namespace.pyi

@@ -0,0 +1,19 @@
+from datetime import tzinfo
+from zoneinfo import ZoneInfo
+
+import httpx
+
+from vlrdevapi._news.article.models import NewsArticle
+from vlrdevapi.fetcher import RateLimiter, RetryConfig
+
+class NewsArticleNamespace:
+    def __init__(
+        self,
+        client: httpx.Client,
+        timeout: int = ...,
+        retry_config: RetryConfig = ...,
+        rate_limiter: RateLimiter | None = None,
+        extra_headers: dict[str, str] | None = None,
+        source_tz: ZoneInfo | tzinfo | None = None,
+    ) -> None: ...
+    def __call__(self, article_id: int) -> NewsArticle: ...