From 2e2332990563b559c94f5297f20684fececca997 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=A9r=C3=B4me=20Deuchnord?=
 <Deuchnord@users.noreply.github.com>
Date: Sat, 20 Nov 2021 11:38:19 +0100
Subject: [PATCH] feat(deprecation): deprecate `Event.get_description()`
 function (#34)

---
 .github/PULL_REQUEST_TEMPLATE.md | 15 ++++++++-------
 kosmorrolib/core.py              | 12 ++++++++++++
 kosmorrolib/model.py             | 28 +++++++++++++++++++---------
 3 files changed, 39 insertions(+), 16 deletions(-)

diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index da1f9a2..38edb77 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -1,10 +1,11 @@
-| Q              | A
-| -------------- | ---
-| Bug fix?       | yes/no
-| New feature?   | yes/no
-| Related issues | Fix #... <!-- prefix each issue number with "Fix #", if any -->
-| Has BC-break   | yes/no
-| License        | GNU AGPL-v3
+| Q                | A
+| --------------   | ---
+| Bug fix?         | yes/no
+| New feature?     | yes/no
+| Related issues   | Fix #... <!-- prefix each issue number with "Fix #" -->
+| Documentation PR | Kosmorrolib/libdoc#... <!-- if you implement a new feature, a PR in the documentation is required -->
+| Has BC-break     | yes/no
+| License          | GNU AGPL-v3
 
 <!--
     Replace this notice with a short README for your feature/bugfix.
diff --git a/kosmorrolib/core.py b/kosmorrolib/core.py
index d512ee3..3424ab0 100644
--- a/kosmorrolib/core.py
+++ b/kosmorrolib/core.py
@@ -16,6 +16,7 @@
 #    You should have received a copy of the GNU Affero General Public License
 #    along with this program.  If not, see <https://www.gnu.org/licenses/>.
 
+from warnings import warn
 from skyfield.api import Loader
 from skyfield.timelib import Time
 from skyfield.nutationlib import iau2000b
@@ -48,3 +49,14 @@ def flatten_list(the_list: list):
         new_list.append(item)
 
     return new_list
+
+
+def deprecated(message):
+    def inner(decorated):
+        def f(*args, **kwargs):
+            warn(message, DeprecationWarning, stacklevel=2)
+            return decorated(*args, **kwargs)
+
+        return f
+
+    return inner
diff --git a/kosmorrolib/model.py b/kosmorrolib/model.py
index aadf068..7a04003 100644
--- a/kosmorrolib/model.py
+++ b/kosmorrolib/model.py
@@ -24,7 +24,7 @@ from math import asin
 from skyfield.api import Topos, Time, Angle
 from skyfield.vectorlib import VectorSum as SkfPlanet
 
-from .core import get_skf_objects, get_timescale
+from .core import get_skf_objects, get_timescale, deprecated
 from .enum import MoonPhaseType, EventType, ObjectIdentifier, ObjectType
 
 
@@ -239,17 +239,27 @@ class Event(Serializable):
             self.details,
         )
 
+    @deprecated(
+        "kosmorrolib.Event.get_description method is deprecated since version 1.1 "
+        "and will be removed in version 2.0. "
+        "It should be reimplemented it in your own code."
+    )
     def get_description(self, show_details: bool = True) -> str:
-        description = self.event_type.value % self._get_objects_name()
-        if show_details and self.details is not None:
-            description += " ({:s})".format(self.details)
-        return description
+        """Return a textual description for the given details
+
+        *Deprecated* since version 1.1
+        """
+        description = f"Event of type {str(self.event_type)}"
+        if show_details and len(self.details) > 0:
+            details = ""
+            for key in self.details:
+                if details != "":
+                    details += ", "
+                details += f"{key}: {self.details[key]}"
 
-    def _get_objects_name(self):
-        if len(self.objects) == 1:
-            return self.objects[0].name
+            description += f" ({details})"
 
-        return tuple(object.name for object in self.objects)
+        return description
 
     def serialize(self) -> dict:
         return {