Skip to content

Commit 1bc0e2a

Browse files
polybassapolybassa
committed
update docs
1 parent 864fe65 commit 1bc0e2a

File tree

1 file changed

+176
-60
lines changed

1 file changed

+176
-60
lines changed

‎scapy/sendrecv.py‎

Lines changed: 176 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -74,75 +74,50 @@ class debug:
7474
# Send / Receive #
7575
####################
7676

77-
_DOC_SNDRCV_PARAMS_HEAD = """
78-
:param pks: SuperSocket instance to send/receive packets
79-
:type pkt: SuperSocket
80-
"""
81-
8277
_DOC_SNDRCV_PARAMS_BODY = """
8378
:param pkt: Packet or iterable of packets to be sent.
84-
:type pkt: _PacketIterable
8579
:param timeout: How much time to wait after the last packet
8680
has been sent. Defaults to None.
87-
:type timeout: Optional[int]
8881
:param inter: Delay between two packets during sending. Defaults to 0.
89-
:type inter: Optional[int]
90-
9182
:param verbose: Set verbosity level. Defaults to None.
92-
:type verbose: Optional[int]
93-
9483
:param chainCC: If True, KeyboardInterrupts will be forwarded.
9584
Defaults to False.
96-
:type chainCC: Optional[bool]
97-
9885
:param retry: If positive, how many times to resend unanswered packets.
9986
If negative, how many times to retry when no more packets
10087
are answered. Defaults to 0.
101-
:type retry: Optional[int]
102-
10388
:param multi: Whether to accept multiple answers for the same stimulus.
10489
Defaults to False.
105-
:type multi: Optional[bool]
106-
10790
:param rcv_pks: If set, will be used instead of pks to receive packets.
10891
Packets will still be sent through pks.
10992
Defaults to None.
110-
:type rcv_pks: Optional[SuperSocket]
111-
11293
:param prebuild: Pre-build the packets before starting to send them.
11394
Automatically enabled when a generator is passed as the
11495
packet. Defaults to False.
115-
:type prebuild: Optional[bool]
116-
11796
:param _flood: _FloodGenerator object, internally used by `flood()`
11897
methods. Defaults to None.
119-
:type _flood: Optional[_FloodGenerator]
120-
12198
:param threaded: If True, packets will be sent in an individual thread.
12299
Defaults to False.
123-
:type threaded: Optional[bool]
124-
125100
:param session: A flow decoder used to handle the stream of packets.
126101
Defaults to None.
127-
:type session: Optional[_GlobSessionType]
128-
129102
:param chainEX: If True, exceptions during send will be forwarded.
130103
Defaults to False.
131-
:type chainEX: Optional[bool]
132104
"""
133105

134106
_DOC_SNDRCV_PARAMS_TAIL = """
135107
:return: A tuple, consisting of two packet lists, one with
136-
answered packets, the other with unanswered packets
137-
:rtype: Tuple[SndRcvList, PacketList]
108+
answered packets, the other with unanswered packets
138109
"""
139110

140111
_DOC_SNDRCV1_PARAMS_TAIL = """
141112
:return: A received Packet answering the sent packet, or None
142-
:rtype: Optional[Packet]
143113
"""
144114

145115

116+
# Append doc in SuperSocket
117+
SuperSocket.sr.__doc__ += _DOC_SNDRCV_PARAMS_BODY + _DOC_SNDRCV_PARAMS_TAIL # type: ignore
118+
SuperSocket.sr1.__doc__ += _DOC_SNDRCV_PARAMS_BODY + _DOC_SNDRCV1_PARAMS_TAIL # type: ignore
119+
120+
146121
_GlobSessionType = Union[Type[DefaultSession], DefaultSession]
147122

148123

