squash: Ensure versioning is a non-breaking change to legacy

Version 1 should be a special case, where the ID is not suffixed with
a version tag, and the unversioned class name continues to be available.

This then means the introduction of versioning is a non-breaking change
to people currently using the legacy library.

Signed-off-by: David Feltell <[email protected]>

Author: feltech

examples/resources/working_with_trait_versions/openassetio_example/specifications/example.py

@@ -59,12 +59,12 @@ def create(cls):
         data = TraitsData(cls.kTraitSet)
         return cls(data)
 
-    def deprectatedTrait(self):
+    def addedTrait(self):
         """
         Returns the view for the 'openassetio-example:example.Unchanged' trait wrapped around
         the data held in this instance.
         """
-        return traits.example.DeprecatedTrait_v1(self.traitsData())
+        return traits.example.AddedTrait_v1(self.traitsData())
 
     def updatedTrait(self):
         """
@@ -74,10 +74,6 @@ def updatedTrait(self):
         return traits.example.UpdatedTrait_v2(self.traitsData())
 
 
-# Alias for latest version.
-ExampleSpecification = ExampleSpecification_v2
-
-
 class ExampleSpecification_v1:
     """
     An example.
@@ -124,17 +120,20 @@ def create(cls):
         data = TraitsData(cls.kTraitSet)
         return cls(data)
 
-
-    def deprectatedTrait(self):
+    def addedTrait(self):
         """
         Returns the view for the 'openassetio-example:example.Unchanged' trait wrapped around
         the data held in this instance.
         """
-        return traits.example.DeprecatedTrait_v1(self.traitsData())
+        return traits.example.AddedTrait_v1(self.traitsData())
 
     def updatedTrait(self):
         """
         Returns the view for the 'openassetio-example:example.Updated' trait wrapped around
         the data held in this instance.
         """
-        return traits.example.UpdatedTrait_v1(self.traitsData())
+        return traits.example.UpdatedTrait_v2(self.traitsData())
+
+
+# Alias for first version.
+ExampleSpecification = ExampleSpecification_v1

examples/resources/working_with_trait_versions/openassetio_example/traits/example.py

@@ -1,9 +1,9 @@
-
 """
 Trait definitions in the 'example' namespace.
 
 Example namespace
 """
+import warnings
 
 # WARNING: This file is auto-generated by openassetio-traitgen, do not edit.
 
@@ -17,7 +17,8 @@ class DeprecatedTrait_v1:
     An example.
     Usage: entity, locale, relationship
     """
-    kId = "openassetio-example:example.Deprecated.v001"
+
+    kId = "openassetio-example:example.Deprecated"
 
     __deprecated__ = True  # (Eventually use PEP 702)
 
@@ -67,16 +68,23 @@ def imbueTo(cls, traitsData):
         traitsData.addTrait(cls.kId)
 
 
-# Alias for latest version.
-DeprecatedTrait = DeprecatedTrait_v1
-
+# Alias for first version.
+class DeprecatedTrait(DeprecatedTrait_v1):
+    def __init__(self, traitsData):
+        super().__init__(traitsData)
+        warnings.warn(
+            "Use of unversioned trait view classes is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
 
 class UpdatedTrait_v2:
     """
     An example.
     Usage: entity, locale, relationship
     """
-    kId = "openassetio-example:example.Updated.v002"
+
+    kId = "openassetio-example:example.Updated.v2"
 
     def __init__(self, traitsData):
         """
@@ -123,7 +131,6 @@ def imbueTo(cls, traitsData):
         """
         traitsData.addTrait(cls.kId)
 
-
     def setPropertyThatWasAdded(self, propertyThatWasAdded: float):
         """
         Sets the propertyThatWasAdded property.
@@ -134,7 +141,7 @@ def setPropertyThatWasAdded(self, propertyThatWasAdded: float):
             raise TypeError("propertyThatWasAdded must be a 'float'.")
         self.__data.setTraitProperty(self.kId, "propertyThatWasAdded", propertyThatWasAdded)
 
-    def getPropertyThatWasAdded(self, defaultValue: float=None) -> Union[float, None]:
+    def getPropertyThatWasAdded(self, defaultValue: float = None) -> Union[float, None]:
         """
         Gets the value of the propertyThatWasAdded property or the supplied default.
 
@@ -146,7 +153,9 @@ def getPropertyThatWasAdded(self, defaultValue: float=None) -> Union[float, None
 
         if not isinstance(value, float):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'float'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'float'."
+                )
             return defaultValue
         return value
 
@@ -160,7 +169,7 @@ def setPropertyThatWasRenamed(self, propertyThatWasRenamed: bool):
             raise TypeError("propertyThatWasRenamed must be a 'bool'.")
         self.__data.setTraitProperty(self.kId, "propertyThatWasRenamed", propertyThatWasRenamed)
 
-    def getPropertyThatWasRenamed(self, defaultValue: bool=None) -> Union[bool, None]:
+    def getPropertyThatWasRenamed(self, defaultValue: bool = None) -> Union[bool, None]:
         """
         Gets the value of the propertyThatWasRenamed property or the supplied default.
 
