scrapely-python 0.1.22__py3-none-any.whl → 0.1.23__py3-none-any.whl

scrapely/__init__.py

@@ -10,22 +10,20 @@ Usage:
             await Actor.push_data({'url': actor_input['url']})
 """
 
-# Side-effect: patch Crawlee Playwright browser pool to use remote CDP (CDP_URL).
+from typing import TYPE_CHECKING, Any
+
+# Side-effect: patch browser launches (Crawlee BrowserPool, PlaywrightCrawler,
+# raw Playwright, Camoufox, pyppeteer) to use the remote CDP browser (CDP_URL).
 # Must run on package import so `from scrapely import Actor` enables the patch
-# before PlaywrightCrawler launches a browser (Node SDK parity).
+# before any browser is launched (Node SDK parity). It does not import Crawlee:
+# the Crawlee patches are applied when Crawlee's browser modules load.
 from .patch_browser_pool import set_cdp_url  # noqa: F401
 
-from crawlee import Request
-
-from crawlee.request_loaders import (
-    RequestLoader,
-    RequestManager,
-    RequestManagerTandem,
-    SitemapRequestLoader,
-)
-from crawlee.storages import Dataset, KeyValueStore, RequestQueue
-from crawlee.storage_clients.models import DatasetItemsListPage
-
+# Crawlee is NOT imported here: it costs ~1 s per run under gVisor and many
+# actors never touch it. Everything that needs Crawlee (the re-exported Crawlee
+# classes, storage clients, events, request loaders) is resolved on first
+# attribute access by ``__getattr__`` below; ``Actor`` imports what it needs on
+# first use. Every ``from scrapely import X`` that worked before still works.
 from .actor import Actor
 from .configuration import Configuration
 from .charging_client import (
@@ -33,40 +31,6 @@ from .charging_client import (
     create_charging_client,
     push_data_charging_context,
 )
-from .storage import (
-    ApiStorageClient,
-    FileSystemStorageClient,
-    MemoryStorageClient,
-    ScrapelyStorageClient,
-    SmartScrapelyStorageClient,
-    StorageClient,
-    set_api_storage,
-)
-from .request_loaders import ScrapelyRequestList
-from crawlee.events import EventListener
-from .events import (
-    AbortingEvent,
-    ActorEventTypes,
-    CrawleeEventManager,
-    DeprecatedEvent,
-    Event,
-    EventAbortingData,
-    EventExitData,
-    EventManager,
-    EventMessage,
-    EventMigratingData,
-    EventPersistStateData,
-    EventSystemInfoData,
-    EventWithoutData,
-    ExitEvent,
-    LocalEventManager,
-    MigratingEvent,
-    PersistStateEvent,
-    ScrapelyEventManager,
-    SystemInfoEvent,
-    SystemInfoEventData,
-    UnknownEvent,
-)
 from .proxy_configuration import ProxyConfiguration
 from .browser_configuration import BrowserConfiguration
 from .charging import (
@@ -132,7 +96,138 @@ from .errors import (
     raise_for_status,
 )
 
-__version__ = '0.1.22'
+# Public name -> (module, attribute) for names that need Crawlee. Loaded on
+# first access and cached in the module namespace.
+_LAZY_ATTRS = {
+    # Crawlee re-exports
+    'Request': ('crawlee', 'Request'),
+    'RequestLoader': ('crawlee.request_loaders', 'RequestLoader'),
+    'RequestManager': ('crawlee.request_loaders', 'RequestManager'),
+    'RequestManagerTandem': ('crawlee.request_loaders', 'RequestManagerTandem'),
+    'SitemapRequestLoader': ('crawlee.request_loaders', 'SitemapRequestLoader'),
+    'Dataset': ('crawlee.storages', 'Dataset'),
+    'KeyValueStore': ('crawlee.storages', 'KeyValueStore'),
+    'RequestQueue': ('crawlee.storages', 'RequestQueue'),
+    'DatasetItemsListPage': ('crawlee.storage_clients.models', 'DatasetItemsListPage'),
+    'EventListener': ('crawlee.events', 'EventListener'),
+    # Storage clients
+    'ApiStorageClient': ('scrapely.storage', 'ApiStorageClient'),
+    'FileSystemStorageClient': ('scrapely.storage', 'FileSystemStorageClient'),
+    'MemoryStorageClient': ('scrapely.storage', 'MemoryStorageClient'),
+    'ScrapelyStorageClient': ('scrapely.storage', 'ScrapelyStorageClient'),
+    'SmartScrapelyStorageClient': ('scrapely.storage', 'SmartScrapelyStorageClient'),
+    'StorageClient': ('scrapely.storage', 'StorageClient'),
+    'set_api_storage': ('scrapely.storage', 'set_api_storage'),
+    # Request loaders
+    'ScrapelyRequestList': ('scrapely.request_loaders', 'ScrapelyRequestList'),
+    # Events
+    **{
+        name: ('scrapely.events', name)
+        for name in (
+            'AbortingEvent',
+            'ActorEventTypes',
+            'CrawleeEventManager',
+            'DeprecatedEvent',
+            'Event',
+            'EventAbortingData',
+            'EventExitData',
+            'EventManager',
+            'EventMessage',
+            'EventMigratingData',
+            'EventPersistStateData',
+            'EventSystemInfoData',
+            'EventWithoutData',
+            'ExitEvent',
+            'LocalEventManager',
+            'MigratingEvent',
+            'PersistStateEvent',
+            'ScrapelyEventManager',
+            'SystemInfoEvent',
+            'SystemInfoEventData',
+            'UnknownEvent',
+        )
+    },
+}
+
+# Submodules that used to be loaded (and so bound as attributes) by this
+# package's eager imports; ``scrapely.events`` etc. keep working without an
+# explicit ``import scrapely.events``.
+_LAZY_SUBMODULES = frozenset({
+    'events',
+    'log',
+    'request_loaders',
+    'storage',
+    'storage_clients',
+    'storages',
+})
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_ATTRS.get(name)
+    if target is not None:
+        import importlib
+
+        value = getattr(importlib.import_module(target[0]), target[1])
+        globals()[name] = value
+        return value
+    if name in _LAZY_SUBMODULES:
+        import importlib
+
+        return importlib.import_module(f'{__name__}.{name}')
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
+def __dir__() -> list:
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | _LAZY_SUBMODULES)
+
+
+if TYPE_CHECKING:  # Static analysers and IDEs see the lazy names as plain imports.
+    from crawlee import Request
+    from crawlee.events import EventListener
+    from crawlee.request_loaders import (
+        RequestLoader,
+        RequestManager,
+        RequestManagerTandem,
+        SitemapRequestLoader,
+    )
+    from crawlee.storage_clients.models import DatasetItemsListPage
+    from crawlee.storages import Dataset, KeyValueStore, RequestQueue
+
+    from .events import (
+        AbortingEvent,
+        ActorEventTypes,
+        CrawleeEventManager,
+        DeprecatedEvent,
+        Event,
+        EventAbortingData,
+        EventExitData,
+        EventManager,
+        EventMessage,
+        EventMigratingData,
+        EventPersistStateData,
+        EventSystemInfoData,
+        EventWithoutData,
+        ExitEvent,
+        LocalEventManager,
+        MigratingEvent,
+        PersistStateEvent,
+        ScrapelyEventManager,
+        SystemInfoEvent,
+        SystemInfoEventData,
+        UnknownEvent,
+    )
+    from .request_loaders import ScrapelyRequestList
+    from .storage import (
+        ApiStorageClient,
+        FileSystemStorageClient,
+        MemoryStorageClient,
+        ScrapelyStorageClient,
+        SmartScrapelyStorageClient,
+        StorageClient,
+        set_api_storage,
+    )
+
+__version__ = '0.1.23'
 __all__ = [
     # Core
     'Actor',

scrapely/actor.py

@@ -20,10 +20,6 @@ from datetime import datetime, timedelta
 from decimal import Decimal
 from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union, cast
 
-from crawlee.configuration import Configuration as CrawleeConfiguration
-from crawlee.storage_clients._base import StorageClient
-from crawlee.storages import Dataset, KeyValueStore, RequestQueue
-
 from .charging import (
     ChargingManager,
     is_default_dataset_item_event,
@@ -34,23 +30,10 @@ from .charging import (
 from .configuration import Configuration
 from .crypto import decrypt_secret_inputs
 from .proxy_configuration import with_proxy_key_aliases
-from crawlee.events import EventManager
-
-from .events import Event, LocalEventManager, ScrapelyEventManager
 from .charging_client import create_charging_client
 from .errors import ForbiddenError
 from .storage.api_client import ApiClient, ApiClientError
 from .storage.client import is_storage_uuid
-from .storage._metadata import StorageType, resolve_alias_from_storages_json
-from .storage.patch_storage import (
-    disconnect_storage,
-    get_api_storage_factory,
-    get_smart_storage_client,
-    set_api_storage,
-    set_storage_client,
-)
-from .storage.scrapely_storage_client import ScrapelyStorageClient
-from .storage.smart_scrapely_storage_client import SmartScrapelyStorageClient
 from .types import (
     AbortOptions,
     ActorRun,
@@ -66,17 +49,74 @@ from .types import (
     StartOptions,
     WebhookOptions,
 )
-from .log import _configure_logging
 from .webhook import Webhook
 
 if TYPE_CHECKING:
+    from crawlee.events import EventManager
+    from crawlee.storage_clients._base import StorageClient
+    from crawlee.storages import Dataset, KeyValueStore, RequestQueue
     from scrapely_client import ApifyClientAsync
 
+    from .events import Event
+    from .storage._metadata import StorageType
+    from .storage.scrapely_storage_client import ScrapelyStorageClient
+    from .storage.smart_scrapely_storage_client import SmartScrapelyStorageClient
+
     from .browser_configuration import BrowserConfiguration
     from .proxy_configuration import ProxyConfiguration
 
 logger = logging.getLogger(__name__)
 
+# Names that need Crawlee, resolved on first use instead of at import: importing
+# Crawlee costs ~1 s per run under gVisor. They stay module attributes
+# (``scrapely.actor.Dataset`` works and can be monkeypatched): ``_lazy`` returns
+# the module-global value when one is set, else imports and caches it.
+_LAZY_ATTRS: Dict[str, Tuple[str, str]] = {
+    'CrawleeConfiguration': ('crawlee.configuration', 'Configuration'),
+    'StorageClient': ('crawlee.storage_clients._base', 'StorageClient'),
+    'Dataset': ('crawlee.storages', 'Dataset'),
+    'KeyValueStore': ('crawlee.storages', 'KeyValueStore'),
+    'RequestQueue': ('crawlee.storages', 'RequestQueue'),
+    'EventManager': ('crawlee.events', 'EventManager'),
+    'Event': ('scrapely.events', 'Event'),
+    'LocalEventManager': ('scrapely.events', 'LocalEventManager'),
+    'ScrapelyEventManager': ('scrapely.events', 'ScrapelyEventManager'),
+    'StorageType': ('scrapely.storage._metadata', 'StorageType'),
+    'resolve_alias_from_storages_json': ('scrapely.storage._metadata', 'resolve_alias_from_storages_json'),
+    'disconnect_storage': ('scrapely.storage.patch_storage', 'disconnect_storage'),
+    'get_api_storage_factory': ('scrapely.storage.patch_storage', 'get_api_storage_factory'),
+    'get_smart_storage_client': ('scrapely.storage.patch_storage', 'get_smart_storage_client'),
+    'set_api_storage': ('scrapely.storage.patch_storage', 'set_api_storage'),
+    'set_storage_client': ('scrapely.storage.patch_storage', 'set_storage_client'),
+    'ScrapelyStorageClient': ('scrapely.storage.scrapely_storage_client', 'ScrapelyStorageClient'),
+    'SmartScrapelyStorageClient': (
+        'scrapely.storage.smart_scrapely_storage_client',
+        'SmartScrapelyStorageClient',
+    ),
+    '_configure_logging': ('scrapely.log', '_configure_logging'),
+}
+
+
+def _lazy(name: str) -> Any:
+    """Return a Crawlee-dependent module attribute, importing it on first use."""
+    value = globals().get(name, _MISSING)
+    if value is _MISSING:
+        import importlib
+
+        module_name, attr = _LAZY_ATTRS[name]
+        value = getattr(importlib.import_module(module_name), attr)
+        globals()[name] = value
+    return value
+
+
+_MISSING = object()
+
+
+def __getattr__(name: str) -> Any:
+    if name in _LAZY_ATTRS:
+        return _lazy(name)
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
 # Terminal run statuses used by the run-control polling loops (call/call_task).
 _RUN_TERMINAL_STATUSES = frozenset({'SUCCEEDED', 'FAILED', 'ABORTED', 'TIMED-OUT'})
 
@@ -324,7 +364,7 @@ class Actor(metaclass=_ActorMeta):
             return
 
         if options is None or options.configure_logging:
-            _configure_logging()
+            _lazy('_configure_logging')()
 
         # Do NOT set _initialized until everything succeeds (failed init must be retryable).
         cls._config = Configuration.get_global_config()
@@ -338,7 +378,7 @@ class Actor(metaclass=_ActorMeta):
             for key, value in options.configuration.items():
                 cls._config.set(key, value)
 
-        crawlee_config = CrawleeConfiguration.get_global_configuration()
+        crawlee_config = _lazy('CrawleeConfiguration').get_global_configuration()
         if cls._config.get('is_at_home'):
             crawlee_config.purge_on_start = False
 
@@ -361,9 +401,9 @@ class Actor(metaclass=_ActorMeta):
                         '[Scrapely] Initializing API storage for run %s',
                         storage_opt['run_id'],
                     )
-                    smart = set_api_storage(storage_opt)
-                elif isinstance(storage_opt, StorageClient):
-                    smart = set_storage_client(storage_opt)
+                    smart = _lazy('set_api_storage')(storage_opt)
+                elif isinstance(storage_opt, _lazy('StorageClient')):
+                    smart = _lazy('set_storage_client')(storage_opt)
                 else:
                     raise TypeError(
                         'Actor.init() storage option must be ApiStorageConfig or StorageClient'
@@ -375,7 +415,7 @@ class Actor(metaclass=_ActorMeta):
 
                 if api_url and token and run_id:
                     logger.info('[Scrapely] Initializing API storage for run %s', run_id)
-                    smart = set_api_storage({
+                    smart = _lazy('set_api_storage')({
                         'api_url': api_url,
                         'token': token,
                         'run_id': run_id,
@@ -383,7 +423,7 @@ class Actor(metaclass=_ActorMeta):
                 elif not cls._config.get('is_at_home'):
                     # Local development without credentials: Smart → FS (Apify docs shape)
                     logger.info('[Scrapely] Initializing local file-system storage')
-                    smart = set_api_storage()
+                    smart = _lazy('set_api_storage')()
                 else:
                     raise RuntimeError(
                         'Missing required configuration for secure storage. '
@@ -392,8 +432,12 @@ class Actor(metaclass=_ActorMeta):
                         'or pass storage in Actor.init().'
                     )
 
-            cls._smart_storage = smart if isinstance(smart, SmartScrapelyStorageClient) else get_smart_storage_client()
-            factory = get_api_storage_factory()
+            cls._smart_storage = (
+                smart
+                if isinstance(smart, _lazy('SmartScrapelyStorageClient'))
+                else _lazy('get_smart_storage_client')()
+            )
+            factory = _lazy('get_api_storage_factory')()
             cls._scrapely_storage = factory
             if factory is not None and factory.has_credentials():
                 cls._client = factory.api_client
@@ -408,12 +452,12 @@ class Actor(metaclass=_ActorMeta):
 
             event_manager: EventManager
             if ws_url:
-                event_manager = ScrapelyEventManager(
+                event_manager = _lazy('ScrapelyEventManager')(
                     configuration=cls._config,
                     persist_state_interval=persist_interval,
                 )
             else:
-                event_manager = LocalEventManager(
+                event_manager = _lazy('LocalEventManager')(
                     system_info_interval=timedelta(seconds=1),
                     persist_state_interval=persist_interval,
                 )
@@ -544,7 +588,7 @@ class Actor(metaclass=_ActorMeta):
             cls._default_rq = None
             cls._cached_input = None
             try:
-                disconnect_storage()
+                _lazy('disconnect_storage')()
             except BaseException as e:
                 cleanup_error = cleanup_error or e
                 logger.warning('disconnect_storage failed during shutdown: %s', e)
@@ -836,7 +880,7 @@ class Actor(metaclass=_ActorMeta):
 
         target = cls._default_dataset
         if dataset is not None:
-            target = dataset if isinstance(dataset, Dataset) else await cls.open_dataset(name=dataset)
+            target = dataset if isinstance(dataset, _lazy('Dataset')) else await cls.open_dataset(name=dataset)
         is_default = target is cls._default_dataset or (
             getattr(target, 'id', None) is not None and target.id == getattr(cls._default_dataset, 'id', None)
         )
@@ -902,7 +946,7 @@ class Actor(metaclass=_ActorMeta):
 
         if alias is not None:
             storages_json = cls._env_config().get('actor_storages_json')
-            resolved = resolve_alias_from_storages_json(alias, storage_type, storages_json)
+            resolved = _lazy('resolve_alias_from_storages_json')(alias, storage_type, storages_json)
             if resolved is not None:
                 id = resolved
                 alias = None
@@ -915,12 +959,12 @@ class Actor(metaclass=_ActorMeta):
 
     @classmethod
     def _storage_client_for_open(cls, *, force_cloud: bool = False) -> Optional[StorageClient]:
-        smart = cls._smart_storage or get_smart_storage_client()
+        smart = cls._smart_storage or _lazy('get_smart_storage_client')()
         if smart is not None:
             return smart.get_suitable_storage_client(force_cloud=force_cloud)
 
         if force_cloud:
-            cloud = get_api_storage_factory()
+            cloud = _lazy('get_api_storage_factory')()
             if cloud is None:
                 # Build from config like TS _buildStorageOpenOptions
                 config = cls.get_config()
@@ -928,7 +972,7 @@ class Actor(metaclass=_ActorMeta):
                 token = config.get('token')
                 run_id = config.get('actor_run_id')
                 if api_url and token and run_id:
-                    return ScrapelyStorageClient(api_url=api_url, token=token, run_id=run_id)
+                    return _lazy('ScrapelyStorageClient')(api_url=api_url, token=token, run_id=run_id)
                 raise RuntimeError('Cloud storage client is not configured')
             return cloud
         return None
@@ -958,10 +1002,10 @@ class Actor(metaclass=_ActorMeta):
 
         if open_args['id'] is None and open_args['name'] is None and open_args['alias'] is None:
             if cls._default_dataset is None:
-                cls._default_dataset = await Dataset.open(storage_client=storage_client)
+                cls._default_dataset = await _lazy('Dataset').open(storage_client=storage_client)
             return cls._default_dataset
 
-        return await Dataset.open(
+        return await _lazy('Dataset').open(
             id=open_args['id'],
             name=open_args['name'],
             alias=open_args['alias'],
@@ -993,10 +1037,10 @@ class Actor(metaclass=_ActorMeta):
 
         if open_args['id'] is None and open_args['name'] is None and open_args['alias'] is None:
             if cls._default_kvs is None:
-                cls._default_kvs = await KeyValueStore.open(storage_client=storage_client)
+                cls._default_kvs = await _lazy('KeyValueStore').open(storage_client=storage_client)
             return cls._default_kvs
 
-        return await KeyValueStore.open(
+        return await _lazy('KeyValueStore').open(
             id=open_args['id'],
             name=open_args['name'],
             alias=open_args['alias'],
@@ -1028,10 +1072,10 @@ class Actor(metaclass=_ActorMeta):
 
         if open_args['id'] is None and open_args['name'] is None and open_args['alias'] is None:
             if cls._default_rq is None:
-                cls._default_rq = await RequestQueue.open(storage_client=storage_client)
+                cls._default_rq = await _lazy('RequestQueue').open(storage_client=storage_client)
             return cls._default_rq
 
-        return await RequestQueue.open(
+        return await _lazy('RequestQueue').open(
             id=open_args['id'],
             name=open_args['name'],
             alias=open_args['alias'],
@@ -1710,7 +1754,7 @@ class Actor(metaclass=_ActorMeta):
         if cls._event_manager:
             from crawlee.events import EventPersistStateData
             cls._event_manager.emit(
-                event=Event.PERSIST_STATE,
+                event=_lazy('Event').PERSIST_STATE,
                 event_data=EventPersistStateData(is_migrating=True),
             )
 

scrapely/patch_browser_pool.py

@@ -30,6 +30,11 @@ Mirrors the Node SDK ``patch-browser-pool.ts``:
   gVisor-safe Chromium args under ``SCRAPELY_CONTAINER_RUNTIME=runsc``.
 - Soft no-op when Playwright/Crawlee browsers are not installed (e.g. HTTP-only
   actors).
+- Crawlee is never imported by this module (it costs ~1 s under gVisor). The
+  Crawlee patches are applied at once when Crawlee's browser / Playwright
+  crawler modules are already loaded, otherwise by a post-import hook the
+  moment those modules finish loading — before actor code can use the classes.
+  The Playwright, Camoufox and pyppeteer patches are applied eagerly on import.
 
 Location and proxy handling (the remote browser never takes a proxy):
 
@@ -63,9 +68,11 @@ from __future__ import annotations
 
 import contextvars
 import functools
+import importlib.abc
 import logging
 import os
 import re
+import sys
 from typing import Any, List, Optional, Tuple
 from urllib.parse import SplitResult, parse_qsl, unquote, urlencode, urlsplit, urlunsplit
 
@@ -459,7 +466,9 @@ def _apply_crawler_patch() -> None:
     ``new_browser`` by the patched ``BrowserPool._get_new_page``.
     """
     try:
