what name to give to a new function?

[Skaperen]

i am developing a new kind of sleep function that can sleep to a specific time offset into a repeating cycle with a minimum amount of time to sleep. for example the repeating cycle could be 12 minutes and the offset be 1 minute and 10 seconds. started at 00:00 it would sleep until 13:10. then started at 13:17 it would sleep until 25:10. notice that the delayed start again time is not accumulated. a third argument sets a minimum time to sleep in case to start time is too close to the goal. the arguments are:
1. offset
2. repeating period (cycle)
3. minimum sleep time
each argument is in seconds with a default value of 0 which makes that argument have no effect.
called with no arguments (ot all 0), the function does not sleep and returns 0.
all arguments can be int, float, or Decimal.

my question is what would be a decent or good name for this function? in the included source code, i named it xsleep(), which is a temporary name. i have changed its name a couples times, before.

from time import sleep, time as secs

def xsleep(offset=0,cycle=0,minimum=0):
    """Synchronized sleep to the next offset in a cyclical period."""
#-----------------------------------------------------------------------------
# Copyright © 2025 - Phil D. Howard - All rights reserved
#
# This program is free software; you can redistribute it and/or
# modify it under the terms of the GNU General Public License
# as published by the Free Software Foundation; either version 2
# of the License, or (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
#-----------------------------------------------------------------------------
    # note: only Python3 is supported by this code
    # arg 1: offset or how long to sleep
    # arg 2: cycle or period duration
    # arg 3: minimum time to sleep
    # return: how many seconds actually slept
    # example:              sleep for 10 minutes: xsleep(600)
    # example: sleep to 10 minutes past the hour: xsleep(600,3600)
    # example: like above but at least 5 minutes: xsleep(600,3600,300)
    # example:            sleep to the next noon: xsleep(86400,43200)
    # example:          middle of next 3 seconds: xsleep(3/2,3)
    # note: values for all three arguments may be int, float, or decimal
    # note: negative values are not supported
    if offset < 0 or cycle < 0 or minimum < 0:
        raise ValueError('negative values are not supported by xsleep()')
    if cycle:
        offset = (offset - secs()) % cycle
        while offset < minimum:
            offset += cycle
    elif offset < minimum:
        offset = minimum
    if offset > 0:
        sleep(offset)
    return offset

any suggestions? i suppose "sleep" could be substituted with "wait" but that might get confused with functions that wait for specific events.

[Gribouillis]

I suggest sleep_to_cycle()

[Skaperen]

a long name? i guess that's a way to make the semantics more readable rather then an "x".

[snippsat]

Some advice you’ll want a non-blocking sleep,so that other coroutines can make progress while you’re waiting for your phase.
Swap out time.sleep()(blocking) for asyncio.sleep() and use the event loop’s clock instead of time.time().
Here’s a sketch and i think phase_sleep is ok.

import asyncio

async def phase_sleep(offset=0, cycle=0, minimum=0):
    """
    Asynchronously sleep until the next offset into a repeating cycle,
    but sleep at least minimum seconds. Returns the actual delay.
    """
    loop = asyncio.get_running_loop()
    now = loop.time()  # clock aligned to the event loop
    if offset < 0 or cycle < 0 or minimum < 0:
        raise ValueError("negative values are not supported")
    if cycle:
        # how far we are from the target phase
        delay = (offset - now) % cycle
        # if that’s too small, jump forward a full cycle
        while delay < minimum:
            delay += cycle
    else:
        # no cycle: just sleep long enough
        delay = max(offset, minimum)
    if delay > 0:
        await asyncio.sleep(delay)
    return delay

[Skaperen]

i was originally planning to do another one for a non-blocking sleep in the near future. this is just a variation on sleep() the way it is used (no need for non-blocking).