feed-sentiment 0.1.0__py3-none-any.whl

feed_sentiment/__init__.py

@@ -0,0 +1,58 @@
+from feed_sentiment._metadata import package_version
+from feed_sentiment.exceptions import (
+    AnalysisError,
+    ContentTypeError,
+    FeedFormatError,
+    FeedSentimentError,
+    InputError,
+    ResponseSizeError,
+    RetrievalError,
+    UnsafeUrlError,
+)
+from feed_sentiment.feeds import FeedRetriever, RetrievalPolicy
+from feed_sentiment.models import (
+    AnalysisWarning,
+    AnalyzedEntry,
+    AnalyzerMetadata,
+    EntryAnalysisResult,
+    FeedAnalysisSnapshot,
+    FeedMetadata,
+    NormalizedFeedEntry,
+    SentimentLabel,
+    SentimentScore,
+    SnapshotAggregate,
+    WarningCode,
+    WeightingMethod,
+)
+from feed_sentiment.services import analyze_entries, analyze_feed, analyze_text
+
+__version__ = package_version()
+
+__all__ = [
+    "AnalysisError",
+    "AnalysisWarning",
+    "AnalyzerMetadata",
+    "AnalyzedEntry",
+    "ContentTypeError",
+    "EntryAnalysisResult",
+    "FeedAnalysisSnapshot",
+    "FeedFormatError",
+    "FeedMetadata",
+    "FeedRetriever",
+    "FeedSentimentError",
+    "InputError",
+    "NormalizedFeedEntry",
+    "ResponseSizeError",
+    "RetrievalError",
+    "RetrievalPolicy",
+    "SentimentLabel",
+    "SentimentScore",
+    "SnapshotAggregate",
+    "UnsafeUrlError",
+    "WarningCode",
+    "WeightingMethod",
+    "__version__",
+    "analyze_entries",
+    "analyze_feed",
+    "analyze_text",
+]

feed_sentiment/_metadata.py

@@ -0,0 +1,18 @@
+from importlib import metadata
+
+DISTRIBUTION_NAME = "feed-sentiment"
+PROJECT_URL = "https://github.com/kurtpatrickyu/feed-sentiment"
+UNKNOWN_VERSION = "0+unknown"
+
+
+def package_version() -> str:
+    """Return the installed distribution version or a source-tree fallback."""
+    try:
+        return metadata.version(DISTRIBUTION_NAME)
+    except metadata.PackageNotFoundError:
+        return UNKNOWN_VERSION
+
+
+def default_user_agent() -> str:
+    """Build the default HTTP User-Agent from installed package metadata."""
+    return f"{DISTRIBUTION_NAME}/{package_version()} (+{PROJECT_URL})"

feed_sentiment/analyzers/__init__.py

@@ -0,0 +1,4 @@
+from feed_sentiment.analyzers.base import SentimentAnalyzer, label_for
+from feed_sentiment.analyzers.vader import VaderAnalyzer
+
+__all__ = ["SentimentAnalyzer", "VaderAnalyzer", "label_for"]

feed_sentiment/analyzers/base.py

@@ -0,0 +1,15 @@
+from typing import Protocol
+
+from feed_sentiment.models import SentimentLabel, SentimentScore
+
+
+class SentimentAnalyzer(Protocol):
+    def analyze(self, text: str) -> SentimentScore: ...
+
+
+def label_for(compound: float) -> SentimentLabel:
+    if compound >= 0.05:
+        return SentimentLabel.POSITIVE
+    if compound <= -0.05:
+        return SentimentLabel.NEGATIVE
+    return SentimentLabel.NEUTRAL

feed_sentiment/analyzers/vader.py

@@ -0,0 +1,31 @@
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any
+
+from vaderSentiment.vaderSentiment import SentimentIntensityAnalyzer  # type: ignore[import-untyped]
+
+from feed_sentiment.analyzers.base import label_for
+from feed_sentiment.models import AnalyzerMetadata, SentimentScore
+
+
+def vader_version() -> str | None:
+    try:
+        return version("vaderSentiment")
+    except PackageNotFoundError:
+        return None
+
+
+class VaderAnalyzer:
+    def __init__(self, engine: Any | None = None) -> None:
+        self._engine = engine or SentimentIntensityAnalyzer()
+
+    def analyze(self, text: str) -> SentimentScore:
+        raw = self._engine.polarity_scores(text)
+        compound = float(raw["compound"])
+        return SentimentScore(
+            negative=float(raw["neg"]),
+            neutral=float(raw["neu"]),
+            positive=float(raw["pos"]),
+            compound=compound,
+            label=label_for(compound),
+            analyzer=AnalyzerMetadata("vaderSentiment", vader_version()),
+        )

