seanbudd · Jun 5, 2023 · May 24, 2022 · May 24, 2022 · Jun 8, 2022 · Jun 10, 2022
@@ -2,6 +2,7 @@
 #Copyright (C) 2018 NV Access Limited
 #This file is covered by the GNU General Public License.
 #See the file COPYING for more details.
+from typing import Tuple
 
 import buildVersion
 import re
@@ -12,8 +13,14 @@
 how the API has changed as well as the range of API versions supported by this build of NVDA
 """
 
-CURRENT = (buildVersion.version_year, buildVersion.version_major, buildVersion.version_minor)
-BACK_COMPAT_TO = (2022, 1, 0)
+AddonApiVersionT = Tuple[int, int, int]
+
+CURRENT: AddonApiVersionT = (
+	buildVersion.version_year,
+	buildVersion.version_major,
+	buildVersion.version_minor
+)
+BACK_COMPAT_TO: AddonApiVersionT = (2022, 1, 0)
 """
 As BACK_COMPAT_TO is incremented, the changed / removed parts / or reasoning should be added below.
 These only serve to act as a reminder, the changelog should be consulted for a comprehensive listing.
@@ -25,24 +32,33 @@
 (0, 0, 0): API version zero, used to signify addons released prior to API version checks.
 """
 
-#: Compiled regular expression to match an addon API version string.
-#: Supports year.major.minor versions (e.g. 2018.1.1).
+# Compiled regular expression to match an addon API version string.
+# Supports year.major.minor versions (e.g. 2018.1.1).
 # Although year and major are mandatory, minor is optional.
-#: Resulting match objects expose three groups reflecting release year, release major, and release minor version,
-# respectively.
-# As minor is optional, the final group in the resulting match object may be None if minor is not provided in the original string. In this case it should be treated as being 0. 
-#: @type: RegexObject
-ADDON_API_VERSION_REGEX = re.compile(r"^(0|\d{4})\.(\d)(?:\.(\d))?$")
+# Resulting match objects expose three groups reflecting:
+# - release year
+# - release major
+# - release minor
+# As minor is optional, the final group in the resulting match object may be None if minor is not provided
+# in the original string. In this case it should be treated as being 0.
+# See also: L{tests.unit.test_addonVersionCheck.TestGetAPIVersionTupleFromString}
+ADDON_API_VERSION_REGEX: re.Pattern = re.compile(r"^(0|\d{4})\.(\d)(?:\.(\d))?$")
+
 
-def getAPIVersionTupleFromString(version):
-	"""Converts a string containing an NVDA version to a tuple of the form (versionYear, versionMajor, versionMinor)"""
+def getAPIVersionTupleFromString(version: str) -> AddonApiVersionT:
+	"""
+	Converts a string containing an NVDA version to a tuple of the form:
+	(versionYear, versionMajor, versionMinor)
+	Raises ValueError when unable to parse version string.
+	# See also: L{tests.unit.test_addonVersionCheck.TestGetAPIVersionTupleFromString}
+	"""
 	match = ADDON_API_VERSION_REGEX.match(version)
 	if not match:
 		raise ValueError(version)
 	return tuple(int(i) if i is not None else 0 for i in match.groups())
 
 
-def formatForGUI(versionTuple):
+def formatForGUI(versionTuple: AddonApiVersionT) -> str:
 	"""Converts a version tuple to a string for displaying in the GUI
 	Examples:
 	- (2018, 1, 1) becomes "2018.1.1"

@@ -3,7 +3,8 @@
 # Joseph Lee, Babbage B.V., Arnold Loubriat, Łukasz Golonka
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-
+import enum
+from abc import abstractmethod, ABC
 import sys
 import os.path
 import gettext
@@ -51,15 +52,32 @@
 isCLIParamKnown = extensionPoints.AccumulatingDecider(defaultDecision=False)
 
 
+class AddonStateCategory(str, enum.Enum):
+	""" For backwards compatibility, the enums must remain functionally a string.
+	I.E. the following must be true:
+	> assert isinstance(AddonStateCategory.PENDING_REMOVE, str)
+	> assert AddonStateCategory.PENDING_REMOVE == "pendingRemovesSet"
+	"""
+	PENDING_REMOVE = "pendingRemovesSet"
+	PENDING_INSTALL = "pendingInstallsSet"
+	DISABLED = "disabledAddons"
+	PENDING_ENABLE = "pendingEnableSet"
+	PENDING_DISABLE = "pendingDisableSet"
+
+
 class AddonsState(collections.UserDict):