@@ -172,7 +181,9 @@ def getPropertyThatWasRenamed(self, defaultValue: bool=None) -> Union[bool, None
 
         if not isinstance(value, bool):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'bool'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'bool'."
+                )
             return defaultValue
         return value
 
@@ -186,7 +197,7 @@ def setPropertyToKeep(self, propertyToKeep: str):
             raise TypeError("propertyToKeep must be a 'str'.")
         self.__data.setTraitProperty(self.kId, "propertyToKeep", propertyToKeep)
 
-    def getPropertyToKeep(self, defaultValue: str=None) -> Union[str, None]:
+    def getPropertyToKeep(self, defaultValue: str = None) -> Union[str, None]:
         """
         Gets the value of the propertyToKeep property or the supplied default.
 
@@ -198,21 +209,20 @@ def getPropertyToKeep(self, defaultValue: str=None) -> Union[str, None]:
 
         if not isinstance(value, str):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'str'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'str'."
+                )
             return defaultValue
         return value
 
 
-# Alias to latest version
-UpdatedTrait = UpdatedTrait_v2
-
-
 class UpdatedTrait_v1:
     """
     An example.
     Usage: entity, locale, relationship
     """
-    kId = "openassetio-example:example.Updated.v001"
+
+    kId = "openassetio-example:example.Updated"
 
     def __init__(self, traitsData):
         """
@@ -259,7 +269,6 @@ def imbueTo(cls, traitsData):
         """
         traitsData.addTrait(cls.kId)
 
-
     def setPropertyToKeep(self, propertyToKeep: str):
         """
         Sets the propertyToKeep property.
@@ -270,7 +279,7 @@ def setPropertyToKeep(self, propertyToKeep: str):
             raise TypeError("propertyToKeep must be a 'str'.")
         self.__data.setTraitProperty(self.kId, "propertyToKeep", propertyToKeep)
 
-    def getPropertyToKeep(self, defaultValue: str=None) -> Union[str, None]:
+    def getPropertyToKeep(self, defaultValue: str = None) -> Union[str, None]:
         """
         Gets the value of the propertyToKeep property or the supplied default.
 
@@ -282,7 +291,9 @@ def getPropertyToKeep(self, defaultValue: str=None) -> Union[str, None]:
 
         if not isinstance(value, str):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'str'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'str'."
+                )
             return defaultValue
         return value
 
@@ -296,7 +307,7 @@ def setPropertyToRemove(self, propertyToRemove: bool):
             raise TypeError("propertyToRemove must be a 'bool'.")
         self.__data.setTraitProperty(self.kId, "propertyToRemove", propertyToRemove)
 
-    def getPropertyToRemove(self, defaultValue: bool=None) -> Union[bool, None]:
+    def getPropertyToRemove(self, defaultValue: bool = None) -> Union[bool, None]:
         """
         Gets the value of the propertyToRemove property or the supplied default.
 
@@ -308,7 +319,9 @@ def getPropertyToRemove(self, defaultValue: bool=None) -> Union[bool, None]:
 
         if not isinstance(value, bool):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'bool'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'bool'."
+                )
             return defaultValue
         return value
 
@@ -323,7 +336,7 @@ def setPropertyToRename(self, propertyToRename: bool):
             raise TypeError("propertyToRename must be a 'bool'.")
         self.__data.setTraitProperty(self.kId, "propertyToRename", propertyToRename)
 
-    def getPropertyToRename(self, defaultValue: bool=None) -> Union[bool, None]:
+    def getPropertyToRename(self, defaultValue: bool = None) -> Union[bool, None]:
         """
         Gets the value of the propertyToRename property or the supplied default.
 
@@ -336,17 +349,30 @@ def getPropertyToRename(self, defaultValue: bool=None) -> Union[bool, None]:
 
         if not isinstance(value, bool):
             if defaultValue is None:
-                raise TypeError(f"Invalid stored value type: '{type(value).__name__}' should be 'bool'.")
+                raise TypeError(
+                    f"Invalid stored value type: '{type(value).__name__}' should be 'bool'."
+                )
             return defaultValue
         return value
 
 
+# Alias to first version
+class UpdatedTrait(UpdatedTrait_v1):
+    def __init__(self, traitsData):
+        super().__init__(traitsData)
+        warnings.warn(
+            "Use of unversioned trait view classes is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+
 class AddedTrait_v1:
     """
     An example.
     Usage: entity, locale, relationship
     """
-    kId = "openassetio-example:example.Added.v001"
+
+    kId = "openassetio-example:example.Added"
 
     def __init__(self, traitsData):
         """
@@ -394,5 +420,12 @@ def imbueTo(cls, traitsData):
         traitsData.addTrait(cls.kId)
 
 
-# Alias to latest version
-AddedTrait = AddedTrait_v1
+# Alias to first version
+class AddedTrait(AddedTrait_v1):
+    def __init__(self, traitsData):
+        super().__init__(traitsData)
+        warnings.warn(
+            "Use of unversioned trait view classes is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )