events: Add backwards compatibility for old event names

In 8c54bb1 and e7567d4
basic event names were refactored. As this is the first change of the
most stable part of mutwo since its inception four years ago, this may
lead to the biggest breaking dependents of 'mutwo.core'. To make the
migration to 'mutwo.core > 2.0.0' easier we therefore add pointers to
the old events names. We don't add a pointer to the deprecated
'ComplexEvent', as this is barely used outside of 'mutwo.core' and
therefore has a much lower necessity. This patch also adds a 'deprecated' decorator,
that functions similar to the new 'deprecated' decorator in python3.13 [1].
Once we are using python 3.13, we can therefore replace the
'core_utilities.deprecated' decorator with the more powerful and more
clever implemented builtin version.

[1] https://docs.python.org/3.13/library/warnings.html#warnings.deprecated

mutwo/core_events/__init__.py

@@ -1,6 +1,6 @@
 # This file is part of mutwo, ecosystem for time-based arts.
 #
-# Copyright (C) 2020-2023
+# Copyright (C) 2020-2024
 #
 # This program is free software: you can redistribute it and/or modify
 # it under the terms of the GNU General Public License as published by
@@ -45,8 +45,23 @@
 
 __all__ = core_utilities.get_all(basic, envelopes)
 
+# BBB: Before mutwo.core < 2.0.0, basic events had different
+# names. As this was the most stable, never touched part of mutwo during the
+# first four years of development, we keep these backwards compatibility
+# pointers for easier migration of code that used mutwo.core < 2.0.0.
+TaggedSequentialEvent = SequentialEvent = core_utilities.deprecated(
+    "'SequentialEvent' is deprecated, use 'Consecution'."
+)(Consecution)
+TaggedSimultaneousEvent = SimultaneousEvent = core_utilities.deprecated(
+    "'SimultaneousEvent' is deprecated, use 'Concurrence'."
+)(Concurrence)
+TaggedSimpleEvent = SimpleEvent = core_utilities.deprecated(
+    "'SimpleEvent' is deprecated, use 'Chronon'."
+)(Chronon)
+
 # Force flat structure
 del basic, core_utilities, envelopes
 
 from . import patchparameters
+
 del patchparameters

mutwo/core_utilities/tools.py

@@ -26,6 +26,7 @@
 import operator
 import types
 import typing
+import warnings
 
 try:
     import quicktions as fractions
@@ -58,6 +59,7 @@
     "get_all",
     "get_cls_logger",
     "str_to_number_parser",
+    "deprecated",
 )
 
 
@@ -648,3 +650,24 @@ def str_to_number_parser(string: str) -> typing.Callable:
         return fractions.Fraction
     else:
         return int
+
+
+def deprecated(info: typing.Optional[str] = None) -> typing.Callable:
+    """Mark a callable as deprecated.
+
+    :param info: Deprecation info printed to the user.
+    :type info: str
+    """
+
+    def _(f: typing.Callable):
+        def wrapper(*args, **kwargs):
+            o = f(*args, **kwargs)
+            try:
+                o._logger.warning(f"DeprecationWarning: {info or 'Deprecation'}")
+            except AttributeError:
+                warnings.warn(Warning(info or "Deprecation"))
+            return o
+
+        return wrapper
+
+    return _