Trait versioning design sketch

examples/resources/working_with_trait_versions/example.yml

@@ -0,0 +1,95 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/OpenAssetIO/OpenAssetIO-TraitGen/main/python/openassetio_traitgen/schema.json
+# yamllint disable-line rule:document-start
+package: openassetio-example
+description: An example traits schema
+
+traits:
+  example:
+    description: Example namespace
+    members:
+
+      Deprecated:
+        deprecated: true
+        versions:
+          1:
+            description: An example.
+            usage:
+            - entity
+            - locale
+            - relationship
+
+      Added:
+        versions:
+          1:
+            description: An example.
+            usage:
+              - entity
+              - locale
+              - relationship
+
+      Updated:
+        versions:
+          1:
+            description: An example.
+            usage:
+              - entity
+              - locale
+              - relationship
+            properties:
+              propertyToKeep:
+                type: string
+                description: A property that is unchanged between versions.
+              propertyToRename:
+                type: boolean
+                description: >
+                  A property that has an inappropriate name and should be renamed in the
+                  next version.
+              propertyToRemove:
+                type: boolean
+                description: A defunct property that should be removed in the next version.
+          2:
+            description: An example.
+            usage:
+              - entity
+              - locale
+              - relationship
+            properties:
+              propertyToKeep:
+                type: string
+                description: A property that is unchanged between versions.
+              propertyThatWasRenamed:
+                type: boolean
+                description: A property that has been renamed.
+              propertyThatWasAdded:
+                type: float
+                description: A new property added in the latest version.
+
+specifications:
+  example:
+    description: Test specifications.
+    members:
+
+      Example:
+        versions:
+          1:
+            description: An example.
+            usage:
+              - entity
+            traitSet:
+              - namespace: example
+                name: Added
+                version: 1
+              - namespace: example
+                name: Updated
+                version: 1
+          2:
+            description: An example.
+            usage:
+              - entity
+            traitSet:
+              - namespace: example
+                name: Added
+                version: 1
+              - namespace: example
+                name: Updated
+                version: 2

examples/resources/working_with_trait_versions/openassetio_example/__init__.py

@@ -0,0 +1,8 @@
+"""
+An example traits schema
+"""
+
+# WARNING: This file is auto-generated by openassetio-traitgen, do not edit.
+
+from . import traits
+from . import specifications

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

@@ -0,0 +1,7 @@
+"""
+Specifications defined in the 'openassetio-example' package.
+"""
+
+# WARNING: This file is auto-generated by openassetio-traitgen, do not edit.
+
+from . import example

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

@@ -0,0 +1,139 @@
+
+"""
+Specification definitions in the 'example' namespace.
+
+Test specifications.
+"""
+
+# WARNING: This file is auto-generated by openassetio-traitgen, do not edit.
+
+from openassetio.trait import TraitsData
+
+
+from .. import traits
+
+
+class ExampleSpecification_v2:
+    """
+    An example.
+    Usage: entity
+    """
+    kTraitSet = {
+        # 'openassetio-example:example.Deprecated'
+        traits.example.AddedTrait_v1.kId,
+        # 'openassetio-example:example.Updated'
+        traits.example.UpdatedTrait_v2.kId,
+
+    }
+
+    def __init__(self, traitsData):
+        """
+        Constructs the specification as a view on the supplied
+        shared @fqref{TraitsData} "TraitsData" instance.
+
+        @param traitsData @fqref{TraitsData} "TraitsData"
+
+        @warning Specifications are always a view on the supplied data,
+        which is held by reference. Any changes made to the data will be
+        visible to any other specifications or @ref trait "traits" that
+        wrap the same TraitsData instance.
+        """
+        if not isinstance(traitsData, TraitsData):
+            raise TypeError("Specifications must be constructed with a TraitsData instance")
+        self.__data = traitsData
+
+    def traitsData(self):
+        """
+        Returns the underlying (shared) @fqref{TraitsData} "TraitsData"
+        instance held by this specification.
+        """
+        return self.__data
+
+    @classmethod
+    def create(cls):
+        """
+        Returns a new instance of the Specification, holding a new
+        @fqref{TraitsData} "TraitsData" instance, pre-populated with all
+        of the specifications traits.
+        """
+        data = TraitsData(cls.kTraitSet)
+        return cls(data)
+
+    def addedTrait(self):
+        """
+        Returns the view for the 'openassetio-example:example.Unchanged' trait wrapped around
+        the data held in this instance.
+        """
+        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_v2(self.traitsData())
+
+
+class ExampleSpecification_v1:
+    """
+    An example.
+    Usage: entity
+    """
+    kTraitSet = {
+        # 'openassetio-example:example.Deprecated'
+        traits.example.AddedTrait_v1.kId,
+        # 'openassetio-example:example.Updated'
+        traits.example.UpdatedTrait_v1.kId,
+
+    }
+
+    def __init__(self, traitsData):
+        """
+        Constructs the specification as a view on the supplied
+        shared @fqref{TraitsData} "TraitsData" instance.
+
+        @param traitsData @fqref{TraitsData} "TraitsData"
+
+        @warning Specifications are always a view on the supplied data,
+        which is held by reference. Any changes made to the data will be
+        visible to any other specifications or @ref trait "traits" that
+        wrap the same TraitsData instance.
+        """
+        if not isinstance(traitsData, TraitsData):
+            raise TypeError("Specifications must be constructed with a TraitsData instance")
+        self.__data = traitsData
+
+    def traitsData(self):
+        """
+        Returns the underlying (shared) @fqref{TraitsData} "TraitsData"
+        instance held by this specification.
+        """
+        return self.__data
+
+    @classmethod
+    def create(cls):
+        """
+        Returns a new instance of the Specification, holding a new
+        @fqref{TraitsData} "TraitsData" instance, pre-populated with all
+        of the specifications traits.
+        """
+        data = TraitsData(cls.kTraitSet)
+        return cls(data)
+
+    def addedTrait(self):
+        """
+        Returns the view for the 'openassetio-example:example.Unchanged' trait wrapped around
+        the data held in this instance.
+        """
+        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_v2(self.traitsData())
+
+
+# Alias for first version.
+ExampleSpecification = ExampleSpecification_v1

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

@@ -0,0 +1,7 @@
+"""
+Traits defined in the 'openassetio-example' package.
+"""
+
+# WARNING: This file is auto-generated by openassetio-traitgen, do not edit.
+
+from . import example