eclectic-saturday-riddles.py

#!/usr/bin/env python

import datetime as dt

def riddle_for_date(date, solutions=False):
    """
    Determines the number for the Saturday Mac Riddle associated with
    a given date, considering whether it is the date for the riddle 
    or the solutions.

    Parameters:
    date (datetime): The date for which to determine the riddle number.
    solutions (bool): Indicates whether to consider the date for 
    solutions (True) or the riddle itself (False). Default is False.

    Returns:
    int: The riddle number associated with the specified date.

    Raises:
    None
    """
    base_date = dt.datetime(2019,6,29) # Date of first riddle
    if solutions: # A monday
        # We provide the date for the first solution by offsetting 
        # by two days (from Saturday to Monday)
        base_date = base_date+dt.timedelta(days=2)
        
    return ((date-base_date).days//7 + 1)

def date_for_riddle(riddle_num, solutions=True):
    """
    Computes the date associated with a given Eclectic Light Co 
    Saturday's riddle number, considering whether to give the date for 
    the riddle or for the solution.

    Parameters:
    riddle_num (int): The number of the riddle for which to calculate 
    the date.
    solutions (bool): Indicates whether to use the solution's or the 
    riddle's date. Default is True (for the solution's date).

    Returns:
    datetime: Computed date associated with the specified riddle.

    Raises:
    ValueError: If the specified riddle number is less than 1.
    """
    # Set a base date for the riddles
    # The first riddle was issued on June 29th, 2019
    base_date = dt.datetime(2019, 6, 29)

    # Offset base date to the next Monday (two days after)
    # if solutions are requested
    if solutions:
        base_date = base_date + dt.timedelta(days=2)

    # Validate riddle number
    riddle_num = int(riddle_num)

    # We use -1 to indicate the latest date
    if riddle_num < 1 and riddle_num != -1:
        raise ValueError(f"The specified riddle number ({riddle_num}) is less than 1, and not -1.")

    # Compute the date associated with the riddle number
    # by adding as many weeks as the riddle number - 1.
    if riddle_num == -1: # Latest riddle
        riddle_num = riddle_for_date(
            dt.datetime.today(),
            solutions=solutions
        )
    
    result = base_date + (riddle_num - 1) * dt.timedelta(days=7)
    return result


def url_for_riddle(riddle_num, solutions=True, open_in_browser=False):
    """
    Generates a URL for accessing a specific Mac riddle from 
    the Eclectic Light Company's blog https://eclecticlight.co/.

    Parameters:
    riddle_num (int): The number of the riddle to generate URL for.
    solutions (bool): Indicates whether the URL should lead to the 
                      riddle's solutions (True), or just to the 
                      original riddle. Default is True.
    open_in_browser (bool): Indicates whether the generated URL should 
                      be opened in the default web browser.
                      Default is False.

    Returns:
    str: The generated URL for the specified Mac riddle.

    Raises:
    ValueError (through `date_for_riddle`) if the riddle_num is less 
    than 1, or not an int.
    """
    if riddle_num == -1:
        riddle_num = riddle_for_date(
            dt.datetime.now(),
            solutions=solutions
        )
    date = date_for_riddle(riddle_num,solutions=solutions)
    slug = f"saturday-mac-riddles-{riddle_num}/"
    
    if solutions:
        slug = f"solutions-to-{slug}"

    result = f"https://eclecticlight.co/{date.year:04d}/{date.month:02d}/{date.day:02}/{slug}"

    if open_in_browser:
        import webbrowser
        webbrowser.open(result)
        
    return result

if __name__ == "__main__":
    """
    Main:
    Print URLs, and open in webbrowser the several IDs.

    It should raise an exception while trying to open riddle 0.
    """
    print(f"Opening URL: {url_for_riddle(  -1, solutions=False, open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle(  -1, solutions=True,  open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle( 123, solutions=False, open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle( 123, solutions=True,  open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle(1234, solutions=False, open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle(1234, solutions=True,  open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle(   0, solutions=False, open_in_browser=True)}")
    print(f"Opening URL: {url_for_riddle(   0, solutions=True,  open_in_browser=True)}")