-        from crawlee.crawlers import PlaywrightCrawler
+        # The defining module, not the ``crawlee.crawlers`` package: the
+        # post-import hook runs this while that package is still initialising.
+        from crawlee.crawlers._playwright._playwright_crawler import PlaywrightCrawler
     except ImportError:
         return
 
@@ -865,8 +874,92 @@ def _apply_pyppeteer_patch() -> None:
     pyppeteer_mod._scrapely_cdp_patched = True
 
 
-_apply_patch()
-_apply_crawler_patch()
+# ─── Crawlee patches without importing Crawlee ───────────────────────────────
+#
+# Importing Crawlee costs ~1 s per run under gVisor, so this module never
+# imports it. The Crawlee patches mutate classes in place, so they only have to
+# run before actor code uses those classes: they are applied immediately when
+# the defining modules are already loaded, otherwise by a post-import hook the
+# moment they finish executing (``import crawlee.browsers``,
+# ``from crawlee.crawlers import PlaywrightCrawler``, a PlaywrightCrawler built
+# by any template...). Behaviour is the same as applying them eagerly.
+
+# Module name -> patch functions to run once that module has finished loading.
+# ``crawlee.browsers`` imports BrowserPool, PlaywrightBrowserController and
+# PlaywrightBrowserPlugin in its ``__init__``; any import of one of those
+# submodules runs that ``__init__`` to completion first.
+_CRAWLEE_POST_IMPORT_PATCHES: dict = {
+    'crawlee.browsers': (_apply_patch,),
+    'crawlee.crawlers._playwright._playwright_crawler': (_apply_crawler_patch,),
+}
+
+
+class _PostImportLoader(importlib.abc.Loader):
+    """Delegating loader that runs the Scrapely patches after the module executes."""
+
+    def __init__(self, loader: Any, patches: tuple) -> None:
+        self._loader = loader
+        self._patches = patches
+
+    def create_module(self, spec: Any) -> Any:
+        return self._loader.create_module(spec)
+
+    def exec_module(self, module: Any) -> None:
+        # Leave the module looking untouched (resource readers, reload, ...).
+        spec = getattr(module, '__spec__', None)
+        if spec is not None:
+            spec.loader = self._loader
+        try:
+            module.__loader__ = self._loader
+        except Exception:
+            pass
+        self._loader.exec_module(module)
+        for patch in self._patches:
+            patch()
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self._loader, name)
+
+
+class _CrawleePostImportFinder(importlib.abc.MetaPathFinder):
+    """Meta path finder that hooks the Crawlee modules in ``_CRAWLEE_POST_IMPORT_PATCHES``."""
+
+    def find_spec(self, fullname: str, path: Any = None, target: Any = None) -> Any:
+        patches = _CRAWLEE_POST_IMPORT_PATCHES.get(fullname)
+        if patches is None:
+            return None
+        for finder in sys.meta_path:
+            if finder is self or isinstance(finder, _CrawleePostImportFinder):
+                continue
+            find_spec = getattr(finder, 'find_spec', None)
+            if find_spec is None:
+                continue
+            spec = find_spec(fullname, path, target)
+            if spec is not None:
+                break
+        else:
+            return None
+        if spec.loader is None or not hasattr(spec.loader, 'exec_module'):
+            return spec
+        # One-shot: the patches are idempotent, but a module loads only once.
+        _CRAWLEE_POST_IMPORT_PATCHES.pop(fullname, None)
+        spec.loader = _PostImportLoader(spec.loader, patches)
+        return spec
+
+
+def _install_crawlee_patches() -> None:
+    """Apply the Crawlee patches now if Crawlee is loaded, else when it loads."""
+    for module_name in list(_CRAWLEE_POST_IMPORT_PATCHES):
+        if module_name in sys.modules:
+            for patch in _CRAWLEE_POST_IMPORT_PATCHES.pop(module_name):
+                patch()
+    if _CRAWLEE_POST_IMPORT_PATCHES and not any(
+        isinstance(finder, _CrawleePostImportFinder) for finder in sys.meta_path
+    ):
+        sys.meta_path.insert(0, _CrawleePostImportFinder())
+
+
+_install_crawlee_patches()
 _apply_camoufox_patch()
 _apply_raw_playwright_patch()
 _apply_pyppeteer_patch()

