Refactor Skill API endpoints

requirements/requirements.txt

@@ -6,3 +6,4 @@ ovos-utils~=0.0, >=0.0.34
 neon-utils~=1.12
 ovos-workshop~=0.0,>=0.0.12
 ovos-lingua-franca~=0.4
+pydantic~=2.0

skill.json

@@ -21,6 +21,7 @@
             "ovos-lingua-franca~=0.4",
             "ovos-utils~=0.0, >=0.0.34",
             "ovos-workshop~=0.0,>=0.0.12",
+            "pydantic~=2.0",
             "pytz>=2022.1",
             "timezonefinder~=5.2"
         ],

skill_date_time/__init__.py

@@ -44,6 +44,7 @@
 import geocoder
 import pytz
 
+from time import time
 from datetime import tzinfo, datetime
 from typing import Union, Optional
 
@@ -62,6 +63,10 @@
 from ovos_workshop.decorators import intent_handler, skill_api_method, \
     resting_screen_handler
 
+from skill_date_time.api_data_models import DisplayCurrentTimeResponse, \
+        DisplayDateReponse, MonthDateResponse, TimeInLocationRequest, \
+        WeekdayResponse, YearResponse, CurrentTimeResponse, FormattedTimeResponse
+
 
 day_to_dialog = {
     0: "word_monday",
@@ -128,20 +133,15 @@ def handle_idle(self, _):
         self.gui.show_page('idle')
 
     @skill_api_method
-    def get_display_date(self, day: Optional[datetime] = None,
-                         location: Optional[str] = None,
-                         message: Message = None) -> str:
+    def get_display_date(self,
+                         request: TimeInLocationRequest = TimeInLocationRequest()) -> DisplayDateReponse:
         """
-        Get the full date for day or location in the configured format.
-        :param day: datetime object to display
-        :param location: location to get the current datetime of
-        :param message: Message containing user profile for request
-        :returns: The full date in the user configured format
+        Get the full date in the configured format.
         """
-        message = message or dig_for_message()
+        # TODO: Refactor to accept format as a param?
+        message = dig_for_message()
         unit_prefs = get_user_prefs(message)['units']
-        if not day:
-            day = self.get_local_datetime(location, None)
+        day = self.get_local_datetime(request.location, None)
         if unit_prefs.get('date') == 'MDY':
             return day.strftime("%-m/%-d/%Y")
         elif unit_prefs.get('date') == 'YMD':
@@ -152,29 +152,15 @@ def get_display_date(self, day: Optional[datetime] = None,
             return day.strftime("%Y/%-d/%-m")
 
     @skill_api_method
-    def get_display_current_time(self, location: Optional[str] = None,
-                                 dt_utc: Optional[datetime] = None,
-                                 message: Message = None) -> \
-            Optional[str]:
-        """
-        Get a formatted digital clock time based on the user preferences
-        :param location: location to get the current datetime of
-        :param dt_utc: UTC datetime to override current datetime
-        :param: Time in the user configured format if location is valid
-            else None
-        :param message: Message containing user profile for request
-        :returns: Formatted string time or None if Exception
-        """
-        message = message or dig_for_message()
+    def get_display_current_time(self, request: TimeInLocationRequest = TimeInLocationRequest(),
+                                 ) -> DisplayCurrentTimeResponse:
+        """
+        Get a formatted digital clock time based on the user's preferences
+        """
+        message = dig_for_message()
+        location = request.location
         try:
             dt = self.get_local_datetime(location, message)
-            if dt_utc:
-                if location:
-                    dt = dt_utc.astimezone(dt.tzinfo)
-                else:
-                    dt = dt_utc
-            if not dt:
-                return None
             load_language(self.lang)
             # Logging here produces logs every 10s
             # LOG.debug(f"Got time: {dt.isoformat()}|use_24h={self.use_24hour}")
@@ -189,16 +175,12 @@ def get_display_current_time(self, location: Optional[str] = None,
             return None
 
     @skill_api_method
-    def get_weekday(self, day: Optional[datetime] = None,
-                    location: Optional[str] = None) -> str:
+    def get_weekday(self, request: TimeInLocationRequest = TimeInLocationRequest(),
+                    ) -> WeekdayResponse:
         """
-        Get the weekday name for a given day.
-        :param day: datetime object to get weekday of
-        :param location: optional location to get weekday for
-        :returns: The name of the weekday (i.e. Monday)
+        Get the weekday name for a given day. (Monday, Tuesday, etc.)
         """
-        if not day:
-            day = self.get_local_datetime(location, None)
+        day = self.get_local_datetime(request.location, None)
         if self.lang in date_time_format.lang_config.keys():
             localized_day_names = list(
                 date_time_format.lang_config[self.lang]['weekday'].values())
@@ -208,21 +190,15 @@ def get_weekday(self, day: Optional[datetime] = None,
         return weekday.capitalize()
 
     @skill_api_method
-    def get_month_date(self, day: Optional[datetime] = None,
-                       location: Optional[str] = None,
-                       message: Message = None) -> str:
-        """
-        Get the month and date for a given day and location
-        :param day: optional datetime object to get month and date for
-        :param location: optional location to get the current datetime of
-        :param message: Message containing user profile for request
-        :returns: date in the format DD MONTH or MONTH DD
-            depending on the users date_format setting.
-        """
-        message = message or dig_for_message()
+    def get_month_date(self,
+                       request: TimeInLocationRequest = TimeInLocationRequest()) -> MonthDateResponse:
+        """
+        Get the month and date for a given day and location in the format 
+        DD MONTH or MONTH DD, depending on the user's date_format setting.
+        """
+        message = dig_for_message()
         unit_prefs = get_user_prefs(message)["units"]
-        if not day:
-            day = self.get_local_datetime(location, None)
+        day = self.get_local_datetime(request.location, None)
         if self.lang in date_time_format.lang_config.keys():
             localized_month_names = \
                 date_time_format.lang_config[self.lang]['month']
@@ -236,19 +212,37 @@ def get_month_date(self, day: Optional[datetime] = None,
             return f"{day.strftime('%d')} {month}"
 
     @skill_api_method
-    def get_year(self, day: Optional[datetime] = None,
-                 location: Optional[str] = None) -> str:
+    def get_year(self, 
+                 request: TimeInLocationRequest = TimeInLocationRequest()) -> YearResponse:
         """
-        Get the year for a given day and location
-        :param day: optional datetime object to get year for
-        :param location: optional location to get the current year of
-        :returns: year in the format YYYY
+        Get the year for a given day and location in YYYY format
         """
-        if not day:
-            day = self.get_local_datetime(location)
+        day = self.get_local_datetime(request.location)
         return day.strftime("%Y")
 
     @skill_api_method
+    def get_current_time(self) -> CurrentTimeResponse:
+        """
+        Get the current epoch timestamp in seconds
+        """
+        return time()
+
+    @skill_api_method
+    def get_formatted_time(self, request: TimeInLocationRequest = TimeInLocationRequest()) -> FormattedTimeResponse:
+        """
+        Get the current time formatted as time, date, and weekday strings
+        """
+        location = request.location or self.location['city']['name']
+        dt = self.get_local_datetime(location)
+        if not dt:
+            raise ValueError(f"Invalid location: {location}")
+        formatted_time = dt.strftime("%H:%M")
+        formatted_date = dt.strftime("%Y-%m-%d")
+        current_weekday = dt.strftime("%A")
+        return FormattedTimeResponse(formatted_time=formatted_time,
+                                      formatted_date=formatted_date,
+                                      current_weekday=current_weekday)
+
     def get_next_leap_year(self, year: int) -> int:
         """
         Get the next calendar year that will be a leap year.
@@ -263,7 +257,6 @@ def get_next_leap_year(self, year: int) -> int:
         else:
             return self.get_next_leap_year(next_year)
 
-    @skill_api_method
     def is_leap_year(self, year: int) -> bool:
         """
         Check if given year is a leap year.
@@ -288,9 +281,10 @@ def handle_query_time(self, message: Message):
             # An error should have been spoken by now, location wasn't valid
             return
 
+        request_obj = TimeInLocationRequest(location=location)
         self.show_time_gui(location,
-                           self.get_display_current_time(location),
-                           self.get_display_date(location=location))
+                           self.get_display_current_time(request_obj),
+                           self.get_display_date(request_obj))
         if location:
             self.speak_dialog("date_time_in_location",
                               {"location": location.title(),

skill_date_time/api_data_models.py

@@ -0,0 +1,65 @@
+# NEON AI (TM) SOFTWARE, Software Development Kit & Application Framework
+# All trademark and other rights reserved by their respective owners
+# Copyright 2008-2025 Neongecko.com Inc.
+# Contributors: Daniel McKnight, Guy Daniels, Elon Gasper, Richard Leeds,
+# Regina Bloomstine, Casimiro Ferreira, Andrii Pernatii, Kirill Hrymailo
+# BSD-3 License
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from this
+#    software without specific prior written permission.
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
+# OR PROFITS;  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE,  EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from typing import Optional
+from pydantic import BaseModel, RootModel, Field
+
+
+class TimeInLocationRequest(BaseModel):
+    location: Optional[str] = Field(
+            default=None, description="Location to get time information for")
+
+
+class DisplayDateReponse(RootModel):
+    root: str = Field(description="Date in the user-configured format")
+
+
+class DisplayCurrentTimeResponse(RootModel):
+    root: str = Field(description="Current time in the user-configured format")
+
+
+class WeekdayResponse(RootModel):
+    root: str = Field(description="Weekday printed in the user's language")
+
+
+class MonthDateResponse(RootModel):
+    root: str = Field(description="Month and day in the user-configured format")
+
+
+class YearResponse(RootModel):
+    root: str = Field(description="Year (YYYY)")
+
+
+class CurrentTimeResponse(RootModel):
+    root: float = Field(description="Current epoch time in seconds")
+
+
+class FormattedTimeResponse(BaseModel):
+    formatted_time: str = Field(description="Current time in HH:MM format")
+    formatted_date: str = Field(description="Current date in YYYY-MM-DD format")
+    current_weekday: str = Field(description="Current weekday name in English")