feat: Support deep_planning_clone class decorator

Author: luxaritas

docs/src/modules/ROOT/pages/using-timefold-solver/modeling-planning-problems.adoc

@@ -2659,6 +2659,10 @@ If any of your problem facts needs to be deep cloned for a planning clone,
 for example if the problem fact references a planning entity or the planning solution,
 mark its class with a `@DeepPlanningClone` annotation:
 
+[tabs]
+===
+Java::
++
 [source,java,options="nowrap"]
 ----
 @DeepPlanningClone
@@ -2669,13 +2673,42 @@ public class SeatDesignationDependency {
 }
 ----
 
+Python::
++
+[source,python,options="nowrap"]
+----
+@deep_planning_clone
+class SeatDesignationDependency:
+    leftSeatDesignation: SeatDesignation # planning entity
+    rightSeatDesignation: SeatDesignation # planning entity
+----
+====
+
 In the example above, because `SeatDesignationDependency` references the planning entity `SeatDesignation`
 (which is deep planning cloned automatically), it should also be deep planning cloned.
 
 Alternatively, the `@DeepPlanningClone` annotation also works on a getter method or a field to planning clone it.
 If that property is a `Collection` or a `Map`, it will shallow clone it and deep planning clone
 any element thereof that is an instance of a class that has a `@DeepPlanningClone` annotation.
 
+[tabs]
+====
+Java::
++
+[source,java,options="nowrap"]
+----
+    @DeepPlanningClone
+    private SeatDesignationDependency seatDesignationDependency;
+----
+
+Python::
++
+[source,python,options="nowrap"]
+----
+seat_designation_dependency: Annotated[SeatDesignationDependency, DeepPlanningClone]
+----
+====
+
 [NOTE]
 ====
 Values of Java's `enum` and `record` types are never deep-cloned.

python/python-core/src/main/python/domain/_annotations.py

@@ -653,13 +653,13 @@ def __init__(self, *,
 
 class DeepPlanningClone(JavaAnnotation):
     """
-    Marks a problem fact class as being required to be deep planning cloned.
-    Not needed for a `planning_solution` or `planning_entity` because those are automatically deep cloned.
-    It can also mark an attribute as being required to be deep planning cloned.
+    Marks an attribute as being required to be deep planning cloned.
     This is especially useful for `list` (or `dict`) properties.
     Not needed for a `list` (or `dist`) attribute with a generic type of `planning_entity`,
     because those are automatically deep cloned.
 
+    To annotate a class, use @deep_planning_clone
+
     Notes
     -----
     If it annotates an attribute returning `list` (or `dict`),
@@ -873,6 +873,32 @@ def constraint_configuration(constraint_configuration_class: Type[Solution_]) ->
     out = add_class_annotation(JavaConstraintConfiguration)(constraint_configuration_class)
     return out
 
+def deep_planning_clone(entity_class: Type[A] = None) -> Type[A]:
+    """
+    Marks a problem fact class as being required to be deep planning cloned.
+    Not needed for a `planning_solution` or `planning_entity` because those are automatically deep cloned.
+
+    To annotate an attribute, use DeepPlanningClone
+
+    Examples
+    --------
+    >>> from timefold.solver.domain import deep_planning_clone
+    >>>
+    >>> @deep_planning_clone
+    ... @dataclass
+    ... class Timeslot:
+    ...     day_of_week: str
+    ...     start_time: time
+    ...     end_time: time
+    """
+    ensure_init()
+    from _jpyinterpreter import add_class_annotation
+    from .._timefold_java_interop import _add_to_compilation_queue
+    from ai.timefold.solver.core.api.domain.solution.cloner import (
+            DeepPlanningClone as JavaDeepPlanningClone)
+    out = add_class_annotation(JavaDeepPlanningClone)(entity_class)
+    _add_to_compilation_queue(entity_class)
+    return out
 
 __all__ = ['PlanningId', 'PlanningScore', 'PlanningPin', 'PlanningPinToIndex',
            'PlanningVariable', 'PlanningVariableGraphType', 'PlanningListVariable',
@@ -883,4 +909,4 @@ def constraint_configuration(constraint_configuration_class: Type[Solution_]) ->
            'PlanningEntityProperty', 'PlanningEntityCollectionProperty',
            'ValueRangeProvider', 'DeepPlanningClone', 'ConstraintConfigurationProvider',
            'ConstraintWeight',
-           'planning_entity', 'planning_solution', 'constraint_configuration']
+           'planning_entity', 'planning_solution', 'constraint_configuration', 'deep_planning_clone']