apify 2.2.2b1__py3-none-any.whl → 2.3.0__py3-none-any.whl

apify/_actor.py

@@ -24,6 +24,7 @@ from crawlee.events import (
     EventSystemInfoData,
 )
 
+from apify._charging import ChargeResult, ChargingManager, ChargingManagerImplementation
 from apify._configuration import Configuration
 from apify._consts import EVENT_LISTENERS_TIMEOUT
 from apify._crypto import decrypt_input_secrets, load_private_key
@@ -55,10 +56,8 @@ MainReturnType = TypeVar('MainReturnType')
 class _ActorType:
     """The class of `Actor`. Only make a new instance if you're absolutely sure you need to."""
 
-    _apify_client: ApifyClientAsync
-    _configuration: Configuration
-    _is_exiting = False
     _is_rebooting = False
+    _is_any_instance_initialized = False
 
     def __init__(
         self,
@@ -76,6 +75,8 @@ class _ActorType:
                 be created.
             configure_logging: Should the default logging configuration be configured?
         """
+        self._is_exiting = False
+
         self._configuration = configuration or Configuration.get_global_configuration()
         self._configure_logging = configure_logging
         self._apify_client = self.new_client()
@@ -97,6 +98,8 @@ class _ActorType:
             )
         )
 
+        self._charging_manager = ChargingManagerImplementation(self._configuration, self._apify_client)
+
         self._is_initialized = False
 
     @ignore_docs
@@ -200,6 +203,12 @@ class _ActorType:
         if self._is_initialized:
             raise RuntimeError('The Actor was already initialized!')
 
+        if _ActorType._is_any_instance_initialized:
+            self.log.warning('Repeated Actor initialization detected - this is non-standard usage, proceed with care')
+
+        # Make sure that the currently initialized instance is also available through the global `Actor` proxy
+        cast(Proxy, Actor).__wrapped__ = self
+
         self._is_exiting = False
         self._was_final_persist_state_emitted = False
 
@@ -221,8 +230,13 @@ class _ActorType:
         # https://github.com/apify/apify-sdk-python/issues/146
 
         await self._event_manager.__aenter__()
+        self.log.debug('Event manager initialized')
+
+        await self._charging_manager.__aenter__()
+        self.log.debug('Charging manager initialized')
 
         self._is_initialized = True
+        _ActorType._is_any_instance_initialized = True
 
     async def exit(
         self,
@@ -262,6 +276,7 @@ class _ActorType:
                 await self._event_manager.wait_for_all_listeners_to_complete(timeout=event_listeners_timeout)
 
             await self._event_manager.__aexit__(None, None, None)
+            await self._charging_manager.__aexit__(None, None, None)
 
         await asyncio.wait_for(finalize(), cleanup_timeout.total_seconds())
         self._is_initialized = False
@@ -270,8 +285,8 @@ class _ActorType:
             self.log.debug(f'Not calling sys.exit({exit_code}) because Actor is running in IPython')
         elif os.getenv('PYTEST_CURRENT_TEST', default=False):  # noqa: PLW1508
             self.log.debug(f'Not calling sys.exit({exit_code}) because Actor is running in an unit test')
-        elif hasattr(asyncio, '_nest_patched'):
-            self.log.debug(f'Not calling sys.exit({exit_code}) because Actor is running in a nested event loop')
+        elif os.getenv('SCRAPY_SETTINGS_MODULE'):
+            self.log.debug(f'Not calling sys.exit({exit_code}) because Actor is running with Scrapy')
         else:
             sys.exit(exit_code)
 
@@ -445,19 +460,46 @@ class _ActorType:
             storage_client=storage_client,
         )
 
-    async def push_data(self, data: dict | list[dict]) -> None:
+    @overload
+    async def push_data(self, data: dict | list[dict]) -> None: ...
+    @overload
+    async def push_data(self, data: dict | list[dict], charged_event_name: str) -> ChargeResult: ...
+    async def push_data(self, data: dict | list[dict], charged_event_name: str | None = None) -> ChargeResult | None:
         """Store an object or a list of objects to the default dataset of the current Actor run.
 
         Args:
             data: The data to push to the default dataset.
+            charged_event_name: If provided and if the Actor uses the pay-per-event pricing model,
+                the method will attempt to charge for the event for each pushed item.
         """
         self._raise_if_not_initialized()
 
         if not data:
-            return
+            return None
+
+        data = data if isinstance(data, list) else [data]
+
+        max_charged_count = (
+            self._charging_manager.calculate_max_event_charge_count_within_limit(charged_event_name)
+            if charged_event_name is not None
+            else None
+        )
 
         dataset = await self.open_dataset()
-        await dataset.push_data(data)
+
+        if max_charged_count is not None and len(data) > max_charged_count:
+            # Push as many items as we can charge for
+            await dataset.push_data(data[:max_charged_count])
+        else:
+            await dataset.push_data(data)
+
+        if charged_event_name:
+            return await self._charging_manager.charge(
+                event_name=charged_event_name,
+                count=min(max_charged_count, len(data)) if max_charged_count is not None else len(data),
+            )
+
+        return None
 
     async def get_input(self) -> Any:
         """Get the Actor input value from the default key-value store associated with the current Actor run."""
@@ -506,6 +548,23 @@ class _ActorType:
         key_value_store = await self.open_key_value_store()
         return await key_value_store.set_value(key, value, content_type=content_type)
 
+    def get_charging_manager(self) -> ChargingManager:
+        """Retrieve the charging manager to access granular pricing information."""
+        self._raise_if_not_initialized()
+        return self._charging_manager
+
+    async def charge(self, event_name: str, count: int = 1) -> ChargeResult:
+        """Charge for a specified number of events - sub-operations of the Actor.
+
+        This is relevant only for the pay-per-event pricing model.
+
+        Args:
+            event_name: Name of the event to be charged for.
+            count: Number of events to charge for.
+        """
+        self._raise_if_not_initialized()
+        return await self._charging_manager.charge(event_name, count)
+
     @overload
     def on(
         self, event_name: Literal[Event.PERSIST_STATE], listener: EventListener[EventPersistStateData]
@@ -898,11 +957,11 @@ class _ActorType:
             self.log.error('Actor.reboot() is only supported when running on the Apify platform.')
             return
 
-        if self._is_rebooting:
+        if _ActorType._is_rebooting:
             self.log.debug('Actor is already rebooting, skipping the additional reboot call.')
             return
 
-        self._is_rebooting = True
+        _ActorType._is_rebooting = True
 
         if not custom_after_sleep:
             custom_after_sleep = self._configuration.metamorph_after_sleep

apify/_charging.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from decimal import Decimal
+from typing import TYPE_CHECKING, Protocol, Union
+
+from pydantic import TypeAdapter
+
+from apify_shared.utils import ignore_docs
+from crawlee._utils.context import ensure_context
+
+from apify._models import ActorRun, PricingModel
+from apify._utils import docs_group
+from apify.log import logger
+from apify.storages import Dataset
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from apify_client import ApifyClientAsync
+
+    from apify._configuration import Configuration
+
+
+run_validator: TypeAdapter[ActorRun | None] = TypeAdapter(Union[ActorRun, None])
+
+
+@docs_group('Interfaces')
+class ChargingManager(Protocol):
+    """Provides fine-grained access to pay-per-event functionality."""
+
+    async def charge(self, event_name: str, count: int = 1) -> ChargeResult:
+        """Charge for a specified number of events - sub-operations of the Actor.
+
+        This is relevant only for the pay-per-event pricing model.
+
+        Args:
+            event_name: Name of the event to be charged for.
+            count: Number of events to charge for.
+        """
+
+    def calculate_total_charged_amount(self) -> Decimal:
+        """Calculate the total amount of money charged for pay-per-event events so far."""
+
+    def calculate_max_event_charge_count_within_limit(self, event_name: str) -> int | None:
+        """Calculate how many instances of an event can be charged before we reach the configured limit.
+
+        Args:
+            event_name: Name of the inspected event.
+        """
+
+    def get_pricing_info(self) -> ActorPricingInfo:
+        """Retrieve detailed information about the effective pricing of the current Actor run.
+
+        This can be used for instance when your code needs to support multiple pricing models in transition periods.
+        """
+
+
+@docs_group('Data structures')
+@dataclass(frozen=True)
+class ChargeResult:
+    """Result of the `ChargingManager.charge` method."""
+
+    event_charge_limit_reached: bool
+    """If true, no more events of this type can be charged within the limit."""
+
+    charged_count: int
+    """Total amount of charged events - may be lower than the requested amount."""
+
+    chargeable_within_limit: dict[str, int | None]
+    """How many events of each known type can still be charged within the limit."""
+
+
+@docs_group('Data structures')
+@dataclass
+class ActorPricingInfo:
+    """Result of the `ChargingManager.get_pricing_info` method."""
+
+    pricing_model: PricingModel | None
+    """The currently effective pricing model."""
+
+    max_total_charge_usd: Decimal
+    """A configured limit for the total charged amount - if you exceed it, you won't receive more money than this."""
+
+    is_pay_per_event: bool
+    """A shortcut - true if the Actor runs with the pay-per-event pricing model."""
+
+    per_event_prices: dict[str, Decimal]
+    """Price of every known event type."""
+
+
+@ignore_docs
+class ChargingManagerImplementation(ChargingManager):
+    """Implementation of the `ChargingManager` Protocol - this is only meant to be instantiated internally."""
+
+    LOCAL_CHARGING_LOG_DATASET_NAME = 'charging_log'
+
+    def __init__(self, configuration: Configuration, client: ApifyClientAsync) -> None:
+        self._max_total_charge_usd = configuration.max_total_charge_usd or Decimal('inf')
+        self._is_at_home = configuration.is_at_home
+        self._actor_run_id = configuration.actor_run_id
+        self._purge_charging_log_dataset = configuration.purge_on_start
+        self._pricing_model: PricingModel | None = None
+
+        if configuration.test_pay_per_event:
+            if self._is_at_home:
+                raise ValueError(
+                    'Using the ACTOR_TEST_PAY_PER_EVENT environment variable is only supported '
+                    'in a local development environment'
+                )
+
+            self._pricing_model = 'PAY_PER_EVENT'
+
+        self._client = client
+        self._charging_log_dataset: Dataset | None = None
+
+        self._charging_state: dict[str, ChargingStateItem] = {}
+        self._pricing_info: dict[str, PricingInfoItem] = {}
+
+        self._not_ppe_warning_printed = False
+        self.active = False
+
+    async def __aenter__(self) -> None:
+        """Initialize the charging manager - this is called by the `Actor` class and shouldn't be invoked manually."""
+        self.active = True
+
+        if self._is_at_home:
+            # Running on the Apify platform - fetch pricing info for the current run.
+
+            if self._actor_run_id is None:
+                raise RuntimeError('Actor run ID not found even though the Actor is running on Apify')
+
+            run = run_validator.validate_python(await self._client.run(self._actor_run_id).get())
+            if run is None:
+                raise RuntimeError('Actor run not found')
+
+            if run.pricing_info is not None:
+                self._pricing_model = run.pricing_info.pricing_model
+
+                if run.pricing_info.pricing_model == 'PAY_PER_EVENT':
+                    for event_name, event_pricing in run.pricing_info.pricing_per_event.actor_charge_events.items():
+                        self._pricing_info[event_name] = PricingInfoItem(
+                            price=event_pricing.event_price_usd,
+                            title=event_pricing.event_title,
+                        )
+
+                    self._max_total_charge_usd = run.options.max_total_charge_usd or self._max_total_charge_usd
+
+            for event_name, count in (run.charged_event_counts or {}).items():
+                price = self._pricing_info.get(event_name, PricingInfoItem(Decimal(), title='')).price
+                self._charging_state[event_name] = ChargingStateItem(
+                    charge_count=count,
+                    total_charged_amount=count * price,
+                )
+
+        if not self._is_at_home and self._pricing_model == 'PAY_PER_EVENT':
+            # We are not running on the Apify platform, but PPE is enabled for testing - open a dataset that
+            # will contain a log of all charge calls for debugging purposes.
+
+            if self._purge_charging_log_dataset:
+                dataset = await Dataset.open(name=self.LOCAL_CHARGING_LOG_DATASET_NAME)
+                await dataset.drop()
+
+            self._charging_log_dataset = await Dataset.open(name=self.LOCAL_CHARGING_LOG_DATASET_NAME)
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        exc_traceback: TracebackType | None,
+    ) -> None:
+        if not self.active:
+            raise RuntimeError('Exiting an uninitialized ChargingManager')
+
+        self.active = False
+
+    @ensure_context
+    async def charge(self, event_name: str, count: int = 1) -> ChargeResult:
+        def calculate_chargeable() -> dict[str, int | None]:
+            """Calculate the maximum number of events of each type that can be charged within the current budget."""
+            return {
+                event_name: self.calculate_max_event_charge_count_within_limit(event_name)
+                for event_name in self._pricing_info
+            }
+
+        # For runs that do not use the pay-per-event pricing model, just print a warning and return
+        if self._pricing_model != 'PAY_PER_EVENT':
+            if not self._not_ppe_warning_printed:
+                logger.warning(
+                    'Ignored attempt to charge for an event - the Actor does not use the pay-per-event pricing'
+                )
+                self._not_ppe_warning_printed = True
+
+            return ChargeResult(
+                event_charge_limit_reached=False,
+                charged_count=0,
+                chargeable_within_limit=calculate_chargeable(),
+            )
+
+        # START OF CRITICAL SECTION - no awaits here
+
+        # Determine the maximum amount of events that can be charged within the budget
+        charged_count = min(count, self.calculate_max_event_charge_count_within_limit(event_name) or count)
+
+        if charged_count == 0:
+            return ChargeResult(
+                event_charge_limit_reached=True,
+                charged_count=0,
+                chargeable_within_limit=calculate_chargeable(),
+            )
+
+        pricing_info = self._pricing_info.get(
+            event_name,
+            PricingInfoItem(
+                price=Decimal()
+                if self._is_at_home
+                else Decimal(
+                    '1'
+                ),  # Use a nonzero price for local development so that the maximum budget can be reached,
+                title=f"Unknown event '{event_name}'",
+            ),
+        )
+
+        # Update the charging state
+        self._charging_state.setdefault(event_name, ChargingStateItem(0, Decimal()))
+        self._charging_state[event_name].charge_count += charged_count
+        self._charging_state[event_name].total_charged_amount += charged_count * pricing_info.price
+
+        # END OF CRITICAL SECTION
+
+        # If running on the platform, call the charge endpoint
+        if self._is_at_home:
+            if self._actor_run_id is None:
+                raise RuntimeError('Actor run ID not configured')
+
+            if event_name in self._pricing_info:
+                await self._client.run(self._actor_run_id).charge(event_name, charged_count)
+            else:
+                logger.warning(f"Attempting to charge for an unknown event '{event_name}'")
+
+        # Log the charged operation (if enabled)
+        if self._charging_log_dataset:
+            await self._charging_log_dataset.push_data(
+                {
+                    'event_name': event_name,
+                    'event_title': pricing_info.title,
+                    'event_price_usd': round(pricing_info.price, 3),
+                    'charged_count': charged_count,
+                    'timestamp': datetime.now(timezone.utc).isoformat(),
+                }
+            )
+
+        # If it is not possible to charge the full amount, log that fact
+        if charged_count < count:
+            subject = 'instance' if count == 1 else 'instances'
+            logger.info(
+                f"Charging {count} ${subject} of '{event_name}' event would exceed max_total_charge_usd "
+                '- only {charged_count} events were charged'
+            )
+
+        max_charge_count = self.calculate_max_event_charge_count_within_limit(event_name)
+
+        return ChargeResult(
+            event_charge_limit_reached=max_charge_count is not None and max_charge_count <= 0,
+            charged_count=charged_count,
+            chargeable_within_limit=calculate_chargeable(),
+        )
+
+    @ensure_context
+    def calculate_total_charged_amount(self) -> Decimal:
+        return sum(
+            (item.total_charged_amount for item in self._charging_state.values()),
+            start=Decimal(),
+        )
+
+    @ensure_context
+    def calculate_max_event_charge_count_within_limit(self, event_name: str) -> int | None:
+        pricing_info = self._pricing_info.get(event_name)
+
+        if pricing_info is not None:
+            price = pricing_info.price
+        elif not self._is_at_home:
+            price = Decimal('1')  # Use a nonzero price for local development so that the maximum budget can be reached
+        else:
+            price = Decimal()
+
+        if not price:
+            return None
+
+        result = (self._max_total_charge_usd - self.calculate_total_charged_amount()) / price
+        return math.floor(result) if result.is_finite() else None
+
+    @ensure_context
+    def get_pricing_info(self) -> ActorPricingInfo:
+        return ActorPricingInfo(
+            pricing_model=self._pricing_model,
+            is_pay_per_event=self._pricing_model == 'PAY_PER_EVENT',
+            max_total_charge_usd=self._max_total_charge_usd
+            if self._max_total_charge_usd is not None
+            else Decimal('inf'),
+            per_event_prices={
+                event_name: pricing_info.price for event_name, pricing_info in self._pricing_info.items()
+            },
+        )
+
+
+@dataclass
+class ChargingStateItem:
+    charge_count: int
+    total_charged_amount: Decimal
+
+
+@dataclass
+class PricingInfoItem:
+    price: Decimal
+    title: str