feed_sentiment/cli/__init__.py

@@ -0,0 +1,3 @@
+from feed_sentiment.cli.app import app
+
+__all__ = ["app"]

feed_sentiment/cli/app.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import json
+from enum import StrEnum
+from typing import Annotated
+
+import typer
+
+from feed_sentiment import RetrievalPolicy, __version__, analyze_feed
+from feed_sentiment.exceptions import FeedSentimentError
+from feed_sentiment.models import FeedAnalysisSnapshot
+
+app = typer.Typer(
+    no_args_is_help=True, add_completion=False, help="Analyze RSS and Atom sentiment snapshots."
+)
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+
+
+def _version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version", callback=_version, is_eager=True, help="Show the installed version."
+        ),
+    ] = False,
+) -> None:
+    """Analyze RSS and Atom sentiment snapshots."""
+
+
+def render_text(snapshot: FeedAnalysisSnapshot) -> str:
+    lines = [f"Feed: {snapshot.feed.title or snapshot.source_url}"]
+    for item in snapshot.entries:
+        name = item.entry.title or item.entry.identity
+        lines.append(f"- {name}: {item.sentiment.label} ({item.sentiment.compound:.4f})")
+    aggregate = snapshot.snapshot_aggregate
+    if aggregate is None:
+        lines.append("Snapshot aggregate: none (no successfully analyzed entries)")
+    else:
+        lines.append(
+            f"Snapshot aggregate: {aggregate.label} ({aggregate.compound:.4f}); "
+            f"included={aggregate.included_count}, skipped={aggregate.skipped_count}, "
+            f"weighting={aggregate.weighting}"
+        )
+    for warning in snapshot.warnings:
+        lines.append(f"Warning [{warning.code}]: {warning.message}")
+    return "\n".join(lines)
+
+
+@app.command()
+def analyze(
+    feed_url: Annotated[str, typer.Argument(help="HTTP(S) RSS or Atom URL.")],
+    output_format: Annotated[
+        OutputFormat, typer.Option("--format", case_sensitive=False)
+    ] = OutputFormat.TEXT,
+    allow_private_network: Annotated[
+        bool,
+        typer.Option(
+            "--allow-private-network",
+            help="Explicitly allow trusted private-network feed destinations.",
+        ),
+    ] = False,
+) -> None:
+    """Analyze one feed snapshot."""
+    try:
+        if allow_private_network:
+            snapshot = analyze_feed(
+                feed_url,
+                retrieval_policy=RetrievalPolicy(allow_private_networks=True),
+            )
+        else:
+            snapshot = analyze_feed(feed_url)
+    except FeedSentimentError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1) from exc
+    if output_format is OutputFormat.JSON:
+        typer.echo(json.dumps(snapshot.to_dict(), ensure_ascii=True))
+    else:
+        typer.echo(render_text(snapshot))
+
+
+if __name__ == "__main__":
+    app()

feed_sentiment/exceptions/__init__.py

@@ -0,0 +1,34 @@
+class FeedSentimentError(Exception):
+    """Base exception for expected package failures."""
+
+
+class InputError(FeedSentimentError, ValueError):
+    """Raised when caller input cannot be analyzed."""
+
+
+class AnalysisError(FeedSentimentError):
+    """Raised when a sentiment analyzer fails."""
+
+
+class RetrievalError(FeedSentimentError):
+    """Raised when a feed cannot be retrieved."""
+
+    def __init__(self, url: str, message: str) -> None:
+        self.url = url
+        super().__init__(f"{message}: {url}")
+
+
+class UnsafeUrlError(RetrievalError):
+    """Raised when URL policy rejects a destination."""
+
+
+class ResponseSizeError(RetrievalError):
+    """Raised when a response exceeds its byte limit."""
+
+
+class ContentTypeError(RetrievalError):
+    """Raised for a clearly incompatible response media type."""
+
+
+class FeedFormatError(FeedSentimentError):
+    """Raised when content is not a recognizable RSS or Atom document."""

feed_sentiment/feeds/__init__.py

