diff --git a/CHANGES.rst b/CHANGES.rst index 106babf5..703e4b1c 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -6,9 +6,10 @@ Changelog Minor changes: -- Add a ``weekday`` attribute to ``vWeekday`` components. See `Issue 749 `_. -- Document ``vRecur`` property. See `Issue 758 `_. +- Add a ``weekday`` attribute to :class:`icalendar.prop.vWeekday` components. See `Issue 749 `_. +- Document :class:`icalendar.prop.vRecur` property. See `Issue 758 `_. - Print failure of doctest to aid debugging. +- Improve documentation of :class:`icalendar.prop.vGeo` - Fix tests, improve code readability, fix typing. See `Issue 766 `_ and `Issue 765 `_. Breaking changes: diff --git a/src/icalendar/prop.py b/src/icalendar/prop.py index 23312280..b86bcd77 100644 --- a/src/icalendar/prop.py +++ b/src/icalendar/prop.py @@ -1478,40 +1478,62 @@ class vGeo: GEO:37.386013;-122.082932 + Parse vGeo: + .. code-block:: pycon >>> from icalendar.prop import vGeo >>> geo = vGeo.from_ical('37.386013;-122.082932') >>> geo (37.386013, -122.082932) + + Add a geo location to an event: + + .. code-block:: pycon + + >>> from icalendar import Event + >>> event = Event() + >>> latitude = 37.386013 + >>> longitude = -122.082932 + >>> event.add('GEO', (latitude, longitude)) + >>> event['GEO'] + vGeo((37.386013, -122.082932)) """ - def __init__(self, geo): + def __init__(self, geo: tuple[float|str|int, float|str|int]): + """Create a new vGeo from a tuple of (latitude, longitude). + + Raises: + ValueError: if geo is not a tuple of (latitude, longitude) + """ try: latitude, longitude = (geo[0], geo[1]) latitude = float(latitude) longitude = float(longitude) - except Exception: - raise ValueError('Input must be (float, float) for ' - 'latitude and longitude') + except Exception as e: + raise ValueError("Input must be (float, float) for " + "latitude and longitude") from e self.latitude = latitude self.longitude = longitude self.params = Parameters() def to_ical(self): - return f'{self.latitude};{self.longitude}' + return f"{self.latitude};{self.longitude}" @staticmethod def from_ical(ical): try: - latitude, longitude = ical.split(';') + latitude, longitude = ical.split(";") return (float(latitude), float(longitude)) - except Exception: - raise ValueError(f"Expected 'float;float' , got: {ical}") + except Exception as e: + raise ValueError(f"Expected 'float;float' , got: {ical}") from e def __eq__(self, other): return self.to_ical() == other.to_ical() + def __repr__(self): + """repr(self)""" + return f"{self.__class__.__name__}(({self.latitude}, {self.longitude}))" class vUTCOffset: """UTC Offset