[Kakao] Move permalink function out of class

docs/streetlevel.kakao.rst

@@ -87,3 +87,7 @@ Data classes and enums
     .. autoclass:: streetlevel.kakao.panorama.PanoramaType
       :members:
       :member-order: bysource
+
+Miscellaneous
+-------------
+    .. autofunction:: streetlevel.kakako.build_permalink

streetlevel/kakao/__init__.py

@@ -1 +1,2 @@
 from .kakao import *
+from .util import *

streetlevel/kakao/panorama.py

@@ -1,12 +1,12 @@
 from __future__ import annotations
 
-import math
-from dataclasses import dataclass, field
+from dataclasses import dataclass
 from datetime import datetime
 from enum import IntEnum
 from typing import List
 
 from streetlevel.dataclasses import Link
+from .util import build_permalink
 
 
 class PanoramaType(IntEnum):
@@ -85,20 +85,16 @@ def permalink(self: KakaoPanorama, heading: float = 0.0, pitch: float = 0.0, rad
         """
         Creates a permalink to a panorama at this location.
 
-        The link will only work as expected for the most recent coverage at a location -
+        The link will only work as expected for the most recent coverage at a location --
         it does not appear to be possible to directly link to older panoramas.
 
         :param heading: *(optional)* Initial heading of the viewport. Defaults to 0°.
         :param pitch: *(optional)* Initial pitch of the viewport. Defaults to 0°.
         :param radians: *(optional)* Whether angles are in radians. Defaults to False.
         :return: A KakaoMap URL.
         """
-        if radians:
-            heading = math.degrees(heading)
-            pitch = math.degrees(pitch)
-        return f"https://map.kakao.com/?map_type=TYPE_MAP&map_attribute=ROADVIEW" \
-               f"&panoid={self.id}&pan={heading}&tilt={pitch}&zoom=0&urlLevel=3" \
-               f"&urlX={self.wcongx}&urlY={self.wcongy}"
+        return build_permalink(id=self.id, wcongx=self.wcongx, wcongy=self.wcongy,
+                               heading=heading, pitch=pitch, radians=radians)
 
     def __repr__(self):
         output = str(self)

streetlevel/kakao/util.py

@@ -0,0 +1,35 @@
+import math
+
+
+def build_permalink(id: int = None, wcongx: float = None, wcongy: float = None,
+                    heading: float = 0.0, pitch: float = 0.0, radians: bool = False) -> str:
+    """
+    Creates a permalink to a panorama. All parameters are optional, but
+    either a location, or a pano ID, or both must be passed.
+
+    When linking by ID, the link will only work as expected for the most recent coverage
+    at a location -- it does not appear to be possible to directly link to older panoramas.
+
+    :param id: The pano ID.
+    :param wcongx: X coordinate of the panorama's location in the WCongnamul coordinate system.
+    :param wcongy: Y coordinate of the panorama's location in the WCongnamul coordinate system.
+    :param heading: *(optional)* Initial heading of the viewport. Defaults to 0°.
+    :param pitch: *(optional)* Initial pitch of the viewport. Defaults to 0°.
+    :param radians: *(optional)* Whether angles are in radians. Defaults to False.
+    :return: A KakaoMap URL which will open the given panorama.
+    """
+    if id is None and (wcongx is None or wcongy is None):
+        raise ValueError("You must pass a location, or pano ID, or both.")
+    elif id is None:
+        id = 0
+    elif wcongx is None and wcongy is None:
+        (wcongx, wcongy) = (0.0, 0.0)
+    elif (wcongx is None and wcongy is not None) or (wcongx is not None and wcongy is None):
+        raise ValueError("wcongx and wcongx must either both be set or both be null.")
+
+    if radians:
+        heading = math.degrees(heading)
+        pitch = math.degrees(pitch)
+    url = f"https://map.kakao.com/?map_type=TYPE_MAP&map_attribute=ROADVIEW&panoid={id}" \
+          f"&urlX={wcongx}&urlY={wcongy}&pan={heading}&tilt={pitch}&zoom=0&urlLevel=3"
+    return url