@@ -0,0 +1,19 @@
+from feed_sentiment.feeds.parser import construct_analysis_text, html_to_text, parse_feed
+from feed_sentiment.feeds.retriever import (
+    FeedRetriever,
+    HttpxFeedRetriever,
+    RetrievalPolicy,
+    RetrievedFeed,
+    validate_url,
+)
+
+__all__ = [
+    "FeedRetriever",
+    "HttpxFeedRetriever",
+    "RetrievedFeed",
+    "RetrievalPolicy",
+    "construct_analysis_text",
+    "html_to_text",
+    "parse_feed",
+    "validate_url",
+]

feed_sentiment/feeds/parser.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import hashlib
+from datetime import UTC, datetime
+from time import struct_time
+from typing import Any
+
+import feedparser  # type: ignore[import-untyped]
+from bs4 import BeautifulSoup
+
+from feed_sentiment.exceptions import FeedFormatError
+from feed_sentiment.models import (
+    AnalysisWarning,
+    FeedMetadata,
+    NormalizedFeedEntry,
+    ParsedFeed,
+    WarningCode,
+)
+
+
+def _clean(value: Any) -> str | None:
+    if value is None:
+        return None
+    cleaned = " ".join(str(value).split())
+    return cleaned or None
+
+
+def html_to_text(value: Any) -> str | None:
+    if value is None:
+        return None
+    soup = BeautifulSoup(str(value), "html.parser")
+    for element in soup(["script", "style"]):
+        element.decompose()
+    return _clean(soup.get_text(" "))
+
+
+def construct_analysis_text(title: str | None, summary: str | None) -> str:
+    return "\n".join(part for part in (title, summary) if part)
+
+
+def _timestamp(entry: Any) -> tuple[datetime | None, bool]:
+    value: struct_time | None = entry.get("published_parsed") or entry.get("updated_parsed")
+    if value is None:
+        raw_present = bool(entry.get("published") or entry.get("updated"))
+        return None, raw_present
+    try:
+        return datetime(*value[:6], tzinfo=UTC), False
+    except (TypeError, ValueError, OverflowError):
+        return None, True
+
+
+def _identity(
+    entry_id: str | None,
+    url: str | None,
+    title: str | None,
+    summary: str | None,
+    published_at: datetime | None,
+) -> str:
+    if entry_id:
+        return f"id:{entry_id}"
+    if url:
+        return f"url:{url}"
+    payload = "\x1f".join(
+        (title or "", summary or "", published_at.isoformat() if published_at else "")
+    )
+    return f"sha256:{hashlib.sha256(payload.encode('utf-8')).hexdigest()}"
+
+
+def parse_feed(content: bytes) -> ParsedFeed:
+    parsed = feedparser.parse(content)
+    if not parsed.get("version") or parsed.get("bozo"):
+        detail = str(parsed.get("bozo_exception", "unrecognized RSS or Atom document"))
+        raise FeedFormatError(f"Malformed feed document: {detail}")
+
+    warnings: list[AnalysisWarning] = []
+    normalized: list[NormalizedFeedEntry] = []
+    seen: set[str] = set()
+    raw_entries = parsed.get("entries", ())
+    for index, raw in enumerate(raw_entries):
+        entry_id = _clean(raw.get("id") or raw.get("guid"))
+        url = _clean(raw.get("link"))
+        title = _clean(raw.get("title"))
+        summary_source = raw.get("summary")
+        if summary_source is None and raw.get("content"):
+            summary_source = raw["content"][0].get("value")
+        summary = html_to_text(summary_source)
+        published_at, invalid_date = _timestamp(raw)
+        identity = _identity(entry_id, url, title, summary, published_at)
+        if invalid_date:
+            warnings.append(
+                AnalysisWarning(
+                    WarningCode.INVALID_METADATA,
+                    "Invalid publication date was omitted",
+                    identity,
+                    index,
+                )
+            )
+        text = construct_analysis_text(title, summary)
+        if not text:
+            warnings.append(
+                AnalysisWarning(
+                    WarningCode.NO_USABLE_TEXT,
+                    "Entry has no usable title or summary",
+                    identity,
+                    index,
+                )
+            )
+            continue
+        if identity in seen:
+            warnings.append(
+                AnalysisWarning(
+                    WarningCode.DUPLICATE_ENTRY, "Duplicate entry was skipped", identity, index
+                )
+            )
+            continue
+        seen.add(identity)
+        normalized.append(
+            NormalizedFeedEntry(identity, entry_id, url, title, summary, published_at, text)
+        )
+
+    if not raw_entries:
+        warnings.append(AnalysisWarning(WarningCode.EMPTY_FEED, "Feed contains no entries"))
+    feed = parsed.get("feed", {})
+    metadata = FeedMetadata(_clean(feed.get("title")), _clean(feed.get("link")))
+    return ParsedFeed(metadata, tuple(normalized), tuple(warnings), len(raw_entries))