-	"""Subclasses `collections.UserDict` to preserve backwards compatibility."""
-
-	_DEFAULT_STATE_CONTENT = {
-		"pendingRemovesSet": set(),
-		"pendingInstallsSet": set(),
-		"disabledAddons": set(),
-		"pendingEnableSet": set(),
-		"pendingDisableSet": set(),
+	"""
+	Subclasses `collections.UserDict` to preserve backwards compatibility.
+	self: typing.Dict[AddonStateCategory, typing.Set[str]]
+	AddonStateCategory string enums mapped to a set of the add-on "name/id" currently in that state.
+	"""
+
+	_DEFAULT_STATE_CONTENT: typing.Dict[AddonStateCategory, typing.Set[str]] = {
+		AddonStateCategory.PENDING_REMOVE: set(),
+		AddonStateCategory.PENDING_INSTALL: set(),
+		AddonStateCategory.DISABLED: set(),
+		AddonStateCategory.PENDING_ENABLE: set(),
+		AddonStateCategory.PENDING_DISABLE: set(),
 	}
 
 	@property
@@ -120,14 +138,16 @@ def cleanupRemovedDisabledAddons(self) -> None:
 state = AddonsState()
 
 
-def getRunningAddons():
+def getRunningAddons() -> typing.Generator["Addon", None, None]:
 	""" Returns currently loaded add-ons.
 	"""
 	return getAvailableAddons(filterFunc=lambda addon: addon.isRunning)
 
+
 def getIncompatibleAddons(
 		currentAPIVersion=addonAPIVersion.CURRENT,
-		backCompatToAPIVersion=addonAPIVersion.BACK_COMPAT_TO):
+		backCompatToAPIVersion=addonAPIVersion.BACK_COMPAT_TO
+) -> typing.Generator["Addon", None, None]:
 	""" Returns a generator of the add-ons that are not compatible.
 	"""
 	return getAvailableAddons(
@@ -266,9 +286,16 @@ def getAvailableAddons(
 			_availableAddons[addon.path] = addon
 	return (addon for addon in _availableAddons.values() if not filterFunc or filterFunc(addon))
 
-def installAddonBundle(bundle):
-	"""Extracts an Addon bundle in to a unique subdirectory of the user addons directory, marking the addon as needing install completion on NVDA restart."""
-	addonPath = os.path.join(globalVars.appArgs.configPath, "addons",bundle.manifest['name']+ADDON_PENDINGINSTALL_SUFFIX)
+
+def installAddonBundle(bundle: "AddonBundle") -> "Addon":
+	""" Extracts an Addon bundle in to a unique subdirectory of the user addons directory,
+	marking the addon as needing 'install completion' on NVDA restart.
+	"""
+	addonPath = os.path.join(
+		globalVars.appArgs.configPath,
+		"addons",
+		bundle.manifest['name'] + ADDON_PENDINGINSTALL_SUFFIX
+	)
 	bundle.extract(addonPath)
 	addon=Addon(addonPath)
 	# #2715: The add-on must be added to _availableAddons here so that
@@ -288,29 +315,45 @@ def installAddonBundle(bundle):
 class AddonError(Exception):
 	""" Represents an exception coming from the addon subsystem. """
 
-class AddonBase(object):
+
+class AddonBase(ABC):
 	"""The base class for functionality that is available both for add-on bundles and add-ons on the file system.
 	Subclasses should at least implement L{manifest}.
 	"""
 
 	@property
-	def name(self):
+	def name(self) -> str:
+		"""A unique name, the id of the add-on.
+		"""
 		return self.manifest['name']
 
 	@property
-	def version(self):
+	def version(self) -> str:
+		"""A display version. Not necessarily semantic
+		"""
 		return self.manifest['version']
 
 	@property
-	def minimumNVDAVersion(self):
+	def minimumNVDAVersion(self) -> typing.Tuple[int, int, int]:
 		return self.manifest.get('minimumNVDAVersion')
 
 	@property
-	def lastTestedNVDAVersion(self):
+	def lastTestedNVDAVersion(self) -> typing.Tuple[int, int, int]:
 		return self.manifest.get('lastTestedNVDAVersion')
 
+	@property
+	@abstractmethod
+	def manifest(self) -> "AddonManifest":
+		...
+
+
 class Addon(AddonBase):
 	""" Represents an Add-on available on the file system."""
+
+	@property
+	def manifest(self) -> "AddonManifest":
+		return self._manifest
+
 	def __init__(self, path):
 		""" Constructs an L{Addon} from.
 		@param path: the base directory for the addon data.
@@ -327,7 +370,7 @@ def __init__(self, path):
 					log.debug("Using manifest translation from %s", p)
 					translatedInput = open(p, 'rb')
 					break
-			self.manifest = AddonManifest(f, translatedInput)
+			self._manifest = AddonManifest(f, translatedInput)
 			if self.manifest.errors is not None:
 				_report_manifest_errors(self.manifest)
 				raise AddonError("Manifest file has errors.")
@@ -648,9 +691,8 @@ def extract(self, addonPath):
 				z.extract(info, addonPath)
 
 	@property
-	def manifest(self):
+	def manifest(self) -> "AddonManifest":
 		""" Gets the manifest for the represented Addon.
-		@rtype: AddonManifest
 		"""
 		return self._manifest
 
@@ -740,7 +782,7 @@ def __init__(self, input, translatedInput=None):
 		"""
 		super(AddonManifest, self).__init__(input, configspec=self.configspec, encoding='utf-8', default_encoding='utf-8')
 		self._errors = None
-		val = Validator({"apiVersion":validate_apiVersionString})
+		val = Validator({"apiVersion": validate_apiVersionString})
 		result = self.validate(val, copy=True, preserve_errors=True)
 		if result != True:
 			self._errors = result
@@ -766,7 +808,8 @@ def _validateApiVersionRange(self):
 		minRequiredVersion = self.get("minimumNVDAVersion")
 		return minRequiredVersion <= lastTested
 
-def validate_apiVersionString(value):
+
+def validate_apiVersionString(value) -> typing.Tuple[int, int, int]:
 	from configobj.validate import ValidateError
 	if not value or value == "None":
 		return (0, 0, 0)

@@ -3,25 +3,38 @@
 # Copyright (C) 2018 NV Access Limited
 # This file is covered by the GNU General Public License.
 # See the file COPYING for more details.
-
+from typing_extensions import Protocol  # Python 3.8 adds native support
 import addonAPIVersion
 
-def hasAddonGotRequiredSupport(addon, currentAPIVersion=addonAPIVersion.CURRENT):
+
+class SupportsVersionCheck(Protocol):
+	""" Examples implementing this protocol include:
+	- addonHandler.AddonBundle
+	- addonStore.models.AddonDetailsModel
+	"""
+	minimumNVDAVersion: addonAPIVersion.AddonApiVersionT
+	lastTestedNVDAVersion: addonAPIVersion.AddonApiVersionT
+
+
+def hasAddonGotRequiredSupport(
+		addon: SupportsVersionCheck,
+		currentAPIVersion=addonAPIVersion.CURRENT
+):
 	"""True if NVDA provides the add-on with an API version high enough to meet the add-on's minimum requirements
 	"""
 	minVersion = addon.minimumNVDAVersion
 	return minVersion <= currentAPIVersion
 
 
-def isAddonTested(addon, backwardsCompatToVersion=addonAPIVersion.BACK_COMPAT_TO):
+def isAddonTested(addon: SupportsVersionCheck, backwardsCompatToVersion=addonAPIVersion.BACK_COMPAT_TO):
 	"""True if this add-on is tested for the given API version.
 	By default, the current version of NVDA is evaluated.
 	"""
 	return addon.lastTestedNVDAVersion >= backwardsCompatToVersion
 
 
 def isAddonCompatible(
-		addon,
+		addon: SupportsVersionCheck,
 		currentAPIVersion=addonAPIVersion.CURRENT,
 		backwardsCompatToVersion=addonAPIVersion.BACK_COMPAT_TO
 ):

diff --git a/source/addonStore/__init__.py b/source/addonStore/__init__.py
@@ -0,0 +1,4 @@
+# A part of NonVisual Desktop Access (NVDA)
+# Copyright (C) 2022 NV Access Limited
+# This file is covered by the GNU General Public License.
+# See the file COPYING for more details.