@@ -159,6 +134,34 @@ class SndRcvHandler(object):
159134
when sending a big amount of packets. Disabled by default
160135
- DEVS: store the outgoing timestamp right BEFORE sending the packet
161136
to avoid races that could result in negative latency. We aren't Stadia
137+
138+
:param pks: SuperSocket instance to send/receive packets
139+
:param pkt: Packet or iterable of packets to be sent.
140+
:param timeout: How much time to wait after the last packet
141+
has been sent. Defaults to None.
142+
:param inter: Delay between two packets during sending. Defaults to 0.
143+
:param verbose: Set verbosity level. Defaults to None.
144+
:param chainCC: If True, KeyboardInterrupts will be forwarded.
145+
Defaults to False.
146+
:param retry: If positive, how many times to resend unanswered packets.
147+
If negative, how many times to retry when no more packets
148+
are answered. Defaults to 0.
149+
:param multi: Whether to accept multiple answers for the same stimulus.
150+
Defaults to False.
151+
:param rcv_pks: If set, will be used instead of pks to receive packets.
152+
Packets will still be sent through pks.
153+
Defaults to None.
154+
:param prebuild: Pre-build the packets before starting to send them.
155+
Automatically enabled when a generator is passed as the
156+
packet. Defaults to False.
157+
:param _flood: _FloodGenerator object, internally used by `flood()`
158+
methods. Defaults to None.
159+
:param threaded: If True, packets will be sent in an individual thread.
160+
Defaults to False.
161+
:param session: A flow decoder used to handle the stream of packets.
162+
Defaults to None.
163+
:param chainEX: If True, exceptions during send will be forwarded.
164+
Defaults to False.
162165
"""
163166
def __init__(self,
164167
pks, # type: SuperSocket
@@ -692,7 +695,7 @@ def _interface_selection(iface, # type: Optional[_GlobInterfaceType]
692695

693696

694697
@conf.commands.register
695-
def sr(x, # type: _PacketIterable
698+
def sr(pkt, # type: _PacketIterable
696699
promisc=None, # type: Optional[bool]
697700
filter=None, # type: Optional[str]
698701
iface=None, # type: Optional[_GlobInterfaceType]
@@ -703,13 +706,46 @@ def sr(x, # type: _PacketIterable
703706
# type: (...) -> Tuple[SndRcvList, PacketList]
704707
"""
705708
Send and receive packets at layer 3
709+
710+
:param pkt: Packet or iterable of packets to be sent.
711+
:param promisc: Sets the socket in promisc mode, if True.
712+
:param iface: Use a specific network interface, if provided.
713+
:param filter: Filter string applied to the underlying socket.
714+
:param nofilter:
715+
:param timeout: How much time to wait after the last packet
716+
has been sent. Defaults to None.
717+
:param inter: Delay between two packets during sending. Defaults to 0.
718+
:param verbose: Set verbosity level. Defaults to None.
719+
:param chainCC: If True, KeyboardInterrupts will be forwarded.
720+
Defaults to False.
721+
:param retry: If positive, how many times to resend unanswered packets.
722+
If negative, how many times to retry when no more packets
723+
are answered. Defaults to 0.
724+
:param multi: Whether to accept multiple answers for the same stimulus.
725+
Defaults to False.
726+
:param rcv_pks: If set, will be used instead of pks to receive packets.
727+
Packets will still be sent through pks.
728+
Defaults to None.
729+
:param prebuild: Pre-build the packets before starting to send them.
730+
Automatically enabled when a generator is passed as the
731+
packet. Defaults to False.
732+
:param _flood: _FloodGenerator object, internally used by `flood()`
733+
methods. Defaults to None.
734+
:param threaded: If True, packets will be sent in an individual thread.
735+
Defaults to False.
736+
:param session: A flow decoder used to handle the stream of packets.
737+
Defaults to None.
738+
:param chainEX: If True, exceptions during send will be forwarded.
739+
Defaults to False.
740+
:return: A tuple, consisting of two packet lists, one with
741+
answered packets, the other with unanswered packets
706742
"""
707-
iface, ipv6 = _interface_selection(iface, x)
743+
iface, ipv6 = _interface_selection(iface, pkt)
708744
s = iface.l3socket(ipv6)(
709745
promisc=promisc, filter=filter,
710746
iface=iface, nofilter=nofilter,
711747
)
712-
result = sndrcv(s, x, *args, **kargs)
748+
result = sndrcv(s, pkt, *args, **kargs)
713749
s.close()
714750
return result
715751

@@ -719,6 +755,38 @@ def sr1(*args, **kargs):
719755
# type: (*Any, **Any) -> Optional[Packet]
720756
"""
721757
Send packets at layer 3 and return only the first answer
758+
759+
:param pkt: Packet or iterable of packets to be sent.
760+
:param promisc: Sets the socket in promisc mode, if True.
761+
:param iface: Use a specific network interface, if provided.
762+
:param filter: Filter string applied to the underlying socket.
763+
:param nofilter:
764+
:param timeout: How much time to wait after the last packet
765+
has been sent. Defaults to None.
766+
:param inter: Delay between two packets during sending. Defaults to 0.
767+
:param verbose: Set verbosity level. Defaults to None.
768+
:param chainCC: If True, KeyboardInterrupts will be forwarded.
769+
Defaults to False.
770+
:param retry: If positive, how many times to resend unanswered packets.
771+
If negative, how many times to retry when no more packets
772+
are answered. Defaults to 0.
773+
:param multi: Whether to accept multiple answers for the same stimulus.
774+
Defaults to False.
775+
:param rcv_pks: If set, will be used instead of pks to receive packets.
776+
Packets will still be sent through pks.
777+
Defaults to None.
778+
:param prebuild: Pre-build the packets before starting to send them.
779+
Automatically enabled when a generator is passed as the
780+
packet. Defaults to False.
781+
:param _flood: _FloodGenerator object, internally used by `flood()`
782+
methods. Defaults to None.
783+
:param threaded: If True, packets will be sent in an individual thread.
784+
Defaults to False.
785+
:param session: A flow decoder used to handle the stream of packets.
786+
Defaults to None.
787+
:param chainEX: If True, exceptions during send will be forwarded.
788+
Defaults to False.
789+
:return: A received Packet answering the sent packet, or None
722790
"""
723791
ans, _ = sr(*args, **kargs)
724792
if ans:
@@ -727,7 +795,7 @@ def sr1(*args, **kargs):
727795

728796

729797
@conf.commands.register
730-
def srp(x, # type: _PacketIterable
798+
def srp(pkt, # type: _PacketIterable
731799
promisc=None, # type: Optional[bool]
732800
iface=None, # type: Optional[_GlobInterfaceType]
733801
iface_hint=None, # type: Optional[str]
@@ -740,13 +808,50 @@ def srp(x, # type: _PacketIterable
740808
# type: (...) -> Tuple[SndRcvList, PacketList]
741809
"""
742810
Send and receive packets at layer 2
811+
812+
:param pkt: Packet or iterable of packets to be sent.
813+
:param promisc: Sets the socket in promisc mode, if True.
814+
:param iface: Use a specific network interface, if provided.
815+
:param iface_hint: The interface used to connect to the host based on
816+
the route information, if provided.
817+
:param filter: Filter string applied to the underlying socket.
818+
:param nofilter:
819+
:param type: Type of the underlying socket
820+
:param timeout: How much time to wait after the last packet
821+
has been sent. Defaults to None.
822+
:param inter: Delay between two packets during sending. Defaults to 0.
823+
:param verbose: Set verbosity level. Defaults to None.
824+
:param chainCC: If True, KeyboardInterrupts will be forwarded.
825+
Defaults to False.
826+
:param retry: If positive, how many times to resend unanswered packets.
827+
If negative, how many times to retry when no more packets
828+
are answered. Defaults to 0.
829+
:param multi: Whether to accept multiple answers for the same stimulus.
830+
Defaults to False.
831+
:param rcv_pks: If set, will be used instead of pks to receive packets.
832+
Packets will still be sent through pks.
833+
Defaults to None.
834+
:param prebuild: Pre-build the packets before starting to send them.
835+
Automatically enabled when a generator is passed as the
836+
packet. Defaults to False.
837+
:param _flood: _FloodGenerator object, internally used by `flood()`
838+
methods. Defaults to None.
839+
:param threaded: If True, packets will be sent in an individual thread.
840+
Defaults to False.
841+
:param session: A flow decoder used to handle the stream of packets.
842+
Defaults to None.
843+
:param chainEX: If True, exceptions during send will be forwarded.
844+
Defaults to False.
845+
846+
:return: A tuple, consisting of two packet lists, one with
847+
answered packets, the other with unanswered packets
743848
"""
744849
if iface is None and iface_hint is not None:
745850
iface = conf.route.route(iface_hint)[0]
746851
iface = resolve_iface(iface or conf.iface)
747852
s = iface.l2socket()(promisc=promisc, iface=iface,
748853
filter=filter, nofilter=nofilter, type=type)
749-
result = sndrcv(s, x, *args, **kargs)
854+
result = sndrcv(s, pkt, *args, **kargs)
750855
s.close()
751856
return result
752857

@@ -756,39 +861,50 @@ def srp1(*args, **kargs):
756861
# type: (*Any, **Any) -> Optional[Packet]
757862
"""
758863
Send and receive packets at layer 2 and return only the first answer
864+
865+
:param pkt: Packet or iterable of packets to be sent.
866+
:param promisc: Sets the socket in promisc mode, if True.
867+
:param iface: Use a specific network interface, if provided.
868+
:param iface_hint: The interface used to connect to the host based on
869+
the route information, if provided.
870+
:param filter: Filter string applied to the underlying socket.
871+
:param nofilter:
872+
:param type: Type of the underlying socket
873+
:param timeout: How much time to wait after the last packet
874+
has been sent. Defaults to None.
875+
:param inter: Delay between two packets during sending. Defaults to 0.
876+
:param verbose: Set verbosity level. Defaults to None.
877+
:param chainCC: If True, KeyboardInterrupts will be forwarded.
878+
Defaults to False.
879+
:param retry: If positive, how many times to resend unanswered packets.
880+
If negative, how many times to retry when no more packets
881+
are answered. Defaults to 0.
882+
:param multi: Whether to accept multiple answers for the same stimulus.
883+
Defaults to False.
884+
:param rcv_pks: If set, will be used instead of pks to receive packets.
885+
Packets will still be sent through pks.
886+
Defaults to None.
887+
:param prebuild: Pre-build the packets before starting to send them.
888+
Automatically enabled when a generator is passed as the
889+
packet. Defaults to False.
890+
:param _flood: _FloodGenerator object, internally used by `flood()`
891+
methods. Defaults to None.
892+
:param threaded: If True, packets will be sent in an individual thread.
893+
Defaults to False.
894+
:param session: A flow decoder used to handle the stream of packets.
895+
Defaults to None.
896+
:param chainEX: If True, exceptions during send will be forwarded.
897+
Defaults to False.
898+
:return: A received Packet answering the sent packet, or None
759899
"""
760900
ans, _ = srp(*args, **kargs)
761901
if len(ans) > 0:
762902
return cast(Packet, ans[0][1])
763903
return None
764904

765905

766-
# Append doc
767-
for sr_func in [srp, sr]:
768-
if sr_func.__doc__ is not None:
769-
sr_func.__doc__ += (_DOC_SNDRCV_PARAMS_HEAD +
770-
_DOC_SNDRCV_PARAMS_BODY +
771-
_DOC_SNDRCV_PARAMS_TAIL)
772-
773-
for sr_func in [srp1, sr1]:
774-
if sr_func.__doc__ is not None:
775-
sr_func.__doc__ += (_DOC_SNDRCV_PARAMS_HEAD +
776-
_DOC_SNDRCV_PARAMS_BODY +
777-
_DOC_SNDRCV1_PARAMS_TAIL)
778-
779-
# Append doc in SuperSocket
780-
for sr_func in [SuperSocket.sr]:
781-
if sr_func.__doc__ is not None:
782-
sr_func.__doc__ += _DOC_SNDRCV_PARAMS_BODY + _DOC_SNDRCV_PARAMS_TAIL
783-
784-
for sr_func in [SuperSocket.sr1]:
785-
if sr_func.__doc__ is not None:
786-
sr_func.__doc__ += _DOC_SNDRCV_PARAMS_BODY + _DOC_SNDRCV1_PARAMS_TAIL
787-
788-
789906
# SEND/RECV LOOP METHODS
790907

791-
792908
def __sr_loop(srfunc, # type: Callable[..., Tuple[SndRcvList, PacketList]]
793909
pkts, # type: _PacketIterable
794910
prn=lambda x: x[1].summary(), # type: Optional[Callable[[QueryAnswer], Any]] # noqa: E501

0 commit comments

Comments
 (0)