added params argument to class constructors

CHANGES.rst

@@ -1,5 +1,25 @@
 Changelog
 =========
+6.1.2 (unreleased 2025-03-19)
+------------------
+
+Minor changes:
+
+- Set default value for ``params`` as ``params={}`` in mulitple constructors in ``icalendar.prop`` to improve usability.
+- Improve object initialization performance in ``icalendar.prop``.
+- Add type hint for ``params`` in multiple constructors in ``icalendar.prop``.
+
+Breaking changes:
+
+- ...
+
+New features:
+
+- ...
+
+Bug fixes:
+
+- ...
 
 6.1.2 (unreleased)
 ------------------

docs/credits.rst

@@ -78,6 +78,7 @@ icalendar contributors
 - `Soham Dutta <https://github.com/NP-compete>`_
 - `Serif OZ  <https://github.com/SerifOZ>`_
 - David Venhoff <https://github.com/david-venhoff>
+- `Tariq <https://github.com/Horisyre>`_
 
 Find out who contributed::
 

src/icalendar/prop.py

@@ -140,9 +140,9 @@ class vBoolean(int):
 
     BOOL_MAP = CaselessDict({'true': True, 'false': False})
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls, *args,params={}, **kwargs):
         self = super().__new__(cls, *args, **kwargs)
-        self.params = Parameters()
+        self.params =Parameters(params)
         return self
 
     def to_ical(self):
@@ -162,11 +162,11 @@ class vText(str):
 
     params: Parameters
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING,params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         self.encoding = encoding
-        self.params = Parameters()
+        self.params=Parameters(params)
         return self
 
     def __repr__(self) -> str:
@@ -222,10 +222,10 @@ class vCalAddress(str):
 
     params: Parameters
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING,params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
-        self.params = Parameters()
+        self.params =Parameters(params)
         return self
 
     def __repr__(self):
@@ -302,9 +302,9 @@ class vFloat(float):
 
     params: Parameters
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls,*args, params={}, **kwargs):
         self = super().__new__(cls, *args, **kwargs)
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self):
@@ -369,9 +369,9 @@ class vInt(int):
 
     params: Parameters
 
-    def __new__(cls, *args, **kwargs):
+    def __new__(cls, *args,params={}, **kwargs):
         self = super().__new__(cls, *args, **kwargs)
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self) -> bytes:
@@ -430,11 +430,11 @@ class vCategory:
     
     params: Parameters
 
-    def __init__(self, c_list):
+    def __init__(self, c_list, params={}):
         if not hasattr(c_list, '__iter__') or isinstance(c_list, str):
             c_list = [c_list]
         self.cats = [vText(c) for c in c_list]
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def __iter__(self):
         return iter(vCategory.from_ical(self.to_ical()))
@@ -624,9 +624,9 @@ class vDatetime(TimeBase):
     
     params: Parameters
 
-    def __init__(self, dt):
+    def __init__(self, dt, params={}):
         self.dt = dt
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def to_ical(self):
         dt = self.dt
@@ -761,11 +761,11 @@ class vDuration(TimeBase):
     
     params: Parameters
 
-    def __init__(self, td):
+    def __init__(self, td,params={}):
         if not isinstance(td, timedelta):
             raise ValueError('Value MUST be a timedelta instance')
         self.td = td
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def to_ical(self):
         sign = ""
@@ -988,7 +988,7 @@ class vWeekday(str):
         "SU": 0, "MO": 1, "TU": 2, "WE": 3, "TH": 4, "FR": 5, "SA": 6,
     })
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING,params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         match = WEEKDAY_RULE.match(self)
@@ -1004,7 +1004,7 @@ class vWeekday(str):
         self.relative = relative and int(relative) or None
         if sign == '-' and self.relative:
             self.relative *= -1
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self):
@@ -1034,12 +1034,12 @@ class vFrequency(str):
         "YEARLY": "YEARLY",
     })
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING, params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
         if self not in vFrequency.frequencies:
             raise ValueError(f'Expected frequency, got: {self}')
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self):
@@ -1083,7 +1083,7 @@ class vMonth(int):
         
     params: Parameters
 
-    def __new__(cls, month:Union[str, int]):
+    def __new__(cls, month:Union[str, int], params={}):
         if isinstance(month, vMonth):
             return cls(month.to_ical().decode())
         if isinstance(month, str):
@@ -1100,7 +1100,7 @@ class vMonth(int):
             month_index = int(month)
         self = super().__new__(cls, month_index)
         self.leap = leap
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self) -> bytes:
@@ -1249,12 +1249,12 @@ class vRecur(CaselessDict):
         'SKIP': vSkip,
     })
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args,params={}, **kwargs):
         for k, v in kwargs.items():
             if not isinstance(v, SEQUENCE_TYPES):
                 kwargs[k] = [v]
         super().__init__(*args, **kwargs)
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def to_ical(self):
         result = []
@@ -1477,10 +1477,10 @@ class vUri(str):
     
     params: Parameters
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING, params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self):
@@ -1555,7 +1555,7 @@ class vGeo:
     
     params: Parameters
 
