feat: Support deep_planning_clone class decorator (#1271)

This brings parity with the Java version.

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

@@ -9,7 +9,6 @@
 Solution_ = TypeVar('Solution_')
 Entity_ = TypeVar('Entity_')
 
-
 class PlanningId(JavaAnnotation):
     """
     Specifies that an attribute is the id to match when locating
@@ -654,13 +653,14 @@ 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.
+    Not needed for `planning_solution` or `planning_entity` attributes because those are automatically deep 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`),
@@ -878,6 +878,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[Entity_] = None) -> Type[Entity_]:
+    """
+    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',
@@ -888,4 +914,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']

python/python-core/tests/test_domain.py

@@ -954,3 +954,69 @@ class Solution:
     solution = solver.solve(problem)
     assert solution.score.score == 0
     assert solution.entity.value == [1, 2, 3]
+
+def test_deep_clone_class():
+    @deep_planning_clone
+    @dataclass
+    class Code:
+        value: str
+        parent_entity: 'Entity' = field(default=None)
+
+    @dataclass
+    class Value:
+        code: Code
+
+    @planning_entity
+    @dataclass
+    class Entity:
+        code: Code
+        value: Annotated[Value, PlanningVariable] = field(default=None)
+
+    def assign_to_v1(constraint_factory: ConstraintFactory):
+        return (constraint_factory.for_each(Entity)
+                .filter(lambda e: e.value.code.value == 'v1')
+                .reward(SimpleScore.ONE)
+                .as_constraint('assign to v1')
+                )
+
+    @constraint_provider
+    def my_constraints(constraint_factory: ConstraintFactory):
+        return [
+            assign_to_v1(constraint_factory)
+        ]
+
+    @planning_solution
+    @dataclass
+    class Solution:
+        entities: Annotated[List[Entity], PlanningEntityCollectionProperty]
+        values: Annotated[List[Value], ProblemFactCollectionProperty, ValueRangeProvider]
+        codes: Annotated[List[Code], ProblemFactCollectionProperty]
+        score: Annotated[SimpleScore, PlanningScore] = field(default=None)
+
+    solver_config = SolverConfig(
+        solution_class=Solution,
+        entity_class_list=[Entity],
+        score_director_factory_config=ScoreDirectorFactoryConfig(
+            constraint_provider_function=my_constraints
+        ),
+        termination_config=TerminationConfig(
+            best_score_limit='2'
+        )
+    )
+
+    e1 = Entity(Code('e1'))
+    e1.code.parent_entity = e1
+    e2 = Entity(Code('e2'))
+    e2.code.parent_entity = e2
+
+    v1 = Value(Code('v1'))
+    v2 = Value(Code('v2'))
+
+    problem = Solution([e1, e2], [v1, v2], [e1.code, e2.code, v1.code, v2.code])
+    solver = SolverFactory.create(solver_config).build_solver()
+    solution = solver.solve(problem)
+
+    assert solution.score.score == 2
+    assert solution.entities[0].value == v1
+    assert solution.codes[0].parent_entity == solution.entities[0]
+    assert solution.codes[0] is not e1.code