mdfetch 0.9.4__tar.gz → 0.9.6__tar.gz

{mdfetch-0.9.4 → mdfetch-0.9.6}/.github/scripts/generate_resources.py

@@ -1,20 +1,39 @@
-import sys
+import argparse
 import json
+import sys
 import urllib.request
 
-def generate():
+from packaging.markers import Marker, default_environment
+
+
+def target_environment(python_version):
+    """Marker environment of the Homebrew install: macOS with the formula's Python."""
+    env = default_environment()
+    env.update(
+        python_version=python_version,
+        python_full_version=f"{python_version}.0",
+        sys_platform="darwin",
+        platform_system="Darwin",
+        os_name="posix",
+    )
+    return env
+
+
+def generate(python_version):
+    env = target_environment(python_version)
+    seen = {}
     for line in sys.stdin:
         line = line.strip()
         # Skip empty lines, comments, and local editable installs
         if not line or line.startswith('#') or line.startswith('-e'):
             continue
             
-        # Very basic environment marker filtering to skip Windows/Linux specific packages
+        # Keep only requirements whose environment marker holds for the Homebrew
+        # install. A lock resolved for several Python versions lists some
+        # packages once per version range, e.g. anyio for < 3.15 and >= 3.15.
         if ';' in line:
             req, marker = line.split(';', 1)
-            # Remove whitespace and quotes for simple matching
-            marker_clean = marker.replace(' ', '').replace('"', '').replace("'", "")
-            if 'sys_platform==win32' in marker_clean or 'sys_platform==linux' in marker_clean:
+            if not Marker(marker.strip()).evaluate(env):
                 continue
             line = req.strip()
         
@@ -29,6 +48,16 @@ def generate():
         # We don't need a resource block for mdfetch itself
         if pkg == "mdfetch":
             continue
+
+        # Homebrew keeps only the first resource of a given name, so a second
+        # one would be dropped silently. Fail instead of guessing.
+        if pkg in seen:
+            print(
+                f"ERROR: {pkg} is pinned twice ({seen[pkg]} and {ver}) for Python {python_version}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        seen[pkg] = ver
             
         url = f"https://pypi.org/pypi/{pkg}/{ver}/json"
         try:
@@ -56,4 +85,8 @@ def generate():
         print(f'  end\n')
 
 if __name__ == "__main__":
-    generate()
+    parser = argparse.ArgumentParser(
+        description="Generate Homebrew resource blocks from `uv export` output on stdin."
+    )
+    parser.add_argument("--python", required=True, help="Python version of the formula, e.g. 3.13")
+    generate(parser.parse_args().python)

{mdfetch-0.9.4 → mdfetch-0.9.6}/.github/workflows/ci.yml

@@ -14,12 +14,12 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
       - name: Set up Python
-        run: uv python pin 3.12
+        run: uv python pin 3.14
       - name: Install dependencies
         run: uv sync --frozen --all-extras
       - name: Check formatting
@@ -38,7 +38,7 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"

{mdfetch-0.9.4 → mdfetch-0.9.6}/.github/workflows/integration.yml

@@ -17,13 +17,13 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         with:
           enable-cache: true
           cache-dependency-glob: "uv.lock"
 
       - name: Set up Python
-        run: uv python pin 3.12
+        run: uv python pin 3.14
 
       - name: Install dependencies
         run: uv sync --frozen --all-extras

{mdfetch-0.9.4 → mdfetch-0.9.6}/.github/workflows/publish.yml

@@ -15,9 +15,9 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
       - name: Set up Python
-        run: uv python pin 3.12
+        run: uv python pin 3.14
       - name: Validate version
         run: |
           TAG_VERSION=${GITHUB_REF_NAME#v}
@@ -29,7 +29,7 @@ jobs:
       - name: Build package
         run: make build
       - name: Store the distribution packages
-        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         with:
           name: python-package-distributions
           path: dist/
@@ -45,12 +45,12 @@ jobs:
       id-token: write
     steps:
       - name: Download all the dists
-        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
         with:
           name: python-package-distributions
           path: dist/
       - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
         with:
           packages-dir: dist/
 
@@ -68,11 +68,13 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       
       - name: Install uv
-        uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
         
       - name: Set up Python
-        run: uv python pin 3.12
-        
+        # Matches `depends_on "python@3.13"` in Formula/md-fetch.rb and the
+        # --python 3.13 flag below, not the 3.14 used by the other jobs.
+        run: uv python pin 3.13
+
       - name: Fetch sdist info from PyPI (with retry)
         env:
           VERSION: ${{ github.ref_name }}
@@ -104,7 +106,11 @@ jobs:
 
       - name: Generate PyPI resource blocks
         run: |
-          uv export --no-dev --no-hashes --format requirements-txt | python3 .github/scripts/generate_resources.py > /tmp/resources.rb
+          # --python must match `depends_on "python@X.Y"` in Formula/md-fetch.rb,
+          # so environment markers are evaluated for the Python Homebrew uses.
+          uv export --no-dev --no-hashes --format requirements-txt \
+            | uv run --no-project --with packaging python .github/scripts/generate_resources.py --python 3.13 \
+            > /tmp/resources.rb
 
       - name: Clone homebrew-tap and update formula
         env:

mdfetch-0.9.6/.python-version

@@ -0,0 +1 @@
+3.14

{mdfetch-0.9.4 → mdfetch-0.9.6}/CLAUDE.md

@@ -8,7 +8,7 @@ Python library that extracts article content from web platforms and returns it a
 src/mdfetch/
 ├── __init__.py       # extract() public API + exception re-exports
 ├── cli.py            # Command-line interface and argument parsing
-├── exceptions.py     # MdfetchError hierarchy (7 exception classes)
+├── exceptions.py     # MdfetchError hierarchy (8 exception classes)
 ├── base.py           # BaseExtractor ABC
 ├── router.py         # Domain-to-provider routing
 └── providers/
@@ -76,6 +76,11 @@ make typecheck    # type check
 **Root Cause:** VoxPop is injected outside `div#tns-post-body-content` — confirmed via live DOM inspection across all 5 reference articles.
 **Prevention Rule:** Do not add VoxPop stripping to `TheNewStackExtractor.clean_html()`. If a future redesign moves VoxPop inside the body container, update `clean_html()` to decompose `div.tns-voxpop-screen`.
 
+### ⚠️ thenewstack.io is behind a Cloudflare bot challenge (since 2026-11)
+**Issue:** Every request from md-fetch to thenewstack.io gets HTTP 403 with `cf-mitigated: challenge` and a "Just a moment..." JS page. Weekly integration tests failed on it (issue #50).
+**Root Cause:** Site-side bot protection, not an HTML change. The block is deliberate, so md-fetch must not try to bypass it (no User-Agent tweaks, no headless browser).
+**Prevention Rule:** `BaseExtractor._do_fetch()` raises `AccessBlockedError` (subclass of `HTTPStatusError`) for any provider when `cf-mitigated: challenge` is present, and never retries it. The thenewstack integration tests `pytest.skip` on `AccessBlockedError`, so check the skip reasons in the weekly log to see when the block is lifted.
+
 ### ⚠️ Homebrew formula requires `uses_from_macos` for lxml
 **Issue:** `brew audit --strict --new Formula/md-fetch.rb` fails with missing system library declarations when `lxml` is a resource block.
 **Root Cause:** `lxml` requires `libxml2` and `libxslt`, which are macOS system libraries. Homebrew requires these to be declared explicitly via `uses_from_macos`.

{mdfetch-0.9.4 → mdfetch-0.9.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mdfetch
-Version: 0.9.4
+Version: 0.9.6
 Summary: Extract article content from web platforms and return it as clean Markdown.
 Project-URL: Homepage, https://github.com/stn1slv/md-fetch
 Project-URL: Source, https://github.com/stn1slv/md-fetch
@@ -85,7 +85,8 @@ markdown = extract("https://dzone.com/articles/article-slug")
 markdown = extract("https://boomi.com/blog/article-slug")
 markdown = extract("https://konghq.com/blog/category/article-slug")
 
-# Fallback to Tavily API if the primary extractor fails (requires TAVILY_API_KEY env var)
+# Fallback to Tavily API if the primary extractor fails (requires TAVILY_API_KEY env var).
+# This also covers sites that block md-fetch with bot protection (AccessBlockedError).
 markdown = extract("https://example.com/unsupported-blog", tavily_fallback=True)
 print(markdown)
 ```
@@ -100,6 +101,7 @@ from mdfetch import (
     UnsupportedContentTypeError,
     FetchError,
     HTTPStatusError,
+    AccessBlockedError,
     EmptyContentError,
     MissingAPIKeyError,
 )
@@ -114,6 +116,8 @@ except UnsupportedPlatformError as e:
     print(f"Platform not supported: {e.message}")
 except UnsupportedContentTypeError as e:
     print(f"Not an article page: {e.message}")
+except AccessBlockedError as e:  # subclass of HTTPStatusError, so catch it first
+    print(f"Blocked by bot protection: {e.message}")
 except HTTPStatusError as e:
     print(f"HTTP {e.status_code}: {e.message}")
 except FetchError as e:
@@ -131,7 +135,7 @@ except MissingAPIKeyError as e:
 | Medium   | `medium.com`, `*.medium.com` |
 | dev.to   | `dev.to` |
 | Substack | `substack.com`, `*.substack.com` |
-| The New Stack | `thenewstack.io` |
+| The New Stack | `thenewstack.io` (may be blocked by Cloudflare bot protection; raises `AccessBlockedError`) |
 | DZone | `dzone.com` |
 | Boomi | `boomi.com` |
 | Kong | `konghq.com` |

{mdfetch-0.9.4 → mdfetch-0.9.6}/README.md

@@ -51,7 +51,8 @@ markdown = extract("https://dzone.com/articles/article-slug")
 markdown = extract("https://boomi.com/blog/article-slug")
 markdown = extract("https://konghq.com/blog/category/article-slug")
 
-# Fallback to Tavily API if the primary extractor fails (requires TAVILY_API_KEY env var)
+# Fallback to Tavily API if the primary extractor fails (requires TAVILY_API_KEY env var).
+# This also covers sites that block md-fetch with bot protection (AccessBlockedError).
 markdown = extract("https://example.com/unsupported-blog", tavily_fallback=True)
 print(markdown)
 ```
@@ -66,6 +67,7 @@ from mdfetch import (
     UnsupportedContentTypeError,
     FetchError,
     HTTPStatusError,
+    AccessBlockedError,
     EmptyContentError,
     MissingAPIKeyError,
 )
@@ -80,6 +82,8 @@ except UnsupportedPlatformError as e:
     print(f"Platform not supported: {e.message}")
 except UnsupportedContentTypeError as e:
     print(f"Not an article page: {e.message}")
+except AccessBlockedError as e:  # subclass of HTTPStatusError, so catch it first
+    print(f"Blocked by bot protection: {e.message}")
 except HTTPStatusError as e:
     print(f"HTTP {e.status_code}: {e.message}")
 except FetchError as e:
@@ -97,7 +101,7 @@ except MissingAPIKeyError as e:
 | Medium   | `medium.com`, `*.medium.com` |
 | dev.to   | `dev.to` |
 | Substack | `substack.com`, `*.substack.com` |
-| The New Stack | `thenewstack.io` |
+| The New Stack | `thenewstack.io` (may be blocked by Cloudflare bot protection; raises `AccessBlockedError`) |
 | DZone | `dzone.com` |
 | Boomi | `boomi.com` |
 | Kong | `konghq.com` |

{mdfetch-0.9.4 → mdfetch-0.9.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mdfetch"
-version = "0.9.4"
+version = "0.9.6"
 description = "Extract article content from web platforms and return it as clean Markdown."
 readme = "README.md"
 license = { text = "MIT" }

{mdfetch-0.9.4 → mdfetch-0.9.6}/src/mdfetch/__init__.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import os
 
 from mdfetch.exceptions import (
+    AccessBlockedError,
     EmptyContentError,
     FetchError,
     HTTPStatusError,
@@ -26,6 +27,7 @@ __all__ = [
     "UnsupportedContentTypeError",
     "FetchError",
     "HTTPStatusError",
+    "AccessBlockedError",
     "EmptyContentError",
     "MissingAPIKeyError",
 ]
@@ -43,7 +45,8 @@ def extract(
     On transient network failures (timeouts, connection errors, non-2xx responses) the
     request is attempted up to *retries* times total (so ``retries=3`` means one initial
     attempt plus two retries) with a fixed delay of *retry_delay* seconds between attempts.
-    Set ``retries=1`` to disable retries.
+    Set ``retries=1`` to disable retries. A bot-protection block (:class:`AccessBlockedError`)
+    is raised at once, without retries.
     """
     if tavily_fallback and not os.environ.get("TAVILY_API_KEY"):
         raise MissingAPIKeyError(

{mdfetch-0.9.4 → mdfetch-0.9.6}/src/mdfetch/base.py

@@ -14,6 +14,7 @@ from bs4.element import Tag
 from markdownify import markdownify
 
 from mdfetch.exceptions import (
+    AccessBlockedError,
     EmptyContentError,
     FetchError,
     HTTPStatusError,
@@ -55,9 +56,10 @@ class BaseExtractor(ABC):
         Makes up to *retries* total attempts on transient :class:`FetchError` (network
         errors, timeouts, non-2xx responses) with a fixed delay of *retry_delay* seconds
         between attempts.  Status codes listed in :attr:`_no_retry_status_codes` are
-        raised immediately without any retry or sleep.  Pass ``_no_retry_codes`` to
-        override the class-level set for this call only (used internally for per-call
-        overrides).
+        raised immediately without any retry or sleep, and so is
+        :class:`AccessBlockedError` (a bot challenge cannot pass on retry).  Pass
+        ``_no_retry_codes`` to override the class-level set for this call only (used
+        internally for per-call overrides).
         """
         no_retry = self._no_retry_status_codes if _no_retry_codes is None else _no_retry_codes
         last_exc: FetchError | None = None
@@ -66,7 +68,9 @@ class BaseExtractor(ABC):
                 try:
                     return self._do_fetch(url, client)
                 except FetchError as exc:
-                    if isinstance(exc, HTTPStatusError) and exc.status_code in no_retry:
+                    if isinstance(exc, AccessBlockedError) or (
+                        isinstance(exc, HTTPStatusError) and exc.status_code in no_retry
+                    ):
                         raise
                     last_exc = exc
                     if attempt < retries - 1:
@@ -81,6 +85,14 @@ class BaseExtractor(ABC):
         try:
             with client.stream("GET", url, headers=headers) as response:
                 if not response.is_success:
+                    cf_mitigated = (response.headers.get("cf-mitigated") or "").strip().lower()
+                    if cf_mitigated == "challenge":
+                        raise AccessBlockedError(
+                            f"HTTP {response.status_code} fetching {url}: access blocked by "
+                            "the site's bot protection (Cloudflare challenge)",
+                            status_code=response.status_code,
+                            url=url,
+                        )
                     raise HTTPStatusError(
                         f"HTTP {response.status_code} fetching {url}",
                         status_code=response.status_code,

{mdfetch-0.9.4 → mdfetch-0.9.6}/src/mdfetch/exceptions.py

@@ -36,6 +36,13 @@ class HTTPStatusError(FetchError):
         self.status_code = status_code
 
 
+class AccessBlockedError(HTTPStatusError):
+    """Raised when the site's bot protection (e.g. a Cloudflare challenge) blocks the request.
+
+    Retrying does not help: the site requires a real browser to pass the challenge.
+    """
+
+
 class EmptyContentError(MdfetchError):
     """Raised when the article body yields no extractable text content."""
 

{mdfetch-0.9.4 → mdfetch-0.9.6}/src/mdfetch/providers/medium.py

@@ -46,13 +46,15 @@ class MediumExtractor(BaseExtractor):
         ):
             button.decompose()
 
-        for element in article.find_all(attrs={"data-testid": "post-sidebar"}):
+        for element in article.find_all(None, attrs={"data-testid": "post-sidebar"}):
             element.decompose()
 
-        for element in article.find_all(attrs={"data-testid": re.compile(r"share", re.IGNORECASE)}):
+        for element in article.find_all(
+            None, attrs={"data-testid": re.compile(r"share", re.IGNORECASE)}
+        ):
             element.decompose()
 
-        for element in article.find_all(attrs={"data-testid": "post-footer"}):
+        for element in article.find_all(None, attrs={"data-testid": "post-footer"}):
             element.decompose()
 
         for section in article.find_all("section"):

{mdfetch-0.9.4 → mdfetch-0.9.6}/src/mdfetch/providers/substack.py

@@ -40,7 +40,7 @@ class SubstackExtractor(BaseExtractor):
         self._replace_embeds_with_links(
             [
                 e
-                for e in body.find_all(attrs={"data-component-name": True})
+                for e in body.find_all(None, attrs={"data-component-name": True})
                 if e.get("data-component-name") not in _safe_components
             ],
             soup,

{mdfetch-0.9.4 → mdfetch-0.9.6}/tests/conftest.py

@@ -12,6 +12,7 @@ def make_stream_mock(
     body: bytes = b"<html></html>",
     content_type: str = "text/html; charset=utf-8",
     stream_side_effect: Exception | None = None,
+    headers: dict[str, str] | None = None,
 ) -> MagicMock:
     """Build a mock httpx.Client whose .stream() behaves like a real streaming response."""
     mock_response = MagicMock()
@@ -19,7 +20,7 @@ def make_stream_mock(
     mock_response.status_code = status_code
     mock_response.encoding = "utf-8"
     mock_response.iter_bytes.side_effect = lambda: iter([body])
-    mock_response.headers = {"content-type": content_type}
+    mock_response.headers = {"content-type": content_type, **(headers or {})}
 
     mock_stream_ctx = MagicMock()
     mock_stream_ctx.__enter__ = MagicMock(return_value=mock_response)

{mdfetch-0.9.4 → mdfetch-0.9.6}/tests/integration/test_thenewstack_integration.py

@@ -7,10 +7,14 @@ from pathlib import Path
 import pytest
 
 from mdfetch import extract
-from mdfetch.exceptions import UnsupportedContentTypeError
+from mdfetch.exceptions import AccessBlockedError, UnsupportedContentTypeError
 
 SNAPSHOTS_DIR = Path(__file__).parent / "snapshots"
 
+# Since 2026-11 thenewstack.io serves a Cloudflare bot challenge to non-browser
+# clients. Skip instead of failing so the weekly run still reports other providers.
+BLOCKED_REASON = "thenewstack.io blocked by Cloudflare bot challenge"
+
 THENEWSTACK_TEST_CASES: list[tuple[str, str]] = [
     (
         "https://thenewstack.io/using-a-developer-portal-for-api-management/",
@@ -45,7 +49,10 @@ def test_extract_contains_snapshot(url: str, snapshot: str) -> None:
     requiring an exact match, making tests resilient to minor structural changes.
     """
     expected = (SNAPSHOTS_DIR / snapshot).read_text(encoding="utf-8")
-    result = extract(url, retries=3, retry_delay=2.0)
+    try:
+        result = extract(url, retries=3, retry_delay=2.0)
+    except AccessBlockedError:
+        pytest.skip(f"{BLOCKED_REASON}: {url}")
     assert expected in result, (
         f"Extracted content for {snapshot!r} does not contain the stored snapshot body.\n"
         f"To regenerate the snapshot, run:\n"
@@ -60,5 +67,10 @@ def test_extract_contains_snapshot(url: str, snapshot: str) -> None:
 @pytest.mark.integration
 def test_homepage_raises_unsupported_content_type_error() -> None:
     """US2: A thenewstack.io homepage raises UnsupportedContentTypeError."""
-    with pytest.raises(UnsupportedContentTypeError):
+    try:
         extract("https://thenewstack.io/", retries=1, retry_delay=0.0)
+    except AccessBlockedError:
+        pytest.skip(f"{BLOCKED_REASON}: https://thenewstack.io/")
+    except UnsupportedContentTypeError:
+        return
+    pytest.fail("Expected UnsupportedContentTypeError for the thenewstack.io homepage")

{mdfetch-0.9.4 → mdfetch-0.9.6}/tests/unit/test_fallback.py

@@ -7,7 +7,12 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from mdfetch import extract
-from mdfetch.exceptions import EmptyContentError, FetchError, MissingAPIKeyError
+from mdfetch.exceptions import (
+    AccessBlockedError,
+    EmptyContentError,
+    FetchError,
+    MissingAPIKeyError,
+)
 from mdfetch.fallback import tavily_extract
 
 
@@ -121,3 +126,20 @@ class TestExtractRouting:
 
         assert result == "# Fallback content"
         mock_tavily.assert_called_once_with("https://medium.com/test", timeout=30.0)
+
+    @patch("mdfetch.route")
+    @patch("mdfetch.tavily_extract")
+    @patch.dict("os.environ", {"TAVILY_API_KEY": "fake-key"})
+    def test_access_blocked_routes_to_fallback(
+        self, mock_tavily: MagicMock, mock_route: MagicMock
+    ) -> None:
+        url = "https://thenewstack.io/article"
+        mock_tavily.return_value = "# Fallback content"
+        mock_route.return_value.extract.side_effect = AccessBlockedError(
+            "blocked", status_code=403, url=url
+        )
+
+        result = extract(url, tavily_fallback=True)
+
+        assert result == "# Fallback content"
+        mock_tavily.assert_called_once_with(url, timeout=30.0)

{mdfetch-0.9.4 → mdfetch-0.9.6}/tests/unit/test_fetch_errors.py

@@ -7,7 +7,12 @@ from unittest.mock import call, patch
 import httpx
 import pytest
 
-from mdfetch.exceptions import FetchError, HTTPStatusError, UnsupportedContentTypeError
+from mdfetch.exceptions import (
+    AccessBlockedError,
+    FetchError,
+    HTTPStatusError,
+    UnsupportedContentTypeError,
+)
 from mdfetch.providers.medium import MediumExtractor
 from tests.conftest import make_stream_mock
 
@@ -101,6 +106,53 @@ class TestFetchErrors:
         assert mock_sleep.call_count == 2  # 3 attempts → 2 sleeps
         assert mock_sleep.call_args_list == [call(1.0), call(1.0)]  # fixed delay, not exponential
 
+    def test_cloudflare_challenge_raises_access_blocked_error(
+        self, extractor: MediumExtractor
+    ) -> None:
+        mock = make_stream_mock(
+            status_code=403, is_success=False, headers={"cf-mitigated": "challenge"}
+        )
+        with patch("httpx.Client", return_value=mock):
+            with pytest.raises(AccessBlockedError, match="bot protection") as exc_info:
+                extractor.fetch_html("https://medium.com/article", retries=1)
+
+        assert exc_info.value.status_code == 403
+        assert isinstance(exc_info.value, HTTPStatusError)
+        assert isinstance(exc_info.value, FetchError)
+
+    def test_cloudflare_challenge_value_is_matched_case_insensitively(
+        self, extractor: MediumExtractor
+    ) -> None:
+        mock = make_stream_mock(
+            status_code=403, is_success=False, headers={"cf-mitigated": " Challenge "}
+        )
+        with patch("httpx.Client", return_value=mock):
+            with pytest.raises(AccessBlockedError):
+                extractor.fetch_html("https://medium.com/article", retries=1)
+
+    def test_cloudflare_challenge_is_not_retried(self, extractor: MediumExtractor) -> None:
+        """A bot challenge cannot pass on retry, so it must raise without any sleep."""
+        mock = make_stream_mock(
+            status_code=503, is_success=False, headers={"cf-mitigated": "challenge"}
+        )
+        with patch("httpx.Client", return_value=mock):
+            with patch("mdfetch.base.time.sleep") as mock_sleep:
+                with pytest.raises(AccessBlockedError):
+                    extractor.fetch_html("https://medium.com/article", retries=3)
+
+        mock_sleep.assert_not_called()
+        assert mock.stream.call_count == 1
+
+    def test_403_without_challenge_header_is_plain_http_status_error(
+        self, extractor: MediumExtractor
+    ) -> None:
+        mock = make_stream_mock(status_code=403, is_success=False)
+        with patch("httpx.Client", return_value=mock):
+            with pytest.raises(HTTPStatusError) as exc_info:
+                extractor.fetch_html("https://medium.com/article", retries=1)
+
+        assert not isinstance(exc_info.value, AccessBlockedError)
+
     def test_raises_unsupported_content_type_for_json(self, extractor: MediumExtractor) -> None:
         mock = make_stream_mock(content_type="application/json")
         with patch("httpx.Client", return_value=mock):