add typings to core

.gitignore

@@ -14,3 +14,7 @@ Core/automation/jython/**
 
 # Python Virtual Environment
 .venv
+
+# Python Stubs
+Core/typings/*
+!Core/typings/core

Core/automation/lib/python/core/date.py

@@ -20,6 +20,11 @@
     "to_python_datetime", "to_joda_datetime", "human_readable_seconds"
 ]
 
+try:
+    import typing as t
+except:
+    pass
+
 import sys
 import datetime
 import inspect
@@ -29,9 +34,14 @@
 from java.time import LocalDateTime, ZonedDateTime
 from java.time import ZoneId, ZoneOffset
 from java.time.format import DateTimeFormatter
-from java.time.temporal.ChronoUnit import DAYS, HOURS, MINUTES, SECONDS
+from java.time.temporal import ChronoUnit
 from java.util import Calendar, Date, TimeZone
 
+DAYS = ChronoUnit.DAYS
+HOURS = ChronoUnit.HOURS
+MINUTES = ChronoUnit.MINUTES
+SECONDS = ChronoUnit.SECONDS
+
 try:
     from org.joda.time import DateTime as JodaDateTime
     from org.joda.time import DateTimeZone as JodaDateTimeZone
@@ -66,6 +76,7 @@ def remove_java_converter(clazz):
 
 
 def format_date(value, format_string="yyyy-MM-dd'T'HH:mm:ss.SSxx"):
+    # type: (t.Any, str) -> str
     """
     Returns string of ``value`` formatted according to ``format_string``.
 
@@ -89,10 +100,11 @@ def format_date(value, format_string="yyyy-MM-dd'T'HH:mm:ss.SSxx"):
     Returns:
         str: the converted value
     """
-    return to_java_zoneddatetime(value).format(DateTimeFormatter.ofPattern(format_string))
+    return str(to_java_zoneddatetime(value).format(DateTimeFormatter.ofPattern(format_string)))
 
 
 def days_between(start_time, stop_time, calendar_days=False):
+    # type: (t.Any, t.Any, bool) -> int
     """
     Returns the number of days between ``start_time`` and ``stop_time``.
     Will return a negative number if ``start_time`` is after ``stop_time``.
@@ -118,6 +130,7 @@ def days_between(start_time, stop_time, calendar_days=False):
 
 
 def hours_between(start_time, stop_time):
+    # type: (t.Any, t.Any) -> int
     """
     Returns the number of hours between ``start_time`` and ``stop_time``.
     Will return a negative number if ``start_time`` is after ``stop_time``.
@@ -138,6 +151,7 @@ def hours_between(start_time, stop_time):
 
 
 def minutes_between(start_time, stop_time):
+    # type: (t.Any, t.Any) -> int
     """
     Returns the number of minutes between ``start_time`` and ``stop_time``.
     Will return a negative number if ``start_time`` is after ``stop_time``.
@@ -158,6 +172,7 @@ def minutes_between(start_time, stop_time):
 
 
 def seconds_between(start_time, stop_time):
+    # type: (t.Any, t.Any) -> int
     """
     Returns the number of seconds between ``start_time`` and ``stop_time``.
     Will return a negative number if ``start_time`` is after ``stop_time``.
@@ -178,6 +193,7 @@ def seconds_between(start_time, stop_time):
 
 
 def human_readable_seconds(seconds):
+    # type: (int) -> str
     """
     Converts seconds into a human readable string of days, hours, minutes and
     seconds.
@@ -222,6 +238,7 @@ def human_readable_seconds(seconds):
 
 
 def to_java_zoneddatetime(value):
+    # type: (t.Any) -> ZonedDateTime
     """
     Converts any of the supported date types to ``java.time.ZonedDateTime``. If
     ``value`` does not have timezone information, the system default will be
@@ -292,6 +309,7 @@ def to_java_zoneddatetime(value):
 
 
 def to_python_datetime(value):
+    # type: (t.Any) -> datetime.datetime
     """
     Converts any of the supported date types to Python ``datetime.datetime``.
     If ``value`` does not have timezone information, the system default will be
@@ -351,6 +369,7 @@ def dst(self, value):
 
 
 def to_joda_datetime(value):
+    # type: (t.Any) -> JodaDateTime
     """
     Converts any of the supported date types to ``org.joda.time.DateTime``. If
     ``value`` does not have timezone information, the system default will be
@@ -390,6 +409,7 @@ def to_joda_datetime(value):
 
 
 def to_java_calendar(value):
+    # type: (t.Any) -> Calendar
     """
     Converts any of the supported date types to ``java.util.Calendar``. If
     ``value`` does not have timezone information, the system default will be

Core/automation/lib/python/core/items.py

@@ -4,6 +4,24 @@
 """
 __all__ = ["add_item", "remove_item"]
 
+try:
+    import typing as t
+    if t.TYPE_CHECKING:
+        basestring = str
+        unicode = str
+        try:
+            from org.openhab.core.items import (
+                ItemBuilderFactory as ohItemBuilderFactory,
+                ManagedItemProvider as ohManagedItemProvider,
+            )
+        except:
+            from org.eclipse.smarthome.core.items import (
+                ItemBuilderFactory as ohItemBuilderFactory,
+                ManagedItemProvider as ohManagedItemProvider,
+            )
+except:
+    pass
+
 from core.jsr223.scope import scriptExtension, itemRegistry
 
 try:
@@ -20,13 +38,13 @@
         "org.openhab.core.items.ItemBuilderFactory"
     ) or osgi.get_service(
         "org.eclipse.smarthome.core.items.ItemBuilderFactory"
-    )
+    ) # type: ohItemBuilderFactory
 
 ManagedItemProvider = osgi.get_service(
         "org.openhab.core.items.ManagedItemProvider"
     ) or osgi.get_service(
         "org.eclipse.smarthome.core.items.ManagedItemProvider"
-    )
+    ) # type: ohManagedItemProvider
 
 log = getLogger("core.items")
 

Core/automation/lib/python/core/links.py

@@ -7,6 +7,16 @@
     "remove_link"
 ]
 
+try:
+    import typing as t
+    if t.TYPE_CHECKING:
+        try:
+            from org.openhab.core.thing.link import ItemChannelLinkRegistry, ManagedItemChannelLinkProvider
+        except:
+            from org.eclipse.smarthome.core.thing.link import ItemChannelLinkRegistry, ManagedItemChannelLinkProvider
+except:
+    pass
+
 from core import osgi
 from core.log import getLogger
 from core.utils import validate_item, validate_channel_uid
@@ -20,13 +30,13 @@
         "org.openhab.core.thing.link.ItemChannelLinkRegistry"
     ) or osgi.get_service(
         "org.eclipse.smarthome.core.thing.link.ItemChannelLinkRegistry"
-    )
+    ) # type: ItemChannelLinkRegistry
 
 MANAGED_ITEM_CHANNEL_LINK_PROVIDER = osgi.get_service(
         "org.openhab.core.thing.link.ManagedItemChannelLinkProvider"
     ) or osgi.get_service(
         "org.eclipse.smarthome.core.thing.link.ManagedItemChannelLinkProvider"
-    )
+    ) # type: ManagedItemChannelLinkProvider
 
 LOG = getLogger(u"core.links")
 

Core/automation/lib/python/core/log.py

@@ -11,6 +11,11 @@
     "log_traceback"
 ]
 
+try:
+    import typing as t
+except:
+    pass
+
 import logging
 import traceback
 from functools import wraps
@@ -19,7 +24,7 @@
 
 try:
     import configuration
-    LOG_PREFIX = configuration.LOG_PREFIX
+    LOG_PREFIX = configuration.LOG_PREFIX # type: str
 except:
     LOG_PREFIX = "jython"
     LoggerFactory.getLogger("{}.core.log".format(LOG_PREFIX)).warn("The 'configuration.py' file is missing from the python.path!")
@@ -67,6 +72,7 @@ def trace(self, msg, *args, **kwargs):
 
 
 def getLogger(name, prefix=None):
+    # type: (t.Optional[str], str) -> Slf4jLogger
     if not prefix and name:
         prefix = LOG_PREFIX
     if name:

Core/automation/lib/python/core/metadata.py

@@ -49,6 +49,17 @@
     "remove_key_value"
 ]
 
+try:
+    import typing as t
+    if t.TYPE_CHECKING:
+        from java.lang import String
+        try:
+            from org.openhab.core.items import MetadataRegistry
+        except:
+            from org.eclipse.smarthome.core.items import MetadataRegistry
+except:
+    pass
+
 from core import osgi
 from core.log import getLogger
 
@@ -61,12 +72,13 @@
         "org.openhab.core.items.MetadataRegistry"
     ) or osgi.get_service(
         "org.eclipse.smarthome.core.items.MetadataRegistry"
-    )
+    ) # type: MetadataRegistry
 
 LOG = getLogger(u"core.metadata")
 
 
 def get_all_namespaces(item_name):
+    # type: (str) -> t.List[String]
     """
     This function will return a list of an Item's namespaces.
 
@@ -89,6 +101,7 @@ def get_all_namespaces(item_name):
 
 
 def get_metadata(item_name, namespace):
+    # type: (str, str) -> t.Union[Metadata, None]
     """
     This function will return the Metadata object associated with the
     specified Item.
@@ -112,7 +125,14 @@ def get_metadata(item_name, namespace):
     return METADATA_REGISTRY.get(MetadataKey(namespace, item_name))
 
 
-def set_metadata(item_name, namespace, configuration, value=None, overwrite=False):
+def set_metadata(
+    item_name, # type: str
+    namespace, # type: str
+    configuration, # type: t.Mapping[str, t.Any]
+    value=None, # type: str
+    overwrite=False # type: bool
+):
+    # type: (...) -> None
     """
     This function creates or modifies Item metadata, optionally overwriting
     the existing data. If not overwriting, the provided keys and values will
@@ -152,6 +172,7 @@ def set_metadata(item_name, namespace, configuration, value=None, overwrite=Fals
 
 
 def remove_metadata(item_name, namespace=None):
+    # type: (str, str) -> None
     """
     This function removes the Item metadata for the specified namepsace or for
     all namespaces.
@@ -179,6 +200,7 @@ def remove_metadata(item_name, namespace=None):
 
 
 def get_key_value(item_name, namespace, *args):
+    # type: (str, str, str) -> t.Any
     """
     Ths function returns the ``configuration`` value for the specified key.
 
@@ -215,6 +237,7 @@ def get_key_value(item_name, namespace, *args):
 
 
 def set_key_value(item_name, namespace, *args):
+    # type: (str, str, t.Any) -> None
     """
     This function creates or updates a key value in the specified namespace.
 
@@ -251,6 +274,7 @@ def set_key_value(item_name, namespace, *args):
 
 
 def remove_key_value(item_name, namespace, *args):
+    # type: (str, str, str) -> None
     """
     This function removes a key from a namespace's ``configuration``.
 
@@ -287,6 +311,7 @@ def remove_key_value(item_name, namespace, *args):
 
 
 def get_value(item_name, namespace):
+    # type: (str, str) -> t.Union[str, None]
     """
     This function will return the Item metadata ``value`` for the specified
     namespace.
@@ -314,6 +339,7 @@ def get_value(item_name, namespace):
 
 
 def set_value(item_name, namespace, value):
+    # type: (str, str, str) -> None
     """
     This function creates or updates the Item metadata ``value`` for the
     specified namespace.