finish docstrings for data models

voice/CHANGES.md

@@ -1,3 +1,6 @@
+# 1.0.4
+- Add docstrings to data models
+
 # 1.0.3
 - Internal refactoring
 

voice/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = 'vonage-voice'
-version = '1.0.3'
+dynamic = ["version"]
 description = 'Vonage voice package'
 readme = "README.md"
 authors = [{ name = "Vonage", email = "devrel@vonage.com" }]
@@ -24,6 +24,9 @@ classifiers = [
 [project.urls]
 homepage = "https://github.com/Vonage/vonage-python-sdk"
 
+[tool.setuptools.dynamic]
+version = { attr = "vonage_voice._version.__version__" }
+
 [build-system]
 requires = ["setuptools>=61.0", "wheel"]
 build-backend = "setuptools.build_meta"

voice/src/vonage_voice/_version.py

@@ -0,0 +1 @@
+__version__ = '1.0.4'

voice/src/vonage_voice/models/common.py

@@ -6,30 +6,69 @@
 
 
 class Phone(BaseModel):
+    """Model for a phone number.
+
+    Args:
+        number (PhoneNumber): The phone number.
+    """
+
     number: PhoneNumber
     type: Channel = Channel.PHONE
 
 
 class Sip(BaseModel):
+    """Model for a SIP URI.
+
+    Args:
+        uri (SipUri): The SIP URI.
+    """
+
     uri: SipUri
     type: Channel = Channel.SIP
 
 
 class Websocket(BaseModel):
+    """Model for a WebSocket connection.
+
+    Args:
+        uri (str): The URI of the WebSocket connection.
+        content_type (Literal['audio/l16;rate=8000', 'audio/l16;rate=16000']): The content
+            type of the audio stream.
+        headers (Optional[dict]): The headers to include with the WebSocket connection.
+    """
+
     uri: str = Field(..., min_length=1, max_length=50)
     content_type: Literal['audio/l16;rate=8000', 'audio/l16;rate=16000'] = Field(
         'audio/l16;rate=16000', serialization_alias='content-type'
     )
-    type: Channel = Channel.WEBSOCKET
     headers: Optional[dict] = None
+    type: Channel = Channel.WEBSOCKET
 
 
 class Vbc(BaseModel):
+    """Model for a VBC connection.
+
+    Args:
+        extension (str): The extension to call.
+    """
+
     extension: str
     type: Channel = Channel.VBC
 
 
 class AdvancedMachineDetection(BaseModel):
+    """Model for advanced machine detection settings. Configure the behavior of Vonage's
+    advanced machine detection. Overrides `machine_detection` if both are set.
+
+    Args:
+        behavior (Optional[Literal['continue', 'hangup']]): The behavior when a machine
+            is detected.
+        mode (Optional[Literal['default', 'detect', 'detect_beep']]): Detect if machine
+            answered and sends a human or machine status in the webhook payload.
+        beep_timeout (Optional[int]): Maximum time in seconds Vonage should wait for a
+            machine beep to be detected.
+    """
+
     behavior: Optional[Literal['continue', 'hangup']] = None
     mode: Optional[Literal['default', 'detect', 'detect_beep']] = None
     beep_timeout: Optional[int] = Field(None, ge=45, le=120)

voice/src/vonage_voice/models/connect_endpoints.py

@@ -7,23 +7,56 @@
 
 
 class OnAnswer(BaseModel):
+    """Settings for what to do when the call is answered.
+
+    Args:
+        url (str): The URL to fetch the NCCO from. The URL serves an NCCO to execute in the
+            number being connected to, before that call is joined to your existing conversation.
+        ringbackTone (Optional[str]): A URL value that points to a `ringbackTone` to be played
+            back on repeat to the caller, so they do not hear silence.
+    """
+
     url: str
     ringbackTone: Optional[str] = None
 
 
 class PhoneEndpoint(BaseModel):
+    """Model for a phone endpoint.
+
+    Args:
+        number (PhoneNumber): The phone number to call.
+        dtmfAnswer (Optional[Dtmf]): The DTMF tones to send when the call is answered.
+        onAnswer (Optional[OnAnswer]): Settings for what to do when the call is answered.
+    """
+
     number: PhoneNumber
     dtmfAnswer: Optional[Dtmf] = None
     onAnswer: Optional[OnAnswer] = None
     type: ConnectEndpointType = ConnectEndpointType.PHONE
 
 
 class AppEndpoint(BaseModel):
+    """Model for an RTC capable application endpoint.
+
+    Args:
+        user (str): The username of the user to connect to. This username must have been
+            added as a user.
+    """
+
     user: str
     type: ConnectEndpointType = ConnectEndpointType.APP
 
 
 class WebsocketEndpoint(BaseModel):
+    """Model for a WebSocket connection.
+
+    Args:
+        uri (str): The URI of the WebSocket connection.
+        contentType (Literal['audio/l16;rate=8000', 'audio/l16;rate=16000']): The internet
+            media type for the audio you are streaming.
+        headers (Optional[dict]): The headers to include with the WebSocket connection.
+    """
+
     uri: str
     contentType: Literal['audio/l16;rate=16000', 'audio/l16;rate=8000'] = Field(
         None, serialization_alias='content-type'
@@ -33,11 +66,26 @@ class WebsocketEndpoint(BaseModel):
 
 
 class SipEndpoint(BaseModel):
+    """Model for a SIP endpoint.
+
+    Args:
+        uri (SipUri): The SIP URI to connect to.
+        headers (Optional[dict]): The headers to include with the SIP connection. To use
+            TLS and/or SRTP, include respectively `transport=tls` or `media=srtp` to the URL with
+            the semicolon `;` as a delimiter.
+    """
+
     uri: SipUri
     headers: Optional[dict] = None
     type: ConnectEndpointType = ConnectEndpointType.SIP
 
 
 class VbcEndpoint(BaseModel):
+    """Model for a VBC endpoint.
+
+    Args:
+        extension (str): The VBC extension to connect the call to.
+    """
+
     extension: str
     type: ConnectEndpointType = ConnectEndpointType.VBC

voice/src/vonage_voice/models/input_types.py

@@ -4,12 +4,44 @@
 
 
 class Dtmf(BaseModel):
+    """Model for DTMF input options used as part of an NCCO.
+
+    Args:
+        timeOut (Optional[int]): The result of the callee's activity is sent to the
+            `eventUrl` webhook endpoint `timeOut` seconds after the last action.
+        submitOnHash (Optional[bool]): Set to `True` so the callee's activity is sent
+            to your webhook endpoint at `eventUrl` after they press `#`. If `#` is not
+                pressed the result is submitted after `timeOut` seconds.
+        maxDigits (Optional[int]): The number of digits the user can press.
+    """
+
     timeOut: Optional[int] = Field(None, ge=0, le=10)
     maxDigits: Optional[int] = Field(None, ge=1, le=20)
     submitOnHash: Optional[bool] = None
 
 
 class Speech(BaseModel):
+    """Model for speech input options used as part of an NCCO.
+
+    Args:
+        uuid (Optional[List[str]]): The UUID of the speech recognition session.
+        endOnSilence (Optional[float]): The length of silence in seconds that indicates
+            the end of the speech. Uses BCP-47 format.
+        language (Optional[str]): The language used for speech recognition. The default
+            is `en-US`.
+        context (Optional[List[str]]):Array of hints (strings) to improve recognition
+            quality if certain words are expected from the user.
+        startTimeout (Optional[int]): Controls how long the system will wait for the user
+            to start speaking.
+        maxDuration (Optional[int]): Controls maximum speech duration (from the moment
+            the user starts speaking).
+        saveAudio (Optional[bool]): If the speech input recording is sent to your webhook
+            endpoint at `eventUrl`.
+        sensitivity (Optional[int]): Audio sensitivity used to differentiate noise from
+            speech. An integer value where `10` represents low sensitivity and `100`
+            maximum sensitivity.
+    """
+
     uuid: Optional[List[str]] = None
     endOnSilence: Optional[float] = Field(None, ge=0.4, le=10.0)
     language: Optional[str] = None