simcord 2.0.2__tar.gz → 2.1.0__tar.gz

{simcord-2.0.2 → simcord-2.1.0}/CHANGELOG.md

@@ -4,6 +4,13 @@ This changelog is generated with [towncrier](https://towncrier.readthedocs.io/).
 
 <!-- towncrier release notes start -->
 
+## 2.1.0 (2026-09-19)
+
+### Features
+
+- Add `Env.http_requests` records with query parameters and audit reasons while preserving the deprecated live `Env.http_log` tuple list for 2.x compatibility.
+
+
 ## 2.0.2 (2026-09-18)
 
 ### Bug fixes

{simcord-2.0.2 → simcord-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simcord
-Version: 2.0.2
+Version: 2.1.0
 Summary: Offline discord.py bot testing with pytest. No network, token, or test server.
 Project-URL: Homepage, https://github.com/SilentHacks/simcord
 Project-URL: Documentation, https://simcord.readthedocs.io/
@@ -263,7 +263,11 @@ When something goes wrong, the `env` tells you what happened:
 
 - `env.transcript()`: the ordered log of gateway events and REST calls, auto-attached to
   failing pytest tests.
-- `env.http_log`: every REST request the bot made, to assert on or inspect.
+- `env.http_requests`: structured records for every REST request (`method`, `path`, `params`,
+  `json`, `reason`). Values are discord.py transport arguments, not wire-normalized strings or
+  headers; uploaded files are not captured.
+- `env.http_log`: deprecated live `(method, path, json_body)` tuples for 2.x compatibility;
+  access emits `DeprecationWarning`.
 - `env.errors`: exceptions the bot swallowed.
 - `env.inject_error("POST", "/channels/*/messages", status=500)`: make matching REST calls
   fail, to test your bot's error handling.

{simcord-2.0.2 → simcord-2.1.0}/README.md

@@ -216,7 +216,11 @@ When something goes wrong, the `env` tells you what happened:
 
 - `env.transcript()`: the ordered log of gateway events and REST calls, auto-attached to
   failing pytest tests.
-- `env.http_log`: every REST request the bot made, to assert on or inspect.
+- `env.http_requests`: structured records for every REST request (`method`, `path`, `params`,
+  `json`, `reason`). Values are discord.py transport arguments, not wire-normalized strings or
+  headers; uploaded files are not captured.
+- `env.http_log`: deprecated live `(method, path, json_body)` tuples for 2.x compatibility;
+  access emits `DeprecationWarning`.
 - `env.errors`: exceptions the bot swallowed.
 - `env.inject_error("POST", "/channels/*/messages", status=500)`: make matching REST calls
   fail, to test your bot's error handling.

{simcord-2.0.2 → simcord-2.1.0}/docs/api.md

@@ -26,6 +26,16 @@ top-level `simcord` package.
 Use `await env.external_wait(awaitable, reason="...")` for one explicitly scoped external
 input wait. Unknown waits remain active and produce a diagnostic timeout.
 
+
+## Request observability
+
+::: simcord.HttpLogEntry
+
+`Env.http_requests` exposes these records for transport-level assertions. The `params` and
+`reason` fields contain discord.py transport arguments, not wire-normalized query strings or
+encoded headers; uploaded files are not captured. `Env.http_log` is a deprecated compatibility
+list of legacy tuples.
+
 ## Builders
 
 Synchronous, omnipotent handles for arranging the virtual Discord. Returned by `env`/`guild`

{simcord-2.0.2 → simcord-2.1.0}/docs/concepts.md

@@ -23,8 +23,8 @@ async def test_something(simcord_env):
 ```
 
 The `Env` owns the virtual backend, tracks the bot's background tasks, captures errors,
-holds the virtual clock, and exposes the diagnostics (`env.http_log`, `env.transcript()`).
-A fresh `Env` is created for each test, so tests never leak state into each other.
+holds the virtual clock, and exposes the diagnostics (`env.http_requests`, `env.transcript()`).
+`env.http_log` is retained as a deprecated compatibility view.
 
 !!! info "One environment per event loop"
     `Env` monkeypatches `loop.create_task` and `time.monotonic` while it's live so it can
@@ -132,7 +132,7 @@ channel.history(viewer=mod)          # ephemeral-aware: what `mod` would see
 channel.pinned_messages()            # list[discord.Message]
 guild.get_ban(target)                # ban record | None
 env.errors                           # exceptions the bot swallowed
-env.http_log                         # every REST call the bot made
+env.http_requests                    # structured REST request records
 ```
 
 Interaction verbs return a richer [`InteractionResult`](api.md#simcord.InteractionResult) capturing

{simcord-2.0.2 → simcord-2.1.0}/docs/cookbook.md

@@ -246,7 +246,11 @@ async def test_no_double_post(simcord_env):
 
     await alice.send(channel, "!announce")
 
-    posts = [c for c in simcord_env.http_log if c[0] == "POST" and "/messages" in c[1]]
+    posts = [
+        entry
+        for entry in simcord_env.http_requests
+        if entry.method == "POST" and "/messages" in entry.path
+    ]
     assert len(posts) == 1
 ```
 

{simcord-2.0.2 → simcord-2.1.0}/docs/guides/diagnostics.md

@@ -107,19 +107,30 @@ The [pytest plugin attaches this to failing tests automatically](fixtures.md#the
 so a failure shows you exactly what the bot did, in order — usually enough to diagnose
 without a debugger.
 
-## The HTTP log (`env.http_log`)
+## HTTP request records (`env.http_requests`)
 
-For fine-grained assertions, `env.http_log` is the list of every REST call the bot made, as
-`(method, path, json_body)` tuples:
+For fine-grained assertions, `env.http_requests` is the list of every REST call the bot made,
+as [`simcord.HttpLogEntry`](../api.md#simcord.HttpLogEntry) records:
 
 ```python
-posts = [c for c in simcord_env.http_log if c[0] == "POST" and "/messages" in c[1]]
-assert len(posts) == 1                       # the bot sent exactly one message
-assert posts[0][2]["content"] == "Pong!"
+posts = [
+    entry
+    for entry in simcord_env.http_requests
+    if entry.method == "POST" and "/messages" in entry.path
+]
+assert len(posts) == 1
+assert posts[0].json["content"] == "Pong!"
 ```
 
-This is how you assert the bot **didn't** do something (e.g. didn't double-post), or made
-exactly the calls you expect.
+Each record exposes `method`, `path`, `params`, `json`, and `reason`. These values are the
+arguments discord.py passed to its transport: query parameters are not wire-normalized
+strings, and `reason` is not an encoded HTTP header value. Uploaded files are not captured.
+The request record is appended before fault injection and route handling, so failed and
+unimplemented requests remain observable.
+
+`env.http_log` remains available as a deprecated live list of legacy
+`(method, path, json_body)` tuples for 2.x compatibility. Access emits `DeprecationWarning`;
+use `env.http_requests` for new assertions.
 
 ## Injecting API failures
 

{simcord-2.0.2 → simcord-2.1.0}/docs/parity-matrix.md

@@ -46,7 +46,7 @@ serializer payloads are conformance-tested against discord.py's own model parser
 | Guilds (create/edit/delete) | ✅ | `Client.create_guild`, `Guild.edit`, `Guild.delete` (owner-only); `GUILD_UPDATE` audit; `Guild.leave`, `Client.fetch_guilds`, `ClientUser.edit` (bot username); `Guild.vanity_invite` (settable via `guild.set_vanity_url`) |
 | Channels (create/edit/delete, overwrites) | ✅ | Runtime create + list; text, voice, stage, category & forum kinds; reorder/move (`Channel.move`); announcement `TextChannel.follow` |
 | Webhooks | ✅ | Create, execute (with per-message `username` override), fetch/edit/delete (by id or token), guild listing |
-| Fault injection / HTTP log | ✅ | `env.inject_error`, `env.http_log` |
+| Fault injection / HTTP log | ✅ | `env.inject_error`, structured `env.http_requests` records, deprecated `env.http_log` tuples |
 | Audit logs | ✅ | Recorded for ban/kick/role/member/channel/event actions; `guild.audit_logs()`, filtering |
 | Polls | ✅ | Message-level poll object; `actor.vote`, expiry (route + `advance_time`), vote events |
 | Scheduled events | ✅ | CRUD + subscribe/unsubscribe; auto status transitions via `advance_time` |

{simcord-2.0.2 → simcord-2.1.0}/docs/quickstart.md

@@ -124,10 +124,9 @@ see [Core concepts](concepts.md) for the deep dive.
   `alice.click(...)`, `alice.select(...)`, `alice.react(...)`, `alice.submit_modal(...)`.
   Do only what a real user physically could. Each one **waits for your bot to finish
   reacting** before returning — so there's never an `asyncio.sleep` in your tests.
-- **Queries** — `channel.history()`, `channel.last_message`,
-  [`env.errors`](guides/diagnostics.md) (errors your bot swallowed),
-  [`env.http_log`](guides/diagnostics.md) (every REST call it made). Assert with plain
-  Python against real `discord.Message` objects.
+- **Queries** — `channel.history()`, [`env.errors`](guides/diagnostics.md) (errors your bot
+  swallowed), and [`env.http_requests`](guides/diagnostics.md) (structured REST request
+  records). Assert with plain Python against real `discord.Message` objects.
 
 ## Testing failure paths
 

{simcord-2.0.2 → simcord-2.1.0}/docs/stability.md

@@ -68,11 +68,18 @@ The public surface is exactly what `simcord` exports from its top-level package
 - the world builders — `GuildHandle`, `ChannelHandle`, `UserHandle`,
   `RoleHandle` — and the `MemberActor` that drives simulated users;
 - the result objects `ResponseMessage` and `InteractionResult`;
+- the request-observability type `HttpLogEntry` and `Env.http_requests`;
 - the assertion helpers (`assert_responded`, `assert_sent`, `assert_message`,
   `assert_error`, `assert_no_errors`);
 - the error and parity-signal types `BackendError`, `SetupError`,
   `RouteNotImplemented` and `UnsupportedField`.
 
+`Env.http_requests` is the semver-covered request-observability API. Its
+`HttpLogEntry` fields preserve discord.py transport arguments (`params`, `json`, and
+`reason`); they are not wire-normalized query strings or encoded headers, and files are
+not captured. `Env.http_log` remains the live 2.x tuple list and emits
+`DeprecationWarning` on access.
+
 The `pytest` plugin (the `simcord_env` fixture) is part of the public surface
 too.
 

{simcord-2.0.2 → simcord-2.1.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "simcord"
-version = "2.0.2"
+version = "2.1.0"
 description = "Offline discord.py bot testing with pytest. No network, token, or test server."
 readme = "README.md"
 license = "MIT"

{simcord-2.0.2 → simcord-2.1.0}/src/simcord/__init__.py

@@ -46,6 +46,7 @@ from .builders import (  # noqa: E402
 from .env import Env, run  # noqa: E402
 from .http import RouteNotImplemented, UnsupportedField  # noqa: E402
 from .results import InteractionResult, ResponseMessage  # noqa: E402
+from .types import HttpLogEntry  # noqa: E402
 
 try:
     __version__ = version("simcord")
@@ -57,6 +58,7 @@ __all__ = (
     "ChannelHandle",
     "Env",
     "GuildHandle",
+    "HttpLogEntry",
     "InteractionResult",
     "MemberActor",
     "ResponseMessage",

{simcord-2.0.2 → simcord-2.1.0}/src/simcord/backend/ops/base.py

@@ -13,6 +13,7 @@ import datetime
 from collections.abc import Callable, Mapping, Sequence
 from typing import Any
 
+from ...types import HttpLogEntry
 from .. import errors, permissions
 from ..cdn import CdnStore
 from ..models import (
@@ -59,6 +60,7 @@ class BackendBase:
         self.cdn = CdnStore()
         self.subscribers: list[EventListener] = []
         self.http_log: list[tuple[str, str, dict[str, Any] | None]] = []
+        self.http_requests: list[HttpLogEntry] = []
         #: Interleaved record of everything that crossed either seam, in order:
         #: ("HTTP", "METHOD /path", body) and ("GATEWAY", event, payload).
         self.transcript: list[tuple[str, str, Any]] = []

{simcord-2.0.2 → simcord-2.1.0}/src/simcord/env.py

@@ -6,6 +6,7 @@ import asyncio
 import contextvars
 import math
 import time
+import warnings
 import weakref
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -22,6 +23,7 @@ from .backend.errors import SetupError
 from .builders import GuildHandle, UserHandle
 from .gateway import ShardRouter
 from .http import FakeHTTPClient, FakeWebhookAdapter
+from .types import HttpLogEntry
 
 _BOT_SCOPE: contextvars.ContextVar[tuple[Any, int] | None] = contextvars.ContextVar(
     "simcord_bot_scope", default=None
@@ -906,9 +908,19 @@ class Env:
 
     # ----------------------------------------------------------- diagnostics
 
+    @property
+    def http_requests(self) -> list[HttpLogEntry]:
+        """Every REST call the bot made as a structured request record."""
+        return self.backend.http_requests
+
     @property
     def http_log(self) -> list[tuple[str, str, dict[str, Any] | None]]:
-        """Every REST call the bot made: (method, path, json body)."""
+        """Deprecated live ``(method, path, json)`` REST call tuples."""
+        warnings.warn(
+            "Env.http_log is deprecated; use Env.http_requests instead",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.backend.http_log
 
     def transcript(self) -> str:

{simcord-2.0.2 → simcord-2.1.0}/src/simcord/http/router.py

@@ -3,7 +3,7 @@
 Unknown routes always fail loudly with :class:`RouteNotImplemented` — a
 testing tool must never silently fake success. The router also services
 test-injected faults (``env.inject_error``) and records every call to
-``backend.http_log`` for advanced assertions.
+``backend.http_requests`` plus the deprecated ``backend.http_log`` tuple list.
 """
 
 from __future__ import annotations
@@ -17,6 +17,7 @@ from typing import Any
 from ..backend import Backend
 from ..backend.errors import BackendError
 from ..backend.models import Channel
+from ..types import HttpLogEntry
 
 
 class RouteNotImplemented(BackendError):
@@ -192,6 +193,7 @@ def dispatch(
     reason: str | None = None,
 ) -> Any:
     backend.http_log.append((method, path, json if isinstance(json, dict) else None))
+    backend.http_requests.append(HttpLogEntry(method, path, dict(params or {}), json, reason))
     backend.transcript.append(("HTTP", f"{method} {path}", json if isinstance(json, dict) else None))
     _check_faults(backend, method, path)
     segments = path.strip("/").split("/")

simcord-2.1.0/src/simcord/types.py

@@ -0,0 +1,17 @@
+"""Public observability value types."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class HttpLogEntry:
+    """A transport-level REST request made by the bot."""
+
+    method: str
+    path: str
+    params: dict[str, Any]
+    json: Any | None
+    reason: str | None

{simcord-2.0.2 → simcord-2.1.0}/tests/integration/test_diagnostics.py

@@ -77,8 +77,20 @@ async def test_unimplemented_route_attaches_parity_note(env, channel):
 
 async def test_http_log_records_bot_calls(env, channel, alice):
     await alice.send(channel, "!ping")
-    sends = [(m, p) for (m, p, _body) in env.http_log if m == "POST" and p.endswith("/messages")]
-    assert sends, env.http_log
+    sends = [
+        (entry.method, entry.path)
+        for entry in env.http_requests
+        if entry.method == "POST" and entry.path.endswith("/messages")
+    ]
+    assert sends, env.http_requests
+
+
+async def test_http_log_legacy_tuples_warn_and_remain_live(env):
+    with pytest.warns(DeprecationWarning, match="use Env.http_requests"):
+        legacy = env.http_log
+    assert legacy is env.backend.http_log
+    legacy.append(("TEST", "/compatibility", None))
+    assert env.backend.http_log[-1] == ("TEST", "/compatibility", None)
 
 
 async def test_embed_limits_enforced(env, channel):

{simcord-2.0.2 → simcord-2.1.0}/tests/integration/test_misc_branches.py

@@ -10,7 +10,7 @@ async def test_bot_typing_indicator(env, channel):
         pass
     await env.settle()
 
-    assert any(method == "POST" and path.endswith("/typing") for method, path, _ in env.http_log)
+    assert any(entry.method == "POST" and entry.path.endswith("/typing") for entry in env.http_requests)
 
 
 async def test_everyone_mention_requires_permission(env, channel):

{simcord-2.0.2 → simcord-2.1.0}/tests/integration/test_moderation.py

@@ -16,6 +16,29 @@ async def test_bulk_ban(env):
     assert alice.id not in env.backend.get_guild(env.guild.id).members
 
 
+async def test_ban_request_records_query_params_and_reason(env):
+    target = env.guild.add_member(env.create_user("baddie"))
+    await env.settle()
+
+    guild = env.bot.get_guild(env.guild.id)
+    await guild.ban(
+        discord.Object(id=target.id),
+        delete_message_seconds=86400,
+        reason="cleanup needed",
+    )
+    await env.settle()
+
+    bans = [
+        entry
+        for entry in env.http_requests
+        if entry.method == "PUT" and entry.path.endswith(f"/bans/{target.id}")
+    ]
+    assert len(bans) == 1
+    assert bans[0].params == {"delete_message_seconds": 86400}
+    assert bans[0].reason == "cleanup needed"
+    assert bans[0].json is None
+
+
 async def test_bulk_ban_already_banned_reported_as_failed(env):
     # When nobody can be banned (all already banned), Discord still returns the
     # split result — not a 403 — with every id in `failed`.

simcord-2.1.0/tests/unit/test_router.py

@@ -0,0 +1,80 @@
+import pytest
+
+from simcord import HttpLogEntry
+from simcord.backend import Backend
+from simcord.backend.errors import BackendError
+from simcord.http import router
+from simcord.http import routes as _routes  # noqa: F401  — registers handlers
+
+
+def test_unknown_route_raises_with_route_name():
+    backend = Backend()
+    with pytest.raises(router.RouteNotImplemented, match="GET /made/up/route"):
+        router.dispatch(backend, "GET", "/made/up/route")
+    assert isinstance(backend.http_requests[-1], HttpLogEntry)
+
+
+def test_literal_segments_beat_parameters():
+    backend = Backend()
+    guild = backend.create_guild("g")
+    channel = backend.create_channel(guild.id, "general")
+    message = backend.create_message(channel.id, backend.bot_user.id, "hi")
+    backend.set_pinned(channel.id, message.id, True)
+    # ".../messages/pins" must not be captured by ".../messages/{message_id}".
+    result = router.dispatch(backend, "GET", f"/channels/{channel.id}/messages/pins")
+    assert [int(i["message"]["id"]) for i in result["items"]] == [message.id]
+
+
+def test_http_request_records_defaults_and_coexists_with_legacy_tuples():
+    backend = Backend()
+    guild = backend.create_guild("g")
+    path = f"/guilds/{guild.id}"
+    router.dispatch(backend, "GET", path)
+    entry = backend.http_requests[-1]
+    assert (entry.method, entry.path, entry.params, entry.json, entry.reason) == (
+        "GET",
+        path,
+        {},
+        None,
+        None,
+    )
+    assert backend.http_log[-1] == ("GET", path, None)
+
+    payload = {"name": "g"}
+    router.dispatch(backend, "GET", path, json=payload)
+    assert backend.http_requests[-1].json is payload
+    assert backend.http_log[-1] == ("GET", path, payload)
+
+
+def test_http_request_records_snapshot_transport_values_before_fault():
+    backend = Backend()
+    guild = backend.create_guild("g")
+    path = f"/guilds/{guild.id}"
+    params = {"limit": 3}
+    payload = ["raw", 1]
+    backend.faults.append(
+        {
+            "method": "GET",
+            "path": path,
+            "status": 500,
+            "code": 0,
+            "message": "boom",
+            "times": 1,
+        }
+    )
+    with pytest.raises(BackendError):
+        router.dispatch(backend, "GET", path, params=params, json=payload, reason="cleanup needed")
+    entry = backend.http_requests[-1]
+    assert entry.params == params and entry.params is not params
+    assert entry.json is payload
+    assert entry.reason == "cleanup needed"
+
+
+def test_snowflakes_are_monotonic_and_timestamped():
+    backend = Backend()
+    flakes = [backend.snowflake() for _ in range(100)]
+    assert flakes == sorted(flakes) and len(set(flakes)) == 100
+    import discord
+
+    # Embedded timestamps decode to the fixed virtual epoch (2026+).
+    assert discord.utils.snowflake_time(flakes[0]).year >= 2026

{simcord-2.0.2 → simcord-2.1.0}/uv.lock

@@ -1402,7 +1402,7 @@ wheels = [
 
 [[package]]
 name = "simcord"
-version = "2.0.2"
+version = "2.1.0"
 source = { editable = "." }
 dependencies = [
     { name = "discord-py" },

simcord-2.0.2/tests/unit/test_router.py

@@ -1,39 +0,0 @@
-import pytest
-
-from simcord.backend import Backend
-from simcord.http import router
-from simcord.http import routes as _routes  # noqa: F401  — registers handlers
-
-
-def test_unknown_route_raises_with_route_name():
-    backend = Backend()
-    with pytest.raises(router.RouteNotImplemented, match="GET /made/up/route"):
-        router.dispatch(backend, "GET", "/made/up/route")
-
-
-def test_literal_segments_beat_parameters():
-    backend = Backend()
-    guild = backend.create_guild("g")
-    channel = backend.create_channel(guild.id, "general")
-    message = backend.create_message(channel.id, backend.bot_user.id, "hi")
-    backend.set_pinned(channel.id, message.id, True)
-    # ".../messages/pins" must not be captured by ".../messages/{message_id}".
-    result = router.dispatch(backend, "GET", f"/channels/{channel.id}/messages/pins")
-    assert [int(i["message"]["id"]) for i in result["items"]] == [message.id]
-
-
-def test_http_log_records_calls():
-    backend = Backend()
-    guild = backend.create_guild("g")
-    router.dispatch(backend, "GET", f"/guilds/{guild.id}")
-    assert backend.http_log[-1][:2] == ("GET", f"/guilds/{guild.id}")
-
-
-def test_snowflakes_are_monotonic_and_timestamped():
-    backend = Backend()
-    flakes = [backend.snowflake() for _ in range(100)]
-    assert flakes == sorted(flakes) and len(set(flakes)) == 100
-    import discord
-
-    # Embedded timestamps decode to the fixed virtual epoch (2026+).
-    assert discord.utils.snowflake_time(flakes[0]).year >= 2026