
    Ki                        U d Z ddlmZ ddlmZmZmZ ddlmZ ddlm	Z	 ddl
mZ ddlmZ erdd	l
mZ d
dlmZ ddddddddZded<    G d de      Zy)z!Cron-style scheduling dependency.    )annotations)datetimetimezonetzinfo)TYPE_CHECKING)CronSim   )current_execution)	Perpetual)TaskOutcome   )	Executionz	0 0 1 1 *z	0 0 1 * *z	0 0 * * 0z	0 0 * * *z	0 * * * *)z@yearlyz	@annuallyz@monthlyz@weeklyz@dailyz	@midnightz@hourlyzdict[str, str]VIXIE_KEYWORDSc                       e Zd ZU dZded<   ded<   ded<   dej                  f	 	 	 	 	 	 	 d fd	Zdd
ZddZ	e
dd       Zd fdZ xZS )Cronac  Declare a task that should run on a cron schedule. Cron tasks are automatically
    rescheduled for the next matching time after they finish (whether they succeed or
    fail). By default, a cron task is scheduled at worker startup with `automatic=True`.

    Unlike `Perpetual` which schedules based on intervals from the current time, `Cron`
    schedules based on wall-clock time, ensuring tasks run at consistent times regardless
    of execution duration or delays.

    Supports standard cron expressions and Vixie cron-style keywords (@daily, @hourly, etc.).

    Example:

    ```python
    from zoneinfo import ZoneInfo

    @task
    async def weekly_report(cron: Cron = Cron("0 9 * * 1")) -> None:
        # Runs every Monday at 9:00 AM UTC
        ...

    @task
    async def daily_cleanup(cron: Cron = Cron("@daily")) -> None:
        # Runs every day at midnight UTC
        ...

    @task
    async def morning_standup(
        cron: Cron = Cron("0 9 * * 1-5", tz=ZoneInfo("America/Los_Angeles"))
    ) -> None:
        # Runs weekdays at 9:00 AM Pacific (handles DST automatically)
        ...
    ```
    str
expressionr   tzr   	_iteratorTc                    t         |   |       t        j                  ||      | _        || _        t        | j                  t        j                  | j
                              | _	        y)a  
        Args:
            expression: A cron expression string. Supports:
                - Standard 5-field syntax: "minute hour day month weekday"
                  (e.g., "0 9 * * 1" for Mondays at 9 AM)
                - Vixie cron keywords: @yearly, @annually, @monthly, @weekly,
                  @daily, @midnight, @hourly
            automatic: If set, this task will be automatically scheduled during worker
                startup and continually through the worker's lifespan. This ensures
                that the task will always be scheduled despite crashes and other
                adverse conditions. Automatic tasks must not require any arguments.
            tz: Timezone for interpreting the cron expression. Defaults to UTC.
                Use `ZoneInfo("America/Los_Angeles")` for Pacific time, etc.
                This correctly handles daylight saving time transitions.
        )	automaticN)
super__init__r   getr   r   r   r   nowr   )selfr   r   r   	__class__s       e/home/jay/workspace/scripts/.codegraph-venv/lib/python3.12/site-packages/docket/dependencies/_cron.pyr   zCron.__init__D   sO    * 	9-(,,ZD (,,tww2GH    c                   K   t        j                         }t        | j                  | j                  | j
                        }|j                  |_        |j                  |_        |S w)N)r   r   r   )r
   r   r   r   r   r   argskwargs)r   	executioncrons      r   
__aenter__zCron.__aenter__^   sK     %))+	t$..TWWUNN	&&s   A%A'c                ,    t        | j                        S )z@Return the next matching cron time from the underlying iterator.)nextr   r   s    r   	next_timezCron.next_timee   s    DNN##r   c                "    | j                         S )z1Return the next cron time for initial scheduling.)r)   r(   s    r   initial_whenzCron.initial_wheni   s     ~~r   c                ~   K   | j                  | j                                t        |   ||       d{   S 7 w)zHandle completion by scheduling the next execution at the exact cron time.

        This overrides Perpetual's on_complete to ensure we hit the exact wall-clock
        time rather than adjusting for task duration.
        N)atr)   r   on_complete)r   r#   outcomer   s      r   r.   zCron.on_completen   s4      	 !W(G<<<<s   3=;=)r   r   r   boolr   r   returnNone)r1   r   )r1   r   )r#   r   r/   r   r1   r0   )__name__
__module____qualname____doc____annotations__r   utcr   r%   r)   propertyr+   r.   __classcell__)r   s   @r   r   r      s     D OJ
 \\	II I 	I
 
I4$    = =r   r   N)r6   
__future__r   r   r   r   typingr   cronsimr   _baser
   
_perpetualr   r   r#   r   r   r7   r    r   r   <module>rA      sY    ' " / /    $ !"% " Y=9 Y=r   