2025-12-25 upload

venv/Lib/site-packages/pydivert-2.1.0.dist-info/DESCRIPTION.rst

@@ -0,0 +1,175 @@
+pydivert
+^^^^^^^^
+
+|appveyor| |codecov| |latest_release| |python_versions|
+
+Python bindings for WinDivert_, a Windows driver that allows user-mode applications to
+capture/modify/drop network packets sent to/from the Windows network stack.
+
+Requirements
+------------
+
+- Python 2.7 or Python 3.4+ (32 or 64 bit)
+- Windows Vista/7/8/10 or Windows Server 2008 (32 or 64 bit)
+- Administrator Privileges
+
+Installation
+------------
+
+You can install PyDivert by running
+
+.. code-block:: text
+
+    $ pip install pydivert
+
+Starting with PyDivert 1.0.2, WinDivert_ is bundled with
+PyDivert and does not need to be installed separately.
+
+
+**WinDivert Version Compatibility**
+
+=================================  ===============
+PyDivert                           WinDivert
+---------------------------------  ---------------
+0.0.7                              1.0.x or 1.1.x
+1.0.x (API-compatible with 0.0.7)  1.1.8 (bundled)
+2.0.x                              1.1.8 (bundled)
+2.1.x                              1.3 (bundled)
+=================================  ===============
+
+Getting Started
+---------------
+
+PyDivert consists of two main classes: ``pydivert.WinDivert`` and ``pydivert.Packet``.
+First, you usually want to create a ``WinDivert`` object to start capturing network traffic and then
+call ``.recv()`` to receive the first ``Packet`` that was captured. By receiving packets, they are taken
+out of the Windows network stack and will not be sent out unless you take action.
+You can re-inject packets by calling ``.send(packet)``.
+The following example opens a WinDivert handle, receives a single packet, prints it, re-injects it,
+and then exits:
+
+.. code-block:: python
+
+    import pydivert
+
+    # Capture only TCP packets to port 80, i.e. HTTP requests.
+    w = pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0")
+
+    w.open()  # packets will be captured from now on
+
+    packet = w.recv()  # read a single packet
+    print(packet)
+    w.send(packet)  # re-inject the packet into the network stack
+
+    w.close()  # stop capturing packets
+
+Packets that are not matched by the ``"tcp.DstPort == 80 and tcp.PayloadLength > 0"`` filter will not be handled by WinDivert
+and continue as usual. The syntax for the filter language is described in the `WinDivert documentation <https://reqrypt.org/windivert-doc.html#filter_language>`_.
+
+Python Idioms
+-------------
+
+``pydivert.WinDivert`` instances can be used as *context managers* for capturing traffic and as (infinite) *iterators* over
+packets. The following code is equivalent to the example above:
+
+.. code-block:: python
+
+    import pydivert
+
+    with pydivert.WinDivert("tcp.DstPort == 80 and tcp.PayloadLength > 0") as w:
+        for packet in w:
+            print(packet)
+            w.send(packet)
+            break
+
+Packet Modification
+-------------------
+
+``pydivert.Packet`` provides a variety of properties that can be used to access and modify the
+packet's headers or payload. For example, you can browse the web on port 1234 with PyDivert:
+
+.. code-block:: python
+
+    import pydivert
+
+    with pydivert.WinDivert("tcp.DstPort == 1234 or tcp.SrcPort == 80") as w:
+        for packet in w:
+            if packet.dst_port == 1234:
+                print(">") # packet to the server
+                packet.dst_port = 80
+            if packet.src_port == 80:
+                print("<") # reply from the server
+                packet.src_port = 1234
+            w.send(packet)
+
+Try opening http://example.com:1234/ in your browser!
+
+WinDivert supports access and modification of a variety of TCP/UDP/ICMP attributes out of the box.
+
+.. code-block:: python
+
+    >>> print(packet)
+    Packet({'direction': <Direction.OUTBOUND: 0>,
+     'dst_addr': '93.184.216.34',
+     'dst_port': 443,
+     'icmpv4': None,
+     'icmpv6': None,
+     'interface': (23, 0),
+     'ipv4': {'src_addr': '192.168.86.169',
+              'dst_addr': '93.184.216.34',
+              'packet_len': 81},
+     'ipv6': None,
+     'is_inbound': False,
+     'is_loopback': False,
+     'is_outbound': True,
+     'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...',
+     'raw': <memory at 0x028924E0>,
+     'src_addr': '192.168.86.169',
+     'src_port': 52387,
+     'tcp': {'src_port': 52387,
+             'dst_port': 443,
+             'syn': False,
+             'ack': True,
+             'fin': False,
+             'rst': False,
+             'psh': True,
+             'urg': False,
+             'header_len': 20,
+             'payload': '\x17\x03\x03\x00$\x00\x00\x00\x00\x00\x00\x02\x05\x19q\xbd\xcfD\x8a\xe3...'},
+     'udp': None})
+
+Uninstalling PyDivert
+---------------------
+
+You can uninstall PyDivert by running
+
+.. code-block:: text
+
+    $ pip uninstall pydivert
+
+If the WinDivert driver is still running at that time, it will remove itself on the next reboot.
+
+API Reference Documentation
+---------------------------
+
+The API Reference Documentation for PyDivert can be found `here <https://ffalcinelli.github.io/pydivert/>`_.
+
+.. |appveyor| image:: https://img.shields.io/appveyor/ci/ffalcinelli/pydivert/master.svg
+    :target: https://ci.appveyor.com/project/ffalcinelli/pydivert
+    :alt: Appveyor Build Status
+
+.. |codecov| image:: https://img.shields.io/codecov/c/github/ffalcinelli/pydivert/master.svg
+    :target: https://codecov.io/gh/ffalcinelli/pydivert
+    :alt: Coverage Status
+
+.. |latest_release| image:: https://img.shields.io/pypi/v/pydivert.svg
+    :target: https://pypi.python.org/pypi/pydivert
+    :alt: Latest Version
+
+.. |python_versions| image:: https://img.shields.io/pypi/pyversions/pydivert.svg
+    :target: https://pypi.python.org/pypi/pydivert
+    :alt: Supported Python versions
+
+.. _WinDivert: https://reqrypt.org/windivert.html
+
+