pktbin 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,219 @@
1
+ # Byte-compiled / optimized / DLL files
2
+ __pycache__/
3
+ *.py[codz]
4
+ *$py.class
5
+
6
+ # C extensions
7
+ *.so
8
+
9
+ # Distribution / packaging
10
+ .Python
11
+ build/
12
+ develop-eggs/
13
+ dist/
14
+ downloads/
15
+ eggs/
16
+ .eggs/
17
+ lib/
18
+ lib64/
19
+ parts/
20
+ sdist/
21
+ var/
22
+ wheels/
23
+ share/python-wheels/
24
+ *.egg-info/
25
+ .installed.cfg
26
+ *.egg
27
+ MANIFEST
28
+
29
+ # PyInstaller
30
+ # Usually these files are written by a python script from a template
31
+ # before PyInstaller builds the exe, so as to inject date/other infos into it.
32
+ *.manifest
33
+ *.spec
34
+
35
+ # Installer logs
36
+ pip-log.txt
37
+ pip-delete-this-directory.txt
38
+
39
+ # Unit test / coverage reports
40
+ htmlcov/
41
+ .tox/
42
+ .nox/
43
+ .coverage
44
+ .coverage.*
45
+ .cache
46
+ nosetests.xml
47
+ coverage.xml
48
+ *.cover
49
+ *.py.cover
50
+ .hypothesis/
51
+ .pytest_cache/
52
+ cover/
53
+
54
+ # Translations
55
+ *.mo
56
+ *.pot
57
+
58
+ # Django stuff:
59
+ *.log
60
+ local_settings.py
61
+ db.sqlite3
62
+ db.sqlite3-journal
63
+
64
+ # Flask stuff:
65
+ instance/
66
+ .webassets-cache
67
+
68
+ # Scrapy stuff:
69
+ .scrapy
70
+
71
+ # Sphinx documentation
72
+ docs/_build/
73
+
74
+ # PyBuilder
75
+ .pybuilder/
76
+ target/
77
+
78
+ # Jupyter Notebook
79
+ .ipynb_checkpoints
80
+
81
+ # IPython
82
+ profile_default/
83
+ ipython_config.py
84
+
85
+ # pyenv
86
+ # For a library or package, you might want to ignore these files since the code is
87
+ # intended to run in multiple environments; otherwise, check them in:
88
+ # .python-version
89
+
90
+ # pipenv
91
+ # According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
92
+ # However, in case of collaboration, if having platform-specific dependencies or dependencies
93
+ # having no cross-platform support, pipenv may install dependencies that don't work, or not
94
+ # install all needed dependencies.
95
+ # Pipfile.lock
96
+
97
+ # UV
98
+ # Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
99
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
100
+ # commonly ignored for libraries.
101
+ # uv.lock
102
+
103
+ # poetry
104
+ # Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
105
+ # This is especially recommended for binary packages to ensure reproducibility, and is more
106
+ # commonly ignored for libraries.
107
+ # https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
108
+ # poetry.lock
109
+ # poetry.toml
110
+
111
+ # pdm
112
+ # Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
113
+ # pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
114
+ # https://pdm-project.org/en/latest/usage/project/#working-with-version-control
115
+ # pdm.lock
116
+ # pdm.toml
117
+ .pdm-python
118
+ .pdm-build/
119
+
120
+ # pixi
121
+ # Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
122
+ # pixi.lock
123
+ # Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
124
+ # in the .venv directory. It is recommended not to include this directory in version control.
125
+ .pixi
126
+
127
+ # PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
128
+ __pypackages__/
129
+
130
+ # Celery stuff
131
+ celerybeat-schedule
132
+ celerybeat.pid
133
+
134
+ # Redis
135
+ *.rdb
136
+ *.aof
137
+ *.pid
138
+
139
+ # RabbitMQ
140
+ mnesia/
141
+ rabbitmq/
142
+ rabbitmq-data/
143
+
144
+ # ActiveMQ
145
+ activemq-data/
146
+
147
+ # SageMath parsed files
148
+ *.sage.py
149
+
150
+ # Environments
151
+ .env
152
+ .envrc
153
+ .venv
154
+ env/
155
+ venv/
156
+ ENV/
157
+ env.bak/
158
+ venv.bak/
159
+
160
+ # Spyder project settings
161
+ .spyderproject
162
+ .spyproject
163
+
164
+ # Rope project settings
165
+ .ropeproject
166
+
167
+ # mkdocs documentation
168
+ /site
169
+
170
+ # mypy
171
+ .mypy_cache/
172
+ .dmypy.json
173
+ dmypy.json
174
+
175
+ # Pyre type checker
176
+ .pyre/
177
+
178
+ # pytype static type analyzer
179
+ .pytype/
180
+
181
+ # Cython debug symbols
182
+ cython_debug/
183
+
184
+ # PyCharm
185
+ # JetBrains specific template is maintained in a separate JetBrains.gitignore that can
186
+ # be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
187
+ # and can be added to the global gitignore or merged into this file. For a more nuclear
188
+ # option (not recommended) you can uncomment the following to ignore the entire idea folder.
189
+ # .idea/
190
+
191
+ # Abstra
192
+ # Abstra is an AI-powered process automation framework.
193
+ # Ignore directories containing user credentials, local state, and settings.
194
+ # Learn more at https://abstra.io/docs
195
+ .abstra/
196
+
197
+ # Visual Studio Code
198
+ # Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
199
+ # that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
200
+ # and can be added to the global gitignore or merged into this file. However, if you prefer,
201
+ # you could uncomment the following to ignore the entire vscode folder
202
+ # .vscode/
203
+
204
+ # Ruff stuff:
205
+ .ruff_cache/
206
+
207
+ # PyPI configuration file
208
+ .pypirc
209
+
210
+ # Marimo
211
+ marimo/_static/
212
+ marimo/_lsp/
213
+ __marimo__/
214
+
215
+ # Streamlit
216
+ .streamlit/secrets.toml
217
+
218
+ # Version
219
+ pktbin/_version.py
pktbin-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Pktbin
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pktbin-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,267 @@
1
+ Metadata-Version: 2.5
2
+ Name: pktbin
3
+ Version: 0.1.0
4
+ Summary: Python client for pktbin: capture the traffic your code sends, and query its packets and requests.
5
+ Project-URL: Homepage, https://pktbin.com
6
+ Project-URL: Documentation, https://pktbin.com/docs/
7
+ Author: Pktbin
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: network,packet capture,pcap,testing,wireshark
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Programming Language :: Python :: 3.14
20
+ Classifier: Topic :: Internet
21
+ Classifier: Topic :: Software Development :: Testing
22
+ Classifier: Topic :: System :: Networking :: Monitoring
23
+ Classifier: Typing :: Typed
24
+ Requires-Python: >=3.11
25
+ Requires-Dist: anyio>=4.12.1
26
+ Requires-Dist: httpx>=0.28
27
+ Requires-Dist: pydantic>=2.12
28
+ Requires-Dist: typing-extensions>=4.4
29
+ Description-Content-Type: text/markdown
30
+
31
+ # pktbin
32
+
33
+ Test what your code sends over the network.
34
+
35
+ Point an HTTP client, SDK or webhook at a capture URL, then check from Python what it sent:
36
+ each request, its headers and body, its TLS connection and its packets. Set what pktbin answers,
37
+ such as errors and delays, to test how your code handles them.
38
+
39
+ This is the official Python client for [pktbin](https://pktbin.com). Its pytest plugin,
40
+ [pytest-pktbin](https://pypi.org/project/pytest-pktbin/), gives each test a capture of its own.
41
+
42
+ Python 3.11 or later.
43
+
44
+ ```bash
45
+ pip install pktbin
46
+ ```
47
+
48
+ Documentation: https://pktbin.com/docs/
49
+
50
+ ## Example
51
+
52
+ ```python
53
+ import httpx
54
+ import pktbin
55
+
56
+ with pktbin.capture() as capture:
57
+ httpx.post(capture.url("/hook"), json={"event": "paid"})
58
+
59
+ details = capture.wait_for_request_details(method="POST", path="/hook")
60
+ print(details.status_code, details.request["content-type"])
61
+ print(details.request.body.text)
62
+ print(details.connection.tls.alpn)
63
+ print(capture.link(details))
64
+ ```
65
+
66
+ `pktbin.capture()` creates a capture and a client for it. When the `with` block ends, the
67
+ client closes. The capture stays until it expires, so you can open its link afterwards. Pass
68
+ `delete=True` to delete it when the block ends. `pktbin.async_capture()` does the same with
69
+ async methods.
70
+
71
+ ## Investigate a request
72
+
73
+ Each request has three layers. The capture's page on pktbin.com shows the same layers, and
74
+ under them the request's packets.
75
+
76
+ 1. **Request**: what was asked, and the outcome. `wait_for_request()`, `requests()` and
77
+ `follow_requests()` match by model, `method`, `target` or `path`, for example
78
+ `wait_for_request(HttpRequest, method="POST", path="/hook")`. A wait returns a request
79
+ with its answer. Some requests never get one in the capture, for example a CONNECT
80
+ through a proxy, or an SMTP session cut short. Pass `answered=False` to wait for those.
81
+ 2. **Exchange**: what each side sent. `request_details(request)`, or
82
+ `wait_for_request_details(...)` in one step, returns `request`, `response` and
83
+ `messages`. `details.request["user-agent"]` reads a field, and `details.request.body.text`
84
+ the body.
85
+ 3. **Connection**: `details.connection` has the TLS version, the ALPN protocols, the
86
+ fingerprints, the round trips and how the connection ended. `details.handshakes` has the
87
+ TCP and TLS handshakes.
88
+
89
+ `link(request)` returns the request's page on pktbin.com, without the owner token.
90
+
91
+ ## Control the response
92
+
93
+ By default, pktbin sends:
94
+
95
+ - An empty 200 for HTTP.
96
+ - An echo for WebSocket messages, and for WebTransport streams and datagrams.
97
+ - Three timestamps, one second apart, for an event stream.
98
+ - `UNIMPLEMENTED` for gRPC calls.
99
+
100
+ To change the response, give a `CaptureResponse`:
101
+
102
+ ```python
103
+ from pktbin import CaptureResponse, Route
104
+
105
+ capture.set_response(
106
+ CaptureResponse(
107
+ status=404,
108
+ routes=[
109
+ Route(
110
+ method="POST",
111
+ path="/login",
112
+ times=2,
113
+ response=CaptureResponse(status=503),
114
+ ),
115
+ Route(method="POST", path="/login", response=CaptureResponse(status=200)),
116
+ ],
117
+ )
118
+ )
119
+ ```
120
+
121
+ In this example, the first two POST requests to `/login` get 503. Later POST requests to
122
+ `/login` get 200. All other requests get 404.
123
+
124
+ - The first route that matches the method and the path sends its response.
125
+ - A path that ends with `*` matches by prefix.
126
+ - A route with `times` answers only that many requests. Later requests go to the routes after
127
+ it. The count starts again when the response changes.
128
+ - `set_response(None)` sets the defaults again.
129
+
130
+ `CaptureResponse` has these fields:
131
+
132
+ | Field | Meaning |
133
+ |---|---|
134
+ | `status` | 200 to 599. A status that is not 2xx also refuses WebSocket, event streams and WebTransport. |
135
+ | `headers` | A list of pairs, or a dict. |
136
+ | `body` | `str` or `bytes`. |
137
+ | `echo_body` | `True` sends the request body back. |
138
+ | `delay_ms` | A delay before the response, 10 000 at most. |
139
+ | `websocket` | A `WebSocketResponse`: messages to send, echo, close. |
140
+ | `sse` | An `SseResponse`: the events of an event stream. |
141
+ | `webtransport` | A `WebTransportResponse`: streams and datagrams to send, echo. |
142
+ | `routes` | A list of `Route`. |
143
+ | `tls` | A `TlsResponse`: the ALPN protocols that HTTPS accepts. |
144
+
145
+ An unknown field raises a `ValidationError`. For example, `CaptureResponse(stauts=500)` fails.
146
+
147
+ ### gRPC
148
+
149
+ A gRPC call gets the same response as an HTTP request:
150
+
151
+ - `body` is the reply message. A real client needs encoded protobuf bytes.
152
+ - The `grpc-status` and `grpc-message` headers go in the trailers.
153
+ - `echo_body` sends the request messages back.
154
+
155
+ ```python
156
+ CaptureResponse(headers={"grpc-status": "14", "grpc-message": "try later"})
157
+ ```
158
+
159
+ ### TLS
160
+
161
+ ```python
162
+ from pktbin import TlsResponse
163
+
164
+ client.create_capture(response=CaptureResponse(tls=TlsResponse(alpn=["http/1.1"])))
165
+ ```
166
+
167
+ pktbin selects the first protocol that the client offers. If the client offers none of them,
168
+ the handshake fails. `alpn=[]` accepts no protocol.
169
+
170
+ ## Filters
171
+
172
+ A filter finds requests by any field of their packets: a request matches when one of its
173
+ packets matches.
174
+
175
+ ```python
176
+ from pktbin import F
177
+
178
+ resets = capture.requests(filter=F.tcp_flags_reset)
179
+ ```
180
+
181
+ - `filter` takes a Wireshark display filter, as text or built from `F`, for example
182
+ `F.tcp_dstport.eq(443)`.
183
+ - Combine filters with `&`, `|` and `~`, also with text: `F.http & "tcp.port == 443"`.
184
+ - To wait for traffic, wait for its request: `wait_for_request(filter=F.tcp_flags_reset)`.
185
+
186
+ ## Clients
187
+
188
+ Use a client to create many captures, or to open an existing capture:
189
+
190
+ ```python
191
+ with pktbin.Client() as client:
192
+ capture = client.create_capture()
193
+ other = client.get_capture("<capture ID>", token="<owner token>")
194
+ ```
195
+
196
+ Without `with`, call `client.close()`. `AsyncClient` has the same methods as coroutines, and
197
+ `aclose()` in place of `close()`.
198
+
199
+ `Client()` takes these keyword arguments:
200
+
201
+ - `timeout`: the HTTP timeout in seconds. The default is 30.
202
+ - Other keyword arguments go to `httpx.AsyncClient`, for example `proxy` or `headers`.
203
+
204
+ ## Captures
205
+
206
+ `create_capture()` takes these arguments:
207
+
208
+ - `ttl`: a `datetime.timedelta`. The default is one hour. The maximum is one day.
209
+ - `region`: where pktbin creates the capture, for example `"de"`. Without it, the default
210
+ region. If that one does not answer, the client tries the next one.
211
+ - `response`: what pktbin sends back. See [Control the response](#control-the-response).
212
+ - `name`: a name that all readers of the capture see.
213
+
214
+ A capture has these URLs, as `str` values:
215
+
216
+ - `capture.urls.ingest`: send traffic here. It ends with `/`. `capture.url("/hook")` gives
217
+ the URL of a path on it.
218
+ - `capture.urls.view`: the capture's page.
219
+ - `capture.owner_url`: the capture's page with the owner token. Do not share it.
220
+
221
+ Other operations:
222
+
223
+ ```python
224
+ capture.set_name("retry test")
225
+ capture.extend(datetime.timedelta(hours=12))
226
+ capture.save("capture.pcapng")
227
+ capture.delete()
228
+ ```
229
+
230
+ ## Access
231
+
232
+ A new capture is private. Only its owner token can read it. `create_capture()` returns the
233
+ token in `capture.token`, and no other call returns it. The client sends the token for each
234
+ capture that it created or opened with the token.
235
+
236
+ To let anyone with the capture ID read the capture:
237
+
238
+ ```python
239
+ capture.set_visibility("link")
240
+ ```
241
+
242
+ Changes and deletes need the owner token. Without it, the client raises
243
+ `PktbinPermissionError`.
244
+
245
+ ## Errors
246
+
247
+ All errors are subclasses of `PktbinError`:
248
+
249
+ | Error | Cause |
250
+ |---|---|
251
+ | `PktbinBadRequestError` | The API refused the request, for example an invalid filter. |
252
+ | `PktbinPermissionError` | The request needs the owner token. |
253
+ | `PktbinNotFoundError` | The capture does not exist, or it expired. |
254
+ | `PktbinNoMatchError` | No request matched in time. |
255
+ | `PktbinTimeoutError` | The client did not connect in time. `PktbinNoMatchError` is a subclass. |
256
+ | `PktbinConnectionError` | The client cannot connect to the API. |
257
+
258
+ The client sends a request again after a 429, 502, 503 or 504 status, up to 5 times. It sends a
259
+ new capture again only after a 429 or 503. For a 429, it issues `PktbinRateLimitWarning`.
260
+
261
+ ## pytest
262
+
263
+ [pytest-pktbin](https://pypi.org/project/pytest-pktbin/) gives each test a new capture.
264
+
265
+ ## License
266
+
267
+ MIT