scrapely/storage/__init__.py

@@ -1,27 +1,92 @@
 """Scrapely storage: Crawlee StorageClient backends + HTTP helpers."""
 
-from crawlee import Request
-from crawlee.storage_clients import MemoryStorageClient, StorageClient
-from crawlee.storages import Dataset, KeyValueStore, RequestQueue
+from typing import TYPE_CHECKING, Any
 
+# Only the Crawlee-free HTTP helpers load eagerly, so ``Actor`` can use
+# ``scrapely.storage.api_client`` / ``.client`` without importing Crawlee.
+# The Crawlee StorageClient backends load on first attribute access.
 from .api_client import ApiClient, ApiClientError
 from .client import ApiStorageClient
-from ._file_system import ScrapelyFileSystemStorageClient
-from .patch_storage import (
-    disconnect_storage,
-    get_api_storage_factory,
-    get_auto_saved_value,
-    get_smart_storage_client,
-    is_api_storage_configured,
-    persist_autosaved_values,
-    set_api_storage,
-    set_storage_client,
-)
-from .scrapely_storage_client import ScrapelyStorageClient
-from .smart_scrapely_storage_client import SmartScrapelyStorageClient
-
-# Apify-style public alias
-FileSystemStorageClient = ScrapelyFileSystemStorageClient
+
+_LAZY_ATTRS = {
+    'Request': ('crawlee', 'Request'),
+    'MemoryStorageClient': ('crawlee.storage_clients', 'MemoryStorageClient'),
+    'StorageClient': ('crawlee.storage_clients', 'StorageClient'),
+    'Dataset': ('crawlee.storages', 'Dataset'),
+    'KeyValueStore': ('crawlee.storages', 'KeyValueStore'),
+    'RequestQueue': ('crawlee.storages', 'RequestQueue'),
+    'ScrapelyFileSystemStorageClient': ('scrapely.storage._file_system', 'ScrapelyFileSystemStorageClient'),
+    # Apify-style public alias
+    'FileSystemStorageClient': ('scrapely.storage._file_system', 'ScrapelyFileSystemStorageClient'),
+    'ScrapelyStorageClient': ('scrapely.storage.scrapely_storage_client', 'ScrapelyStorageClient'),
+    'SmartScrapelyStorageClient': ('scrapely.storage.smart_scrapely_storage_client', 'SmartScrapelyStorageClient'),
+    **{
+        name: ('scrapely.storage.patch_storage', name)
+        for name in (
+            'disconnect_storage',
+            'get_api_storage_factory',
+            'get_auto_saved_value',
+            'get_smart_storage_client',
+            'is_api_storage_configured',
+            'persist_autosaved_values',
+            'set_api_storage',
+            'set_storage_client',
+        )
+    },
+}
+
+# Submodules that used to be bound as attributes by this package's eager imports.
+_LAZY_SUBMODULES = frozenset({
+    '_file_system',
+    '_metadata',
+    'patch_storage',
+    'scrapely_dataset_client',
+    'scrapely_kvs_client',
+    'scrapely_rq_client',
+    'scrapely_storage_client',
+    'smart_scrapely_storage_client',
+    'utils',
+})
+
+
+def __getattr__(name: str) -> Any:
+    target = _LAZY_ATTRS.get(name)
+    if target is not None:
+        import importlib
+
+        value = getattr(importlib.import_module(target[0]), target[1])
+        globals()[name] = value
+        return value
+    if name in _LAZY_SUBMODULES:
+        import importlib
+
+        return importlib.import_module(f'{__name__}.{name}')
+    raise AttributeError(f'module {__name__!r} has no attribute {name!r}')
+
+
+def __dir__() -> list:
+    return sorted(set(globals()) | set(_LAZY_ATTRS) | _LAZY_SUBMODULES)
+
+
+if TYPE_CHECKING:
+    from crawlee import Request
+    from crawlee.storage_clients import MemoryStorageClient, StorageClient
+    from crawlee.storages import Dataset, KeyValueStore, RequestQueue
+
+    from ._file_system import ScrapelyFileSystemStorageClient
+    from ._file_system import ScrapelyFileSystemStorageClient as FileSystemStorageClient
+    from .patch_storage import (
+        disconnect_storage,
+        get_api_storage_factory,
+        get_auto_saved_value,
+        get_smart_storage_client,
+        is_api_storage_configured,
+        persist_autosaved_values,
+        set_api_storage,
+        set_storage_client,
+    )
+    from .scrapely_storage_client import ScrapelyStorageClient
+    from .smart_scrapely_storage_client import SmartScrapelyStorageClient
 
 __all__ = [
     'ApiClient',

{scrapely_python-0.1.22.dist-info → scrapely_python-0.1.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scrapely-python
-Version: 0.1.22
+Version: 0.1.23
 Summary: Scrapely Python SDK - A toolkit for building Actors on the Scrapely platform
 Author-email: Scrapely <support@scrape.ly>
 License-Expression: MIT AND Apache-2.0

{scrapely_python-0.1.22.dist-info → scrapely_python-0.1.23.dist-info}/RECORD

@@ -1,6 +1,6 @@
-scrapely/__init__.py,sha256=cxlsfPD_FlaCCerWYImS5rGRnKxE9INU61hDl3C04Y0,5746
+scrapely/__init__.py,sha256=urKlJYfwafwGuUNCaDEPM0wK5H_krI8jYNKys8dsh9U,9661
 scrapely/_browser_locations.py,sha256=8QVVnkms2bDn3_LDYgYDR59MvFx8757l_JYnZ7xb3oI,145269
-scrapely/actor.py,sha256=yLy05XzoFwslw0D4aSM38rDIGd81JvPqpngY467hWxQ,82969
+scrapely/actor.py,sha256=fNxlB2KxattbBh6aMo1p_ALrDQ3GdbJa03w_6DgIkjs,85310
 scrapely/browser_configuration.py,sha256=jAZapNSHLFW05B96df4wNBtcyiiU9DA3ml0yTL1FwfA,5770
 scrapely/cdp_retry.py,sha256=hdTJEAIKhApM7IOk1DrQEl8NoflSJSmqd4RbNJ2IsgI,8540
 scrapely/charging.py,sha256=ns-kuUJtl8hBI4-3iBisC62BggJG67yYOa1yVVItoUI,83800
@@ -8,7 +8,7 @@ scrapely/charging_client.py,sha256=-4q-Ww7gu9EZXpM9QIn1Vd4vwAXmgL_WEKqaQIx3ViA,3
 scrapely/configuration.py,sha256=Of-lKm7hoPGUQO8d08kV7fAy2co9QTfb8Of_8ds5PSA,17028
 scrapely/errors.py,sha256=DCAlVvE3jToZuPEG2HVDL7i8D8hLboomQ5JpSOcsXoQ,4107
 scrapely/log.py,sha256=iVKoQdMLQXEWz1STzbSXrNUxsS_FNwiIdqoEg7CzeqU,1440
-scrapely/patch_browser_pool.py,sha256=qZstdQ1rFw8kGjzB9fm3GXco8Jt40eklTw1Czf_vh-8,38018
+scrapely/patch_browser_pool.py,sha256=R-1QDKa-ZvfdQ9wgyA8JCtmQqD9v7dOsaCZnSUoyf7U,42214
 scrapely/pricing_types.py,sha256=J6wCddZd-U1MYeOtaaEdeHSsp1HBgiQLfvSInBOvhIo,5305
 scrapely/proxy_configuration.py,sha256=4passyiUBfBsuzaBDyf5003rY0ayLYwwSnev0FaxCs0,38125
 scrapely/py.typed,sha256=XtWlywqUjc6x_M2gAXlDtYXbAsYkCjKZEjFyJvaHvm4,105
@@ -22,7 +22,7 @@ scrapely/events/_types.py,sha256=XslMIEAQOe7othqevnxO86c7i7AysbvDLHH0lep64QU,599
 scrapely/events/event_manager.py,sha256=9x3VqNy1gBi5tNQRv_1KptCRJQ9QnPwCDLT7JdlvjIM,12774
 scrapely/request_loaders/__init__.py,sha256=aNgr4pRt3MziUbU6UQ_bjTT3moMNvvyUsPeCJyMQcwU,196
 scrapely/request_loaders/_scrapely_request_list.py,sha256=vguj-EvBjvrGY5_vf2fGXnJBfnhlPeRjdkjPFaxUA7g,7628
-scrapely/storage/__init__.py,sha256=diAhxEvOXjc3YVhZvzkO3MttJUXQWJ5ogxstiApsh7U,1405
+scrapely/storage/__init__.py,sha256=GWVzHJPlcsZp0bDCZwvYFwQD-JXSkoEYGLOFC1siLYw,3852
 scrapely/storage/_metadata.py,sha256=WWawBnVN0b1iK2K-SlxZXUc6czb5wXWf8iC_0tzkgAQ,4764
 scrapely/storage/api_client.py,sha256=uhIU5LnOmW0x6MOMt1H7iWlvs-b55Sn4zVCgAnynTug,22900
 scrapely/storage/client.py,sha256=dfTD3424kb0AAFdFU5F6HMcS2XaKcJ1ACiViYniKDXg,22562
@@ -39,10 +39,10 @@ scrapely/storage/_file_system/_key_value_store_client.py,sha256=4Ipgbh4qEqAkwQJ9
 scrapely/storage/_file_system/_storage_client.py,sha256=aaGJ4P0QAtIgEMl6yHpuobeWFD5M4rMC5HwhOOvuGuo,1794
 scrapely/storage_clients/__init__.py,sha256=cs1YX7JV2_GKBXeiiJgkQFali08b5_y_jH6Yw7iROAA,656
 scrapely/storages/__init__.py,sha256=4PAELhJNZ3exJ7Uouicn-bCQ58NafKjhLBixQ8ATQc4,173
-scrapely_python-0.1.22.dist-info/licenses/LICENSE,sha256=pQGY0XwjIYh-a2HfawxHq1en53bXkFkDj2Q70jKWHr4,1088
-scrapely_python-0.1.22.dist-info/licenses/LICENSE-APACHE,sha256=N8m0FzMq8i4UbTgXZvKEZJSD-27OF8pWZYS_atz4kTU,11355
-scrapely_python-0.1.22.dist-info/licenses/NOTICE,sha256=DEsNrw6UdSIqdYYqMWVFgJnyt6jUivTD7iFU6YM_e1A,1122
-scrapely_python-0.1.22.dist-info/METADATA,sha256=K-JZZELeDs7kIXmXodCXXVF3YCvozeqESmkQ5StszVw,3487
-scrapely_python-0.1.22.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-scrapely_python-0.1.22.dist-info/top_level.txt,sha256=T4B9UMrs4q99QSAFyD1zdXhl40KnLhBKqrDkPhOTsmY,9
-scrapely_python-0.1.22.dist-info/RECORD,,
+scrapely_python-0.1.23.dist-info/licenses/LICENSE,sha256=pQGY0XwjIYh-a2HfawxHq1en53bXkFkDj2Q70jKWHr4,1088
+scrapely_python-0.1.23.dist-info/licenses/LICENSE-APACHE,sha256=N8m0FzMq8i4UbTgXZvKEZJSD-27OF8pWZYS_atz4kTU,11355
+scrapely_python-0.1.23.dist-info/licenses/NOTICE,sha256=DEsNrw6UdSIqdYYqMWVFgJnyt6jUivTD7iFU6YM_e1A,1122
+scrapely_python-0.1.23.dist-info/METADATA,sha256=AY2FmyNKFInqRuBqZ2HnLSUVjz-UZ4bKeRTV5OsgPTU,3487
+scrapely_python-0.1.23.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+scrapely_python-0.1.23.dist-info/top_level.txt,sha256=T4B9UMrs4q99QSAFyD1zdXhl40KnLhBKqrDkPhOTsmY,9
+scrapely_python-0.1.23.dist-info/RECORD,,