Merge pull request #834 from niccokunzmann/issue-816

Deprecate the UID Generator

Author: niccokunzmann

CHANGES.rst

@@ -12,7 +12,7 @@ We use `Semantic Versioning <https://semver.org>`_.
 
 Minor changes:
 
-- Deprecate the UIDGenerator class. See `Issue 816 <https://github.com/collective/icalendar/issues/816>`.
+- Deprecate ``icalendar.UIDGenerator``. See `Issue 816 <https://github.com/collective/icalendar/issues/816>`_.
 
 Breaking changes:
 

pyproject.toml

@@ -189,6 +189,9 @@ norecursedirs = [
     "src/icalendar/tests/hypothesis",
     "build",
 ]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]
 
 [dependency-groups]
 dev = [

src/icalendar/__init__.py

@@ -19,6 +19,7 @@
 from icalendar.error import (
     ComponentEndMissing,
     ComponentStartMissing,
+    FeatureWillBeRemovedInFutureVersion,
     IncompleteAlarmInformation,
     IncompleteComponent,
     InvalidCalendar,
@@ -121,4 +122,5 @@
     "vSkip",
     "RELTYPE",
     "ROLE",
+    "FeatureWillBeRemovedInFutureVersion"
 ]

src/icalendar/error.py

@@ -44,12 +44,24 @@ class ComponentStartMissing(IncompleteAlarmInformation):
     Use Alarms.set_start().
     """
 
+class FeatureWillBeRemovedInFutureVersion(DeprecationWarning):
+    """This feature will be removed in a future version."""
+
+
+class WillBeRemovedInVersion7(FeatureWillBeRemovedInFutureVersion):
+    """This feature will be removed in icalendar version 7.
+
+    Suppress FeatureWillBeRemovedInFutureVersion instead.
+    """
 
 __all__ = [
     "InvalidCalendar",
     "IncompleteComponent",
     "IncompleteAlarmInformation",
     "LocalTimezoneMissing",
     "ComponentEndMissing",
+    
     "ComponentStartMissing",
+    "FeatureWillBeRemovedInFutureVersion",
+    "WillBeRemovedInVersion7",
 ]

src/icalendar/tests/test_unit_tools.py

@@ -79,3 +79,10 @@ def test_uid_generator_issue_345(args, kw, split, expected):
     """
     uid = UIDGenerator.uid(*args, **kw)
     assert uid.split(split)[1] == expected
+
+
+def test_warning():
+    with pytest.warns(DeprecationWarning):
+        UIDGenerator.uid()
+    with pytest.warns(DeprecationWarning):
+        UIDGenerator.rnd_string()

src/icalendar/tools.py

@@ -1,29 +1,62 @@
+"""Utility functions for icalendar."""
+
 from __future__ import annotations
+
 import random
 from datetime import date, datetime, tzinfo
 from string import ascii_letters, digits
+from warnings import warn
 
 from icalendar.parser_tools import to_unicode
 
+from .error import WillBeRemovedInVersion7
+
 
 class UIDGenerator:
-    """If you are too lazy to create real uid's."""
+    """Use this only if you're too lazy to create real UUIDs.
+    
+    .. deprecated:: 6.2.1
+
+        Use the Python standard library's :func:`uuid.uuid4` instead.
+    """
 
     chars = list(ascii_letters + digits)
 
     @staticmethod
-    def rnd_string(length=16):
-        """Generates a string with random characters of length."""
+    def rnd_string(length=16) -> str:
+        """Generates a string with random characters of length.
+
+         .. deprecated:: 6.2.1
+
+             Use the Python standard library's :func:`uuid.uuid4` instead.
+        """
+        warn(
+            "Use https://docs.python.org/3/library/uuid.html#uuid.uuid4 instead.",
+            WillBeRemovedInVersion7,
+            stacklevel=1
+        )
         return "".join([random.choice(UIDGenerator.chars) for _ in range(length)])
 
     @staticmethod
     def uid(host_name="example.com", unique=""):
-        """Generates a unique id consisting of:
-            datetime-uniquevalue@host.
-        Like:
-            [email protected]
+        """Generates a unique ID consisting of ``datetime-uniquevalue@host``.
+
+        For example:
+            
+            .. code-block:: text
+
+                [email protected]
+        
+        .. deprecated:: 6.2.1
+
+            Use the Python standard library's :func:`uuid.uuid5` instead.
         """
         from icalendar.prop import vDatetime, vText
+        warn(
+            "Use https://docs.python.org/3/library/uuid.html#uuid.uuid5 instead.",
+            WillBeRemovedInVersion7,
+            stacklevel=1
+        )
 
         host_name = to_unicode(host_name)
         unique = unique or UIDGenerator.rnd_string()