async def receive_media(self) -> object:
"""Receive a deserialized object from the client.
The incoming payload type determines the media handler that will be used
to deserialize the object (see also: :ref:`ws_media_handlers`).
"""
self._require_accepted()
event = await self._receive()
# NOTE(kgriffs): Most likely case is going to be JSON via text
# payload, so try that first.
text = event.get('text')
if text is not None:
return self._mh_text_deserialize(text)
# PERF(kgriffs): At this point there better be a 'bytes' key, so
# use EAFP this time.
try:
data = event['bytes']
except KeyError:
data = None
# NOTE(kgriffs): Even if the key is present, it may be None
if data is None:
raise errors.PayloadTypeError(
'Message did not contain either a TEXT (0x01) or BINARY (0x02) payload'
)
return self._mh_bin_deserialize(data)
async def receive_data(self) -> bytes:
"""Receive a message from the app with a binary data payload.
Awaiting this coroutine will block until a message is available or
the WebSocket is disconnected.
"""
event = await self._receive()
# PERF(kgriffs): When we normally expect the key to be
# present, EAFP is faster than get()
try:
data = event['bytes']
except KeyError:
data = None
# NOTE(kgriffs): Even if the key is present, it may be None
if data is None:
raise falcon_errors.PayloadTypeError('Expected BINARY payload but got TEXT instead')
return data
async def receive_text(self) -> str:
"""Receive a message from the app with a Unicode string payload.
Awaiting this coroutine will block until a message is available or
the WebSocket is disconnected.
"""
event = await self._receive()
# PERF(kgriffs): When we normally expect the key to be
# present, this pattern is faster than get()
try:
text = event['text']
except KeyError:
text = None
# NOTE(kgriffs): Even if the key is present, it may be None
if text is None:
raise falcon_errors.PayloadTypeError('Expected TEXT payload but got BINARY instead')
return text