Improve __replace__ typing and documentation

docs/source/structs.rst

@@ -161,6 +161,14 @@ at the end of the generated ``__init__`` method. It has the same semantics as th
 This method may be useful for adding additional logic to the init (such as
 custom validation).
 
+.. important::
+
+    ``__post_init__`` will *not* be called when using any of
+
+    - :func:`msgspec.structs.replace`,
+    - :func:`copy.replace`,
+    - :func:`copy.copy`,
+
 In addition to in ``__init__``, the ``__post_init__`` hook is also called when:
 
 - Decoding into a struct type (e.g. ``msgspec.json.decode(..., type=MyStruct)``)

msgspec/__init__.pyi

@@ -17,7 +17,7 @@ from typing import (
     overload,
 )
 
-from typing_extensions import dataclass_transform, Buffer
+from typing_extensions import dataclass_transform, Buffer, Self
 
 from . import inspect, json, msgpack, structs, toml, yaml
 
@@ -118,6 +118,7 @@ class Struct(metaclass=StructMeta):
     def __rich_repr__(
         self,
     ) -> Iterable[Union[Any, Tuple[Any], Tuple[str, Any], Tuple[str, Any, Any]]]: ...
+    def __replace__(self, **changes: Any) -> Self: ...
 
 def defstruct(
     name: str,