feed_sentiment/feeds/retriever.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+from dataclasses import dataclass, field
+from typing import Protocol
+from urllib.parse import urljoin, urlsplit
+
+import httpx
+
+from feed_sentiment._metadata import default_user_agent
+from feed_sentiment.exceptions import (
+    ContentTypeError,
+    ResponseSizeError,
+    RetrievalError,
+    UnsafeUrlError,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievalPolicy:
+    connect_timeout: float = 5.0
+    read_timeout: float = 15.0
+    max_redirects: int = 5
+    max_response_bytes: int = 5 * 1024 * 1024
+    allow_private_networks: bool = False
+    user_agent: str = field(default_factory=default_user_agent)
+
+
+@dataclass(frozen=True, slots=True)
+class RetrievedFeed:
+    url: str
+    content: bytes
+    content_type: str | None
+
+
+class FeedRetriever(Protocol):
+    def fetch(self, url: str, policy: RetrievalPolicy) -> RetrievedFeed: ...
+
+
+def _blocked(address: ipaddress.IPv4Address | ipaddress.IPv6Address) -> bool:
+    return any(
+        (
+            address.is_private,
+            address.is_loopback,
+            address.is_link_local,
+            address.is_multicast,
+            address.is_unspecified,
+            address.is_reserved,
+        )
+    )
+
+
+def validate_url(url: str, policy: RetrievalPolicy) -> None:
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"}:
+        raise UnsafeUrlError(url, "Only HTTP and HTTPS feed URLs are allowed")
+    if not parsed.hostname or parsed.username is not None or parsed.password is not None:
+        raise UnsafeUrlError(url, "Feed URL must have a host and no embedded credentials")
+    if policy.allow_private_networks:
+        return
+    try:
+        infos = socket.getaddrinfo(parsed.hostname, parsed.port, type=socket.SOCK_STREAM)
+    except OSError as exc:
+        raise RetrievalError(url, f"Could not resolve feed host ({exc})") from exc
+    for info in infos:
+        address = ipaddress.ip_address(info[4][0])
+        if _blocked(address):
+            raise UnsafeUrlError(url, f"Feed URL resolves to blocked address {address}")
+
+
+_ACCEPTED_TYPES = {
+    "application/atom+xml",
+    "application/rss+xml",
+    "application/xml",
+    "text/xml",
+    "application/octet-stream",
+    "binary/octet-stream",
+}
+
+
+class HttpxFeedRetriever:
+    def fetch(self, url: str, policy: RetrievalPolicy) -> RetrievedFeed:
+        current = url
+        timeout = httpx.Timeout(policy.read_timeout, connect=policy.connect_timeout)
+        try:
+            with httpx.Client(
+                follow_redirects=False, timeout=timeout, headers={"User-Agent": policy.user_agent}
+            ) as client:
+                for redirect_count in range(policy.max_redirects + 1):
+                    validate_url(current, policy)
+                    with client.stream("GET", current) as response:
+                        if response.is_redirect:
+                            location = response.headers.get("location")
+                            if not location or redirect_count >= policy.max_redirects:
+                                raise RetrievalError(
+                                    current, "Feed redirect limit exceeded or target missing"
+                                )
+                            current = urljoin(current, location)
+                            continue
+                        response.raise_for_status()
+                        media_type = (
+                            response.headers.get("content-type", "")
+                            .split(";", 1)[0]
+                            .strip()
+                            .lower()
+                        )
+                        if (
+                            media_type
+                            and media_type not in _ACCEPTED_TYPES
+                            and not media_type.endswith("+xml")
+                        ):
+                            raise ContentTypeError(
+                                current, f"Unsupported feed content type {media_type}"
+                            )
+                        chunks: list[bytes] = []
+                        size = 0
+                        for chunk in response.iter_bytes():
+                            size += len(chunk)
+                            if size > policy.max_response_bytes:
+                                raise ResponseSizeError(
+                                    current,
+                                    f"Feed response exceeds {policy.max_response_bytes} bytes",
+                                )
+                            chunks.append(chunk)
+                        return RetrievedFeed(
+                            str(response.url), b"".join(chunks), media_type or None
+                        )
+        except RetrievalError:
+            raise
+        except httpx.TimeoutException as exc:
+            raise RetrievalError(current, "Feed retrieval timed out") from exc
+        except httpx.HTTPError as exc:
+            raise RetrievalError(current, f"Feed retrieval failed ({exc})") from exc
+        raise RetrievalError(current, "Feed redirect handling failed")

feed_sentiment/models.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from enum import StrEnum
+from typing import Any, cast
+
+
+class SentimentLabel(StrEnum):
+    NEGATIVE = "negative"
+    NEUTRAL = "neutral"
+    POSITIVE = "positive"
+
+
+class WarningCode(StrEnum):
+    EMPTY_FEED = "empty_feed"
+    NO_USABLE_TEXT = "no_usable_text"
+    DUPLICATE_ENTRY = "duplicate_entry"
+    INVALID_METADATA = "invalid_metadata"
+    ANALYSIS_FAILED = "analysis_failed"
+
+
+class WeightingMethod(StrEnum):
+    EQUAL_ENTRY = "equal_entry"
+
+
+class Serializable:
+    def to_dict(self) -> dict[str, Any]:
+        return cast(dict[str, Any], _json_value(asdict(cast(Any, self))))
+
+
+def _json_value(value: Any) -> Any:
+    if isinstance(value, datetime):
+        return value.isoformat()
+    if isinstance(value, StrEnum):
+        return value.value
+    if isinstance(value, dict):
+        return {key: _json_value(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_json_value(item) for item in value]
+    return value
+
+
+@dataclass(frozen=True, slots=True)
+class AnalyzerMetadata(Serializable):
+    name: str
+    version: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class SentimentScore(Serializable):
+    negative: float
+    neutral: float
+    positive: float
+    compound: float
+    label: SentimentLabel
+    analyzer: AnalyzerMetadata
+
+    def __post_init__(self) -> None:
+        for name in ("negative", "neutral", "positive"):
+            if not 0.0 <= getattr(self, name) <= 1.0:
+                raise ValueError(f"{name} must be between 0 and 1")
+        if not -1.0 <= self.compound <= 1.0:
+            raise ValueError("compound must be between -1 and 1")
+
+
+@dataclass(frozen=True, slots=True)
+class NormalizedFeedEntry(Serializable):
+    identity: str
+    entry_id: str | None
+    url: str | None
+    title: str | None
+    summary: str | None
+    published_at: datetime | None
+    analysis_text: str
+
+
+@dataclass(frozen=True, slots=True)
+class AnalyzedEntry(Serializable):
+    entry: NormalizedFeedEntry
+    sentiment: SentimentScore
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisWarning(Serializable):
+    code: WarningCode
+    message: str
+    entry_identity: str | None = None
+    entry_index: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class EntryAnalysisResult(Serializable):
+    entries: tuple[AnalyzedEntry, ...]
+    warnings: tuple[AnalysisWarning, ...]
+    skipped_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class SnapshotAggregate(Serializable):
+    negative: float
+    neutral: float
+    positive: float
+    compound: float
+    label: SentimentLabel
+    included_count: int
+    skipped_count: int
+    weighting: WeightingMethod = WeightingMethod.EQUAL_ENTRY
+
+
+@dataclass(frozen=True, slots=True)
+class FeedMetadata(Serializable):
+    title: str | None = None
+    url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class ParsedFeed(Serializable):
+    metadata: FeedMetadata
+    entries: tuple[NormalizedFeedEntry, ...]
+    warnings: tuple[AnalysisWarning, ...]
+    source_entry_count: int
+
+
+@dataclass(frozen=True, slots=True)
+class FeedAnalysisSnapshot(Serializable):
+    source_url: str
+    feed: FeedMetadata
+    entries: tuple[AnalyzedEntry, ...]
+    warnings: tuple[AnalysisWarning, ...]
+    snapshot_aggregate: SnapshotAggregate | None

feed_sentiment/services/__init__.py

@@ -0,0 +1,8 @@
+from feed_sentiment.services.analysis import (
+    aggregate_entries,
+    analyze_entries,
+    analyze_feed,
+    analyze_text,
+)
+
+__all__ = ["aggregate_entries", "analyze_entries", "analyze_feed", "analyze_text"]

feed_sentiment/services/analysis.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from feed_sentiment.analyzers import SentimentAnalyzer, VaderAnalyzer, label_for
+from feed_sentiment.exceptions import AnalysisError, InputError
+from feed_sentiment.feeds import FeedRetriever, HttpxFeedRetriever, RetrievalPolicy, parse_feed
+from feed_sentiment.models import (
+    AnalysisWarning,
+    AnalyzedEntry,
+    EntryAnalysisResult,
+    FeedAnalysisSnapshot,
+    NormalizedFeedEntry,
+    SentimentScore,
+    SnapshotAggregate,
+    WarningCode,
+)
+
+
+def _analyzer(selected: SentimentAnalyzer | None) -> SentimentAnalyzer:
+    return selected if selected is not None else VaderAnalyzer()
+
+
+def analyze_text(text: str, *, analyzer: SentimentAnalyzer | None = None) -> SentimentScore:
+    cleaned = text.strip()
+    if not cleaned:
+        raise InputError("Text must contain non-whitespace characters")
+    try:
+        return _analyzer(analyzer).analyze(cleaned)
+    except AnalysisError:
+        raise
+    except Exception as exc:
+        raise AnalysisError("Sentiment analyzer failed") from exc
+
+
+def analyze_entries(
+    entries: Iterable[NormalizedFeedEntry],
+    *,
+    analyzer: SentimentAnalyzer | None = None,
+) -> EntryAnalysisResult:
+    selected = _analyzer(analyzer)
+    analyzed: list[AnalyzedEntry] = []
+    warnings: list[AnalysisWarning] = []
+    skipped = 0
+    for index, entry in enumerate(entries):
+        if not entry.analysis_text.strip():
+            skipped += 1
+            warnings.append(
+                AnalysisWarning(
+                    WarningCode.NO_USABLE_TEXT,
+                    "Entry has no usable analysis text",
+                    entry.identity,
+                    index,
+                )
+            )
+            continue
+        try:
+            analyzed.append(AnalyzedEntry(entry, selected.analyze(entry.analysis_text)))
+        except Exception:
+            skipped += 1
+            warnings.append(
+                AnalysisWarning(
+                    WarningCode.ANALYSIS_FAILED,
+                    "Sentiment analysis failed for entry",
+                    entry.identity,
+                    index,
+                )
+            )
+    return EntryAnalysisResult(tuple(analyzed), tuple(warnings), skipped)
+
+
+def aggregate_entries(
+    entries: tuple[AnalyzedEntry, ...], skipped_count: int
+) -> SnapshotAggregate | None:
+    if not entries:
+        return None
+    count = len(entries)
+    negative = sum(item.sentiment.negative for item in entries) / count
+    neutral = sum(item.sentiment.neutral for item in entries) / count
+    positive = sum(item.sentiment.positive for item in entries) / count
+    compound = sum(item.sentiment.compound for item in entries) / count
+    return SnapshotAggregate(
+        negative, neutral, positive, compound, label_for(compound), count, skipped_count
+    )
+
+
+def analyze_feed(
+    url: str,
+    *,
+    analyzer: SentimentAnalyzer | None = None,
+    retriever: FeedRetriever | None = None,
+    retrieval_policy: RetrievalPolicy | None = None,
+) -> FeedAnalysisSnapshot:
+    policy = retrieval_policy or RetrievalPolicy()
+    fetched = (retriever or HttpxFeedRetriever()).fetch(url, policy)
+    parsed = parse_feed(fetched.content)
+    result = analyze_entries(parsed.entries, analyzer=analyzer)
+    warnings = parsed.warnings + result.warnings
+    skipped = parsed.source_entry_count - len(result.entries)
+    return FeedAnalysisSnapshot(
+        source_url=url,
+        feed=parsed.metadata,
+        entries=result.entries,
+        warnings=warnings,
+        snapshot_aggregate=aggregate_entries(result.entries, skipped),
+    )

feed_sentiment-0.1.0.dist-info/METADATA

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: feed-sentiment
+Version: 0.1.0
+Summary: Typed sentiment analysis for RSS and Atom feed snapshots
+Project-URL: Homepage, https://github.com/kurtpatrickyu/feed-sentiment
+Project-URL: Repository, https://github.com/kurtpatrickyu/feed-sentiment
+Project-URL: Issues, https://github.com/kurtpatrickyu/feed-sentiment/issues
+Project-URL: Changelog, https://github.com/kurtpatrickyu/feed-sentiment/releases
+Author: Kurt Patrick Yu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: atom,feed,news-analysis,nlp,rss,sentiment-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content :: News/Diary
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Requires-Python: >=3.12
+Requires-Dist: beautifulsoup4<5,>=4.13
+Requires-Dist: feedparser<7,>=6.0.11
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: typer<1,>=0.16
+Requires-Dist: vadersentiment<4,>=3.3.2
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2,>=1.16; extra == 'dev'
+Requires-Dist: pytest-httpx<1,>=0.35; extra == 'dev'
+Requires-Dist: pytest<9,>=8.4; extra == 'dev'
+Requires-Dist: ruff<1,>=0.12; extra == 'dev'
+Requires-Dist: twine<7,>=6.2; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Feed Sentiment
+
+Feed Sentiment is an MIT-licensed Python 3.12+ package for one-shot sentiment analysis of RSS and Atom feed snapshots. It normalizes entries, scores each usable entry with VADER, and returns an explicitly defined snapshot aggregate.
+
+## Installation
+
+```console
+python -m pip install feed-sentiment
+```
+
+Runtime dependencies have narrow roles: `httpx` performs bounded HTTP retrieval, `feedparser` interprets RSS and Atom, `beautifulsoup4` converts summary HTML to deterministic plain text, `vaderSentiment` supplies the default lexical analyzer, and `typer` provides the CLI. The `dev` extra adds pytest, pytest-httpx, Ruff, mypy, and build tooling.
+
+## Python API
+
+```python
+from feed_sentiment import analyze_feed, analyze_text
+
+text_score = analyze_text("This release is excellent!")
+snapshot = analyze_feed("https://example.com/feed.xml")
+
+for item in snapshot.entries:
+    print(item.entry.title, item.sentiment.label, item.sentiment.compound)
+
+print(snapshot.snapshot_aggregate)
+```
+
+`analyze_entries(entries, *, analyzer=None)` analyzes already normalized entries. All public operations return package-owned typed dataclasses; analyzer and parser implementation objects do not leak through the API. A custom analyzer can implement the public `SentimentAnalyzer` protocol.
+
+## CLI
+
+```console
+feed-sentiment analyze https://example.com/feed.xml
+feed-sentiment analyze https://example.com/feed.xml --format json
+feed-sentiment analyze http://intranet/feed.xml --allow-private-network
+feed-sentiment --version
+```
+
+Normal results are written to stdout. Expected errors are concise, go to stderr, and exit 1; CLI usage errors exit 2. JSON mode emits exactly one undecorated JSON document.
+
+## Score semantics
+
+Each entry contains VADER `negative`, `neutral`, and `positive` proportions in `[0, 1]` plus `compound` in `[-1, 1]`. Compound scores `>= 0.05` are positive, scores `<= -0.05` are negative, and values between those thresholds are neutral. Analyzer name and installed version (when discoverable) accompany each score. Empty text is an input error rather than an artificial neutral result.
+
+Entry analysis text is `title + "\n" + plain_text_summary` when both fields exist, or the sole usable field otherwise. HTML tags and script/style content are removed, entities decoded, whitespace collapsed, and Unicode preserved. Entries with no usable text are skipped with structured warnings.
+
+## Snapshot aggregation
+
+`snapshot.snapshot_aggregate` includes exactly the entries successfully analyzed in the current retrieval. Every included entry has equal weight. Negative, neutral, positive, and compound are component-wise arithmetic means calculated without intermediate rounding; the aggregate label uses the same compound thresholds. The result records included and skipped counts plus `equal_entry` weighting. If no entry succeeds, the aggregate is `None`/JSON `null`, and warnings explain empty, skipped, duplicate, or failed entries.
+
+Within one snapshot, duplicate identity prefers entry ID, then canonical entry URL, then a SHA-256 fingerprint of normalized title, summary, and publication timestamp. This fallback is not a persistent monitoring identity contract.
+
+## Retrieval and security boundary
+
+Retrieval accepts only HTTP(S), uses finite connect/read timeouts, a redirect cap, a response-size limit, explicit media-type checks, and no automatic retries. The default policy rejects embedded credentials and destinations resolving to private, loopback, link-local, multicast, unspecified, or reserved addresses, including redirect targets. Trusted applications may explicitly enable private-network feeds with `RetrievalPolicy(allow_private_networks=True)`.
+
+These checks are defense in depth for a reusable client, not a complete hosted-service SSRF sandbox. A service accepting untrusted URLs still needs network egress controls and DNS-rebinding defenses. Importing the package never performs network access.
+
+## Known limitations
+
+- This release analyzes one snapshot only; it has no subscriptions, persistence, `poll_once()`, history, rolling windows, or watch loop.
+- VADER is lexical and English-oriented; it can miss domain context, irony, and nuanced language.
+- Full article pages are not fetched. Only feed titles and summaries/content are analyzed.
+- Malformed XML is rejected at document level. Recoverable missing or invalid entry metadata is represented by structured warnings.
+
+## Development
+
+```console
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m ruff check .
+python -m mypy
+python -m build
+python -m twine check --strict dist/*
+```
+
+Tests use local fixtures and controlled HTTP doubles; the normal suite does not require live public feeds.
+
+The `Quality Gates` GitHub Actions workflow runs pytest on Python 3.12, 3.13, and 3.14, then runs Ruff and mypy before validating clean wheel and source-distribution installations. CI retains seven-day diagnostic artifacts named `test-results-python-<version>`, `static-check-results`, and `package-validation-results`. Successfully validated wheel and source-distribution files are uploaded separately as `python-package-distributions` for a future publishing workflow; generated `dist/` files remain local/CI artifacts and are not committed to Git.
+
+Production publishing setup and the maintainer release procedure are documented in [docs/releasing.md](docs/releasing.md).

feed_sentiment-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+feed_sentiment/__init__.py,sha256=36E7WrtUCoVgUPmqboiZmAdgEv4SmYL2xcmbHcYypyE,1335
+feed_sentiment/_metadata.py,sha256=aXjq5S3L782MH41-KqXqKRDrGeZpMkH9Csq8aVOSf9c,590
+feed_sentiment/models.py,sha256=8AmqeHiS7wJYow1PKk0QA9EbZbwxo5pyqeNnjPBgQYU,3361
+feed_sentiment/analyzers/__init__.py,sha256=7lSmCoyokuVrHd32yULkuyc4NjRcYXU9fwu9KC_SnXM,191
+feed_sentiment/analyzers/base.py,sha256=9-0Xivu0eaToytA-dOzSKaCSzfFnU9zuPfk33iJdBk4,402
+feed_sentiment/analyzers/vader.py,sha256=0M4bjJvgBPirbjSpVv8EUCyWghN8ciA2p0zWAWdZsjI,1038
+feed_sentiment/cli/__init__.py,sha256=fRqUYl-OUx8NkFLMf9671zR4H0Zc5ph1eDLk5MorjNQ,58
+feed_sentiment/cli/app.py,sha256=gtyCu9IISpBk_6RflPk5B2BwAvxNkz8KcGDIVeUUIgo,2805
+feed_sentiment/exceptions/__init__.py,sha256=3ntYaI4QHGSO7PgATGBcnEaOfQwEVgkE9QOkr_UgK7s,935
+feed_sentiment/feeds/__init__.py,sha256=HubpPmDgec8QxsgAcCERY63MFRSJMV25JVRpbeybauQ,433
+feed_sentiment/feeds/parser.py,sha256=5guTjOEDT_LbkIrWgMR3ahR59UKZ9DQKLGy5bHdawaY,4160
+feed_sentiment/feeds/retriever.py,sha256=VQxPnUzGPWuCsHCe-AffeEt5PBxLut_PGMAvQzf4BP8,5081
+feed_sentiment/services/__init__.py,sha256=rv9rYjfIe7X1wyy2i8Dygwuj-CD7GNBSUNBowdQQ90E,213
+feed_sentiment/services/analysis.py,sha256=K6o9_3rccUpfZxNnY7STa2w1LK-EXh-kM67aQnpP-IU,3606
+feed_sentiment-0.1.0.dist-info/METADATA,sha256=3XjklHdxVhPhd35uuXujZNrv79QhJX0EEKiUP-d1fF8,7014
+feed_sentiment-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+feed_sentiment-0.1.0.dist-info/entry_points.txt,sha256=oz3XW9g2PiA1iHwtUGAgvtONV9fdBOqQL4U1bGEK-lo,62
+feed_sentiment-0.1.0.dist-info/licenses/LICENSE,sha256=FPoTe9ec8eUoYt01Su1ckgs34jBJAcuUMkzSocyqVyQ,1070
+feed_sentiment-0.1.0.dist-info/RECORD,,

feed_sentiment-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

feed_sentiment-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+feed-sentiment = feed_sentiment.cli.app:app

feed_sentiment-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kurtpatrickyu
+
+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.