-    def __init__(self, geo: tuple[float|str|int, float|str|int]):
+    def __init__(self, geo: tuple[float|str|int, float|str|int], params={}):
         """Create a new vGeo from a tuple of (latitude, longitude).
 
         Raises:
@@ -1570,7 +1570,7 @@ class vGeo:
                              "latitude and longitude") from e
         self.latitude = latitude
         self.longitude = longitude
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def to_ical(self):
         return f"{self.latitude};{self.longitude}"
@@ -1646,11 +1646,11 @@ class vUTCOffset:
     # it, rather than let the exception
     # propagate upwards
 
-    def __init__(self, td):
+    def __init__(self, td, params={}):
         if not isinstance(td, timedelta):
             raise ValueError('Offset value MUST be a timedelta instance')
         self.td = td
-        self.params = Parameters()
+        self.params = Parameters(params)
 
     def to_ical(self):
 
@@ -1711,10 +1711,10 @@ class vInline(str):
     
     params: Parameters
 
-    def __new__(cls, value, encoding=DEFAULT_ENCODING):
+    def __new__(cls, value, encoding=DEFAULT_ENCODING, params={}):
         value = to_unicode(value, encoding=encoding)
         self = super().__new__(cls, value)
-        self.params = Parameters()
+        self.params = Parameters(params)
         return self
 
     def to_ical(self):

src/icalendar/tests/prop/test_constructors.py

@@ -0,0 +1,116 @@
+
+from icalendar.prop  import  vBoolean,vInline , vUTCOffset, vCategory, vCalAddress, vWeekday, vDuration, vFloat, vGeo, vInt,  vText, vMonth, vUTCOffset, vFrequency,  vRecur,  vDatetime, vDDDTypes, vUri
+import datetime
+
+def test_param_vCategory():
+    try:
+        obj = vCategory(["Work", "Personal"], params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vCategory)  
+    except Exception as e:
+        assert False, f"Error creating vCategory object: {e}"  
+
+def test_param_vCalAddress():
+    try:
+        obj = vCalAddress('mailto:jane_doe@example.com',params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vCalAddress) 
+    except Exception as e:
+        assert False, f"Error creating vCalAddress object: {e}"  
+
+def test_param_vWeekday():
+    try:
+        obj = vWeekday("2FR",params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vWeekday)  
+    except Exception as e:
+        assert False, f"Error creating vWeekday object: {e}"  
+
+def test_param_vBoolean():
+    try:
+        obj = vBoolean(True, params={"SOME_PARAM":"VALUE"})  
+        assert isinstance(obj, vBoolean)  
+    except Exception as e:
+        assert False, f"Error creating vBoolean object: {e}" 
+
+def test_param_vDuration():
+    try:
+        td=datetime.timedelta(days=15, seconds=18020)
+        obj = vDuration(td, params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vDuration)  
+    except Exception as e:
+        assert False, f"Error creating vDuration object: {e}"  
+
+def test_param_vFloat():
+    try:
+        obj = vFloat('1.333',params={"SOME_PARAAM":"VALUE"})
+        
+        assert isinstance(obj, vFloat)  
+    except Exception as e:
+        assert False, f"Error creating vFloat object: {e}"  
+
+def test_param_vGeo():
+    try:
+        obj = vGeo((37.386013, -122.082932),params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vGeo) 
+    except Exception as e:
+        assert False, f"Error creating vGeo object: {e}"  
+
+def test_param_vInt():
+    try:
+        obj = vInt('87',params={"SOME_PARAAM":"VALUE"})  
+        assert isinstance(obj, vInt)  
+    except Exception as e:
+        assert False, f"Error creating vInt object: {e}"  
+
+def test_param_vInline():
+    try:
+        obj = vInline("sometxt", params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vInline)  
+    except Exception as e:
+        assert False, f"Error creating vInline object: {e}"  
+def test_param_vText():
+    try:
+        obj = vText("sometxt", params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vText)  
+    except Exception as e:
+        assert False, f"Error creating vText object: {e}"  
+
+def test_param_vMonth():
+    try:
+        obj = vMonth(1,params={"SOME_PARAAM":"VALUE"})  
+        assert isinstance(obj, vMonth)  
+    except Exception as e:
+        assert False, f"Error creating vMonth object: {e}"  
+
+def test_param_vUTCOffset():
+    try:
+        obj =  vUTCOffset(datetime.timedelta(days=-1, seconds=68400),params={"SOME_PARAM":"VALUE"})  
+        assert isinstance(obj, vUTCOffset)  
+    except Exception as e:
+        assert False, f"Error creating vUTCOffset object: {e}"  
+
+def test_param_vFrequency():
+    try:
+        obj = vFrequency("DAILY",params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vFrequency) 
+    except Exception as e:
+        assert False, f"Error creating vFrequency object: {e}"  
+
+ 
+def test_param_vRecur():
+    try:
+        obj =vRecur({'FREQ': ['DAILY'], 'COUNT': [10]}, params={"SOME_PARAAM":"VALUE"})
+    except Exception as e:
+        assert False, f"Error creating vRecur object: {e}"  
+
+def test_param_vDatetime():
+    try:
+        dt = datetime.datetime(2025, 3, 16, 14, 30, 0, tzinfo=datetime.timezone.utc)
+        obj = vDatetime(dt,params={"SOME_PARAAM":"VALUE"})  
+        assert isinstance(obj, vDatetime)  
+    except Exception as e:
+        assert False, f"Error creating vDatetime object: {e}"  
+def test_param_vUri():
+    try:
+        obj = uri_instance = vUri("WWW.WESBITE.COM",params={"SOME_PARAAM":"VALUE"}) 
+        assert isinstance(obj, vUri)  
+    except Exception as e:
+        assert False, f"Error creating vUri object: {e}"