Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.8/site-packages/zmq/sugar/frame.py: 57%

1"""0MQ Frame pure Python methods.""" 

2 

3# Copyright (C) PyZMQ Developers 

4# Distributed under the terms of the Modified BSD License. 

5 

6import zmq 

7from zmq.backend import Frame as FrameBase 

8 

9from .attrsettr import AttributeSetter 

10 

11 

12def _draft(v, feature): 

13 zmq.error._check_version(v, feature) 

14 if not zmq.DRAFT_API: 

15 raise RuntimeError( 

16 "libzmq and pyzmq must be built with draft support for %s" % feature 

17 ) 

18 

19 

20class Frame(FrameBase, AttributeSetter): 

21 """Frame(data=None, track=False, copy=None, copy_threshold=zmq.COPY_THRESHOLD) 

22 

23 A zmq message Frame class for non-copying send/recvs and access to message properties. 

24 

25 A ``zmq.Frame`` wraps an underlying ``zmq_msg_t``. 

26 

27 Message *properties* can be accessed by treating a Frame like a dictionary (``frame["User-Id"]``). 

28 

29 .. versionadded:: 14.4, libzmq 4 

30 

31 Frames created by ``recv(copy=False)`` can be used to access message properties and attributes, 

32 such as the CURVE User-Id. 

33 

34 For example:: 

35 

36 frames = socket.recv_multipart(copy=False) 

37 user_id = frames[0]["User-Id"] 

38 

39 This class is used if you want to do non-copying send and recvs. 

40 When you pass a chunk of bytes to this class, e.g. ``Frame(buf)``, the 

41 ref-count of `buf` is increased by two: once because the Frame saves `buf` as 

42 an instance attribute and another because a ZMQ message is created that 

43 points to the buffer of `buf`. This second ref-count increase makes sure 

44 that `buf` lives until all messages that use it have been sent. 

45 Once 0MQ sends all the messages and it doesn't need the buffer of ``buf``, 

46 0MQ will call ``Py_DECREF(s)``. 

47 

48 Parameters 

49 ---------- 

50 

51 data : object, optional 

52 any object that provides the buffer interface will be used to 

53 construct the 0MQ message data. 

54 track : bool [default: False] 

55 whether a MessageTracker_ should be created to track this object. 

56 Tracking a message has a cost at creation, because it creates a threadsafe 

57 Event object. 

58 copy : bool [default: use copy_threshold] 

59 Whether to create a copy of the data to pass to libzmq 

60 or share the memory with libzmq. 

61 If unspecified, copy_threshold is used. 

62 copy_threshold: int [default: zmq.COPY_THRESHOLD] 

63 If copy is unspecified, messages smaller than this many bytes 

64 will be copied and messages larger than this will be shared with libzmq. 

65 """ 

66 

67 def __getitem__(self, key): 

68 # map Frame['User-Id'] to Frame.get('User-Id') 

69 return self.get(key) 

70 

71 @property 

72 def group(self): 

73 """The RADIO-DISH group of the message. 

74 

75 Requires libzmq >= 4.2 and pyzmq built with draft APIs enabled. 

76 

77 .. versionadded:: 17 

78 """ 

79 _draft((4, 2), "RADIO-DISH") 

80 return self.get('group') 

81 

82 @group.setter 

83 def group(self, group): 

84 _draft((4, 2), "RADIO-DISH") 

85 self.set('group', group) 

86 

87 @property 

88 def routing_id(self): 

89 """The CLIENT-SERVER routing id of the message. 

90 

91 Requires libzmq >= 4.2 and pyzmq built with draft APIs enabled. 

92 

93 .. versionadded:: 17 

94 """ 

95 _draft((4, 2), "CLIENT-SERVER") 

96 return self.get('routing_id') 

97 

98 @routing_id.setter 

99 def routing_id(self, routing_id): 

100 _draft((4, 2), "CLIENT-SERVER") 

101 self.set('routing_id', routing_id) 

102 

103 

104# keep deprecated alias 

105Message = Frame 

106__all__ = ['Frame', 'Message']