apify/_configuration.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from datetime import datetime, timedelta
+from decimal import Decimal
 from logging import getLogger
 from typing import Annotated, Any
 
@@ -212,7 +213,7 @@ class Configuration(CrawleeConfiguration):
     ] = None
 
     max_total_charge_usd: Annotated[
-        float | None,
+        Decimal | None,
         Field(
             alias='actor_max_total_charge_usd',
             description='For pay-per-event Actors, the user-set limit on total charges. Do not exceed this limit',
@@ -220,6 +221,14 @@ class Configuration(CrawleeConfiguration):
         BeforeValidator(lambda val: val or None),
     ] = None
 
+    test_pay_per_event: Annotated[
+        bool,
+        Field(
+            alias='actor_test_pay_per_event',
+            description='Enable pay-per-event functionality for local development',
+        ),
+    ] = False
+
     meta_origin: Annotated[
         str | None,
         Field(

apify/_models.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
 from datetime import datetime, timedelta
-from typing import Annotated
+from decimal import Decimal
+from typing import TYPE_CHECKING, Annotated, Literal
 
 from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
 
@@ -11,6 +12,9 @@ from crawlee._utils.urls import validate_http_url
 
 from apify._utils import docs_group
 
+if TYPE_CHECKING:
+    from typing_extensions import TypeAlias
+
 
 @docs_group('Data structures')
 class Webhook(BaseModel):
@@ -67,6 +71,7 @@ class ActorRunOptions(BaseModel):
     timeout: Annotated[timedelta, Field(alias='timeoutSecs')]
     memory_mbytes: Annotated[int, Field(alias='memoryMbytes')]
     disk_mbytes: Annotated[int, Field(alias='diskMbytes')]
+    max_total_charge_usd: Annotated[Decimal | None, Field(alias='maxTotalChargeUsd')] = None
 
 
 @docs_group('Data structures')
@@ -115,3 +120,55 @@ class ActorRun(BaseModel):
     usage: Annotated[ActorRunUsage | None, Field(alias='usage')] = None
     usage_total_usd: Annotated[float | None, Field(alias='usageTotalUsd')] = None
     usage_usd: Annotated[ActorRunUsage | None, Field(alias='usageUsd')] = None
+    pricing_info: Annotated[
+        FreeActorPricingInfo
+        | FlatPricePerMonthActorPricingInfo
+        | PricePerDatasetItemActorPricingInfo
+        | PayPerEventActorPricingInfo
+        | None,
+        Field(alias='pricingInfo', discriminator='pricing_model'),
+    ] = None
+    charged_event_counts: Annotated[
+        dict[str, int] | None,
+        Field(alias='chargedEventCounts'),
+    ] = None
+
+
+class FreeActorPricingInfo(BaseModel):
+    pricing_model: Annotated[Literal['FREE'], Field(alias='pricingModel')]
+
+
+class FlatPricePerMonthActorPricingInfo(BaseModel):
+    pricing_model: Annotated[Literal['FLAT_PRICE_PER_MONTH'], Field(alias='pricingModel')]
+    trial_minutes: Annotated[int | None, Field(alias='trialMinutes')] = None
+    price_per_unit_usd: Annotated[Decimal, Field(alias='pricePerUnitUsd')]
+
+
+class PricePerDatasetItemActorPricingInfo(BaseModel):
+    pricing_model: Annotated[Literal['PRICE_PER_DATASET_ITEM'], Field(alias='pricingModel')]
+    unit_name: Annotated[str | None, Field(alias='unitName')] = None
+    price_per_unit_usd: Annotated[Decimal, Field(alias='pricePerUnitUsd')]
+
+
+class ActorChargeEvent(BaseModel):
+    event_price_usd: Annotated[Decimal, Field(alias='eventPriceUsd')]
+    event_title: Annotated[str, Field(alias='eventTitle')]
+    event_description: Annotated[str | None, Field(alias='eventDescription')] = None
+
+
+class PricingPerEvent(BaseModel):
+    actor_charge_events: Annotated[dict[str, ActorChargeEvent], Field(alias='actorChargeEvents')]
+
+
+class PayPerEventActorPricingInfo(BaseModel):
+    pricing_model: Annotated[Literal['PAY_PER_EVENT'], Field(alias='pricingModel')]
+    pricing_per_event: Annotated[PricingPerEvent, Field(alias='pricingPerEvent')]
+    minimal_max_total_charge_usd: Annotated[Decimal | None, Field(alias='minimalMaxTotalChargeUsd')] = None
+
+
+PricingModel: TypeAlias = Literal[
+    'FREE',
+    'FLAT_PRICE_PER_MONTH',
+    'PRICE_PER_DATASET_ITEM',
+    'PAY_PER_EVENT',
+]

apify/_utils.py

@@ -27,7 +27,7 @@ def is_running_in_ipython() -> bool:
     return getattr(builtins, '__IPYTHON__', False)
 
 
-GroupName = Literal['Classes', 'Abstract classes', 'Data structures', 'Errors', 'Functions']
+GroupName = Literal['Classes', 'Abstract classes', 'Interfaces', 'Data structures', 'Errors', 'Functions']
 
 
 def docs_group(group_name: GroupName) -> Callable:  # noqa: ARG001

apify/apify_storage_client/_apify_storage_client.py

@@ -66,3 +66,7 @@ class ApifyStorageClient(BaseStorageClient):
     @override
     async def purge_on_start(self) -> None:
         pass
+
+    @override
+    def get_rate_limit_errors(self) -> dict[int, int]:  # type: ignore[misc]
+        return self._apify_client.stats.rate_limit_errors

apify/scrapy/__init__.py

@@ -1,11 +1,32 @@
-from apify.scrapy.requests import to_apify_request, to_scrapy_request
-from apify.scrapy.scheduler import ApifyScheduler
-from apify.scrapy.utils import get_basic_auth_header, get_running_event_loop_id
+from crawlee._utils.try_import import install_import_hook as _install_import_hook
+from crawlee._utils.try_import import try_import as _try_import
+
+_install_import_hook(__name__)
+
+# The following imports use try_import to handle optional dependencies, as they may not always be available.
+
+with _try_import(__name__, 'run_scrapy_actor'):
+    from ._actor_runner import run_scrapy_actor
+
+with _try_import(__name__, 'initialize_logging'):
+    from ._logging_config import initialize_logging
+
+with _try_import(__name__, 'to_apify_request', 'to_scrapy_request'):
+    from .requests import to_apify_request, to_scrapy_request
+
+with _try_import(__name__, 'ApifyScheduler'):
+    from .scheduler import ApifyScheduler
+
+with _try_import(__name__, 'apply_apify_settings', 'get_basic_auth_header'):
+    from .utils import apply_apify_settings, get_basic_auth_header
+
 
 __all__ = [
     'ApifyScheduler',
+    'apply_apify_settings',
     'get_basic_auth_header',
-    'get_running_event_loop_id',
+    'initialize_logging',
+    'run_scrapy_actor',
     'to_apify_request',
     'to_scrapy_request',
 ]

apify/scrapy/_actor_runner.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from twisted.internet.defer import Deferred, ensureDeferred
+from twisted.internet.task import react
+
+if TYPE_CHECKING:
+    from collections.abc import Coroutine
+
+
+async def _run_coro_as_deferred(coro: Coroutine) -> None:
+    """Wrap the given asyncio coroutine in a Task and await its result as a Twisted Deferred."""
+    task = asyncio.ensure_future(coro)
+    await Deferred.fromFuture(task)
+
+
+def run_scrapy_actor(coro: Coroutine) -> None:
+    """Start Twisted's reactor and execute the provided Actor coroutine.
+
+    This function initiates the Twisted reactor and runs the given asyncio coroutine (typically the
+    Actor's main) by converting it to a Deferred. This bridges the asyncio and Twisted event loops,
+    enabling the Apify and Scrapy integration to work together.
+    """
+    react(lambda _: ensureDeferred(_run_coro_as_deferred(coro)))