patchtroy 0.4.4__tar.gz → 0.4.6__tar.gz

{patchtroy-0.4.4 → patchtroy-0.4.6}/Dockerfile

@@ -8,7 +8,7 @@ FROM python:3.11-slim
 LABEL maintainer="Marcus Zou <marcus.zou@icloud.com>"
 LABEL org.opencontainers.image.title="Patchtroy"
 LABEL org.opencontainers.image.description="Undetected stealth web scraper & markdown extractor microservice"
-LABEL org.opencontainers.image.version="0.4.4"
+LABEL org.opencontainers.image.version="0.4.6"
 
 # Python and environment settings
 ENV PYTHONUNBUFFERED=1 \

{patchtroy-0.4.4 → patchtroy-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: patchtroy
-Version: 0.4.4
+Version: 0.4.6
 Summary: Undetected stealth web scraper & markdown extractor for LLMs, pairing Patchright with Trafilatura.
 Project-URL: Homepage, https://github.com/marcuz-apl/patchtroy
 Project-URL: Repository, https://github.com/marcuz-apl/patchtroy

{patchtroy-0.4.4 → patchtroy-0.4.6}/PRD.md

@@ -152,7 +152,7 @@ Patchtroy occupies the unoccupied **"Lightweight Stealth Sweet Spot"**:
 - [x] Token counter & LLM chunking utility (`result.chunk(max_tokens=2048)`).
 - [x] Full test suite (32 tests passing).
 
-### Phase 4 (v0.4.4 — Current)
+### Phase 4 (v0.4.6 — Current)
 - [x] PyPI public release workflows & multi-OS matrix CI (`.github/workflows/`).
 - [x] Comprehensive benchmark publication vs Crawl4AI and Firecrawl (`benchmarks/BENCHMARKS.md`).
 - [x] Official documentation portal (Material for MkDocs).

patchtroy-0.4.6/VERSION

@@ -0,0 +1 @@
+v0.4.7-260902d

{patchtroy-0.4.4 → patchtroy-0.4.6}/benchmarks/BENCHMARKS.md

@@ -19,7 +19,7 @@ Existing open-source solutions force developers to choose between:
 
 ## 2. Feature & Architecture Matrix
 
-| Dimension | **Patchtroy** (v0.4.4) | **Crawl4AI** (v0.9.3) | **Firecrawl** (Self-Hosted) |
+| Dimension | **Patchtroy** (v0.4.6) | **Crawl4AI** (v0.9.3) | **Firecrawl** (Self-Hosted) |
 | :--- | :---: | :---: | :---: |
 | **Stealth Engine** | **✅ Native Patchright (C++ CDP masked)** | ❌ Standard Playwright (CDP leaked) | ⚠️ Standard Playwright / Puppeteer |
 | **Dynamic Challenge Resilience** | **✅ Native driver protection** | ❌ Frequently flagged on automated checks | ❌ Blocked unless using paid SaaS proxy |

{patchtroy-0.4.4 → patchtroy-0.4.6}/docs/benchmarks.md

@@ -1,6 +1,6 @@
 # 📊 Benchmarks vs Crawl4AI and Firecrawl
 
-A quantitative, reproducible benchmark comparing **Patchtroy (v0.4.4)** against **Crawl4AI (v0.9.3)** and **Firecrawl (Self-Hosted)**.
+A quantitative, reproducible benchmark comparing **Patchtroy (v0.4.6)** against **Crawl4AI (v0.9.3)** and **Firecrawl (Self-Hosted)**.
 
 ---
 

{patchtroy-0.4.4 → patchtroy-0.4.6}/docs/rest-api.md

@@ -53,7 +53,7 @@ curl http://localhost:4013/health
 ```json
 {
   "status": "healthy",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "engine": "patchright",
   "active": true
 }

{patchtroy-0.4.4 → patchtroy-0.4.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "patchtroy"
-version = "0.4.4"
+version = "0.4.6"
 description = "Undetected stealth web scraper & markdown extractor for LLMs, pairing Patchright with Trafilatura."
 readme = "README.md"
 license = "Apache-2.0"

{patchtroy-0.4.4 → patchtroy-0.4.6}/src/patchtroy/__init__.py

@@ -6,7 +6,7 @@ from patchtroy.models import LinkItem, PatchtroyConfig, ScrapeResult
 from patchtroy.pool import BrowserContextPool
 from patchtroy.proxy import ProxyItem, ProxyManager
 
-__version__ = "0.4.4"
+__version__ = "0.4.6"
 __author__ = "Marcus Zou"
 __license__ = "Apache-2.0"
 __copyright__ = "Copyright 2026 Alfazen Inc."

{patchtroy-0.4.4 → patchtroy-0.4.6}/src/patchtroy/cli.py

@@ -9,8 +9,9 @@ from pathlib import Path
 
 from patchtroy.crawler import Patchtroy
 from patchtroy.models import PatchtroyConfig
+from patchtroy.utils import silence_windows_proactor_bug
 
-__version__ = "0.4.4"
+__version__ = "0.4.6"
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -129,68 +130,70 @@ def main(argv: list[str] | None = None) -> int:
         pdf_path=args.pdf,
     )
 
+    silence_windows_proactor_bug()
     crawler = Patchtroy(config)
 
-    # Single URL execution
-    if len(args.urls) == 1:
-        target_url = args.urls[0]
-        result = crawler.scrape(target_url)
+    with crawler:
+        # Single URL execution
+        if len(args.urls) == 1:
+            target_url = args.urls[0]
+            result = crawler.scrape(target_url)
+
+            if not result.success and not result.markdown:
+                sys.stderr.write(f"Error scraping {target_url}: {result.error}\n")
+                return 1
+
+            if args.format == "json":
+                # Avoid serializing raw media bytes directly into standard JSON
+                dump_data = result.model_dump(exclude={"screenshot_bytes", "pdf_bytes"})
+                content = json.dumps(dump_data, indent=2, ensure_ascii=False)
+            elif args.format == "html":
+                content = result.html
+            else:
+                header = f"# {result.title}\n\nSource: {result.url}\n\n" if result.title else ""
+                content = header + result.markdown
+
+            if args.output:
+                Path(args.output).write_text(content, encoding="utf-8")
+                sys.stderr.write(f"[Patchtroy] Extracted content saved to {args.output} ({len(content)} chars)\n")
+            else:
+                print(content)
+
+            if args.screenshot and result.screenshot_bytes:
+                sys.stderr.write(f"[Patchtroy] Screenshot saved to {args.screenshot}\n")
+            if args.pdf and result.pdf_bytes:
+                sys.stderr.write(f"[Patchtroy] PDF saved to {args.pdf}\n")
+
+            return 0
 
-        if not result.success and not result.markdown:
-            sys.stderr.write(f"Error scraping {target_url}: {result.error}\n")
-            return 1
+        # Batch URLs execution
+        sys.stderr.write(f"[Patchtroy] Batch scraping {len(args.urls)} URLs (concurrency: {args.concurrency})...\n")
+        results = crawler.scrape_many(args.urls)
 
         if args.format == "json":
-            # Avoid serializing raw media bytes directly into standard JSON
-            dump_data = result.model_dump(exclude={"screenshot_bytes", "pdf_bytes"})
+            dump_data = [
+                r.model_dump(exclude={"screenshot_bytes", "pdf_bytes"})
+                for r in results
+            ]
             content = json.dumps(dump_data, indent=2, ensure_ascii=False)
-        elif args.format == "html":
-            content = result.html
         else:
-            header = f"# {result.title}\n\nSource: {result.url}\n\n" if result.title else ""
-            content = header + result.markdown
+            combined = []
+            for r in results:
+                if r.success:
+                    header = f"# {r.title}\n\nSource: {r.url}\n\n" if r.title else f"Source: {r.url}\n\n"
+                    combined.append(header + r.markdown)
+                else:
+                    combined.append(f"<!-- Failed: {r.url} ({r.error}) -->")
+            content = "\n\n---\n\n".join(combined)
 
         if args.output:
             Path(args.output).write_text(content, encoding="utf-8")
-            sys.stderr.write(f"[Patchtroy] Extracted content saved to {args.output} ({len(content)} chars)\n")
+            sys.stderr.write(f"[Patchtroy] Batch results saved to {args.output}\n")
         else:
             print(content)
 
-        if args.screenshot and result.screenshot_bytes:
-            sys.stderr.write(f"[Patchtroy] Screenshot saved to {args.screenshot}\n")
-        if args.pdf and result.pdf_bytes:
-            sys.stderr.write(f"[Patchtroy] PDF saved to {args.pdf}\n")
-
         return 0
 
-    # Batch URLs execution
-    sys.stderr.write(f"[Patchtroy] Batch scraping {len(args.urls)} URLs (concurrency: {args.concurrency})...\n")
-    results = crawler.scrape_many(args.urls)
-
-    if args.format == "json":
-        dump_data = [
-            r.model_dump(exclude={"screenshot_bytes", "pdf_bytes"})
-            for r in results
-        ]
-        content = json.dumps(dump_data, indent=2, ensure_ascii=False)
-    else:
-        combined = []
-        for r in results:
-            if r.success:
-                header = f"# {r.title}\n\nSource: {r.url}\n\n" if r.title else f"Source: {r.url}\n\n"
-                combined.append(header + r.markdown)
-            else:
-                combined.append(f"<!-- Failed: {r.url} ({r.error}) -->")
-        content = "\n\n---\n\n".join(combined)
-
-    if args.output:
-        Path(args.output).write_text(content, encoding="utf-8")
-        sys.stderr.write(f"[Patchtroy] Batch results saved to {args.output}\n")
-    else:
-        print(content)
-
-    return 0
-
 
 if __name__ == "__main__":
     sys.exit(main())

{patchtroy-0.4.4 → patchtroy-0.4.6}/src/patchtroy/crawler.py

@@ -19,7 +19,12 @@ from patchtroy.extractors import (
 from patchtroy.models import LinkItem, PatchtroyConfig, ScrapeResult
 from patchtroy.pool import BrowserContextPool
 from patchtroy.proxy import ProxyManager
-from patchtroy.utils import STEALTH_INJECTION_SCRIPT, get_random_user_agent, is_valid_url
+from patchtroy.utils import (
+    STEALTH_INJECTION_SCRIPT,
+    get_random_user_agent,
+    is_valid_url,
+    silence_windows_proactor_bug,
+)
 
 logger = logging.getLogger("patchtroy.crawler")
 
@@ -312,11 +317,30 @@ class AsyncPatchtroy:
             return await client.scrape_many(urls, wait_for=wait_for, custom_schema=custom_schema)
 
 
+def _run_sync(coro: Any) -> Any:
+    """Execute coroutine synchronously with Windows proactor event loop protections."""
+    silence_windows_proactor_bug()
+    if sys.platform == "win32":
+        asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
+    return asyncio.run(coro)
+
+
 class Patchtroy:
     """Synchronous wrapper for Patchtroy crawler execution."""
 
     def __init__(self, config: PatchtroyConfig | dict[str, Any] | None = None) -> None:
-        self._async_crawler = AsyncPatchtroy(config)
+        self.config = (
+            PatchtroyConfig(**config)
+            if isinstance(config, dict)
+            else (config or PatchtroyConfig())
+        )
+        silence_windows_proactor_bug()
+        self._async_crawler: AsyncPatchtroy | None = None
+
+    def _get_crawler(self) -> AsyncPatchtroy:
+        if self._async_crawler is None:
+            self._async_crawler = AsyncPatchtroy(self.config)
+        return self._async_crawler
 
     def scrape(
         self,
@@ -325,9 +349,8 @@ class Patchtroy:
         custom_schema: dict[str, Any] | None = None,
     ) -> ScrapeResult:
         """Execute scrape synchronously in an event loop."""
-        if sys.platform == "win32":
-            asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
-        return asyncio.run(self._async_crawler.scrape(url, wait_for=wait_for, custom_schema=custom_schema))
+        crawler = self._get_crawler()
+        return _run_sync(crawler.scrape(url, wait_for=wait_for, custom_schema=custom_schema))
 
     def scrape_many(
         self,
@@ -336,9 +359,22 @@ class Patchtroy:
         custom_schema: dict[str, Any] | None = None,
     ) -> list[ScrapeResult]:
         """Execute concurrent batch scraping synchronously."""
-        if sys.platform == "win32":
-            asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
-        return asyncio.run(self._async_crawler.scrape_many(urls, wait_for=wait_for, custom_schema=custom_schema))
+        crawler = self._get_crawler()
+        return _run_sync(crawler.scrape_many(urls, wait_for=wait_for, custom_schema=custom_schema))
+
+    def close(self) -> None:
+        """Close browser pool and cleanup resources."""
+        if self._async_crawler is not None:
+            try:
+                _run_sync(self._async_crawler.close())
+            finally:
+                self._async_crawler = None
+
+    def __enter__(self) -> Patchtroy:
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        self.close()
 
     @classmethod
     def crawl(
@@ -351,9 +387,7 @@ class Patchtroy:
         pdf: bool = False,
     ) -> ScrapeResult:
         """Synchronous one-shot convenience function for scraping."""
-        if sys.platform == "win32":
-            asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
-        return asyncio.run(
+        return _run_sync(
             AsyncPatchtroy.crawl(
                 url,
                 headless=headless,
@@ -374,9 +408,7 @@ class Patchtroy:
         custom_schema: dict[str, Any] | None = None,
     ) -> list[ScrapeResult]:
         """Synchronous one-shot convenience function for concurrent batch crawling."""
-        if sys.platform == "win32":
-            asyncio.set_event_loop_policy(asyncio.WindowsProactorEventLoopPolicy())
-        return asyncio.run(
+        return _run_sync(
             AsyncPatchtroy.crawl_many(
                 urls,
                 headless=headless,

{patchtroy-0.4.4 → patchtroy-0.4.6}/src/patchtroy/pool.py

@@ -89,6 +89,9 @@ class BrowserContextPool:
                     pass
                 self._playwright = None
 
+            # Allow event loop to process subprocess termination callbacks before shutdown
+            await asyncio.sleep(0.05)
+
     @asynccontextmanager
     async def acquire_context(
         self,

{patchtroy-0.4.4 → patchtroy-0.4.6}/src/patchtroy/server.py

@@ -90,16 +90,16 @@ def create_app() -> FastAPI:
     app = FastAPI(
         title="Patchtroy REST Microservice",
         description="Undetected stealth web scraper & clean Markdown extractor for LLMs.",
-        version="0.4.4",
+        version="0.4.6",
         lifespan=lifespan,
     )
 
-    @app.get("/health")
+    @app.get("/health", tags=["Health"])
     async def health_check() -> dict[str, Any]:
         """Microservice health and status check."""
         return {
             "status": "healthy",
-            "version": "0.4.4",
+            "version": "0.4.6",
             "engine": "patchright",
             "active": crawler_instance is not None and crawler_instance._pool.is_running,
         }

patchtroy-0.4.6/src/patchtroy/utils.py

@@ -0,0 +1,105 @@
+"""Utility functions, stealth injection scripts, and platform helpers."""
+
+from __future__ import annotations
+
+import random
+from typing import Any
+from urllib.parse import urlparse
+
+DEFAULT_USER_AGENTS = [
+    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
+]
+
+STEALTH_INJECTION_SCRIPT = """
+// Configure natural browser environment signatures
+Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
+window.chrome = {
+    runtime: {},
+    loadTimes: function() {},
+    csi: function() {},
+    app: {}
+};
+// Emulate realistic plugins
+Object.defineProperty(navigator, 'plugins', {
+    get: () => [1, 2, 3, 4, 5],
+});
+// Emulate standard languages
+Object.defineProperty(navigator, 'languages', {
+    get: () => ['en-US', 'en'],
+});
+// Emulate permissions query
+if (window.navigator && window.navigator.permissions) {
+    const originalQuery = window.navigator.permissions.query;
+    window.navigator.permissions.query = (parameters) => (
+        parameters.name === 'notifications' ?
+            Promise.resolve({ state: 'default' }) :
+            originalQuery(parameters)
+    );
+}
+"""
+
+
+def get_random_user_agent() -> str:
+    """Return a realistic modern desktop browser User-Agent."""
+    return random.choice(DEFAULT_USER_AGENTS)
+
+
+def is_valid_url(url: str) -> bool:
+    """Validate URL scheme is http or https."""
+    try:
+        parsed = urlparse(url)
+        return parsed.scheme in ("http", "https") and bool(parsed.netloc)
+    except Exception:
+        return False
+
+
+def silence_subprocess_transport_bug() -> None:
+    """Silence Python asyncio BaseSubprocessTransport and pipe transport destructor errors.
+
+    When an event loop finishes and closes (via asyncio.run), underlying child process
+    transports may remain in the garbage collector until interpreter exit. During GC,
+    their __del__ destructors attempt post-loop cleanup:
+      - On Unix/Linux: calls self.close() -> loop.call_soon() -> RuntimeError('Event loop is closed')
+      - On Windows: calls _warn() -> __repr__() -> fileno() -> ValueError('I/O operation on closed pipe')
+    Wrapping both destructors safely catches and suppresses these post-loop cleanup errors across
+    all platforms (Linux, macOS, Windows).
+    """
+    try:
+        from asyncio.base_subprocess import BaseSubprocessTransport
+
+        orig_sub_del = getattr(BaseSubprocessTransport, "__del__", None)
+        if orig_sub_del and not getattr(BaseSubprocessTransport, "_patchtroy_safe", False):
+
+            def _safe_sub_del(self: Any, *args: Any, **kwargs: Any) -> None:
+                try:
+                    orig_sub_del(self, *args, **kwargs)
+                except (RuntimeError, ValueError, OSError):
+                    pass
+
+            BaseSubprocessTransport.__del__ = _safe_sub_del  # type: ignore[method-assign]
+            BaseSubprocessTransport._patchtroy_safe = True  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+    try:
+        from asyncio.proactor_events import _ProactorBasePipeTransport
+
+        orig_pipe_del = getattr(_ProactorBasePipeTransport, "__del__", None)
+        if orig_pipe_del and not getattr(_ProactorBasePipeTransport, "_patchtroy_safe", False):
+
+            def _safe_pipe_del(self: Any, *args: Any, **kwargs: Any) -> None:
+                try:
+                    orig_pipe_del(self, *args, **kwargs)
+                except (RuntimeError, ValueError, OSError):
+                    pass
+
+            _ProactorBasePipeTransport.__del__ = _safe_pipe_del  # type: ignore[method-assign]
+            _ProactorBasePipeTransport._patchtroy_safe = True  # type: ignore[attr-defined]
+    except Exception:
+        pass
+
+
+# Backwards-compatible alias
+silence_windows_proactor_bug = silence_subprocess_transport_bug

{patchtroy-0.4.4 → patchtroy-0.4.6}/tests/test_crawler.py

@@ -40,3 +40,18 @@ def test_sync_scrape_many():
     results = crawler.scrape_many(urls)
     assert len(results) == 2
     assert all(not r.success for r in results)
+    crawler.close()
+
+
+def test_sync_context_manager():
+    with Patchtroy() as crawler:
+        res = crawler.scrape("ftp://bad-url")
+        assert res.success is False
+
+
+def test_silence_windows_proactor_bug():
+    from patchtroy.utils import silence_windows_proactor_bug
+
+    # Should execute cleanly across all platforms
+    silence_windows_proactor_bug()
+

{patchtroy-0.4.4 → patchtroy-0.4.6}/tests/test_server.py

@@ -17,7 +17,7 @@ async def test_health_check_endpoint():
         assert resp.status_code == 200
         data = resp.json()
         assert data["status"] == "healthy"
-        assert data["version"] == "0.4.4"
+        assert data["version"] == "0.4.6"
         assert data["engine"] == "patchright"
 
 

{patchtroy-0.4.4 → patchtroy-0.4.6}/uv.lock

@@ -900,7 +900,7 @@ wheels = [
 
 [[package]]
 name = "patchtroy"
-version = "0.4.4"
+version = "0.4.6"
 source = { editable = "." }
 dependencies = [
     { name = "beautifulsoup4" },

patchtroy-0.4.4/VERSION

@@ -1 +0,0 @@
-v0.4.4-260902a

patchtroy-0.4.4/src/patchtroy/utils.py

@@ -1,54 +0,0 @@
-"""Utility functions, stealth injection scripts, and headers."""
-
-from __future__ import annotations
-
-import random
-from urllib.parse import urlparse
-
-DEFAULT_USER_AGENTS = [
-    "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
-    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
-    "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36",
-]
-
-STEALTH_INJECTION_SCRIPT = """
-// Evade common automated browser detection signatures
-Object.defineProperty(navigator, 'webdriver', { get: () => undefined });
-window.chrome = {
-    runtime: {},
-    loadTimes: function() {},
-    csi: function() {},
-    app: {}
-};
-// Emulate realistic plugins
-Object.defineProperty(navigator, 'plugins', {
-    get: () => [1, 2, 3, 4, 5],
-});
-// Emulate standard languages
-Object.defineProperty(navigator, 'languages', {
-    get: () => ['en-US', 'en'],
-});
-// Emulate permissions query
-if (window.navigator && window.navigator.permissions) {
-    const originalQuery = window.navigator.permissions.query;
-    window.navigator.permissions.query = (parameters) => (
-        parameters.name === 'notifications' ?
-            Promise.resolve({ state: 'default' }) :
-            originalQuery(parameters)
-    );
-}
-"""
-
-
-def get_random_user_agent() -> str:
-    """Return a realistic modern desktop browser User-Agent."""
-    return random.choice(DEFAULT_USER_AGENTS)
-
-
-def is_valid_url(url: str) -> bool:
-    """Validate URL scheme is http or https."""
-    try:
-        parsed = urlparse(url)
-        return parsed.scheme in ("http", "https") and bool(parsed.netloc)
-    except Exception:
-        return False