update documentation and fix code examples for clarity and accuracy

Author: charliecloudberry

crates/by_typeshed_patch/src/patches/container_overlapping.rs

@@ -3,8 +3,10 @@
 //! `Container` is covariant in its element (`out Element`), so a membership test
 //! consumes that covariant typevar in an input position. basedpython types the
 //! parameter as `Overlapping[Element]`: a value is accepted iff it is not
-//! disjoint from `Element`, so `1 in xs` and `object() in xs` are allowed for an
-//! `xs: Container[int]`, while `"a" in xs` is rejected
+//! disjoint from `Element`, so for an `xs: Container[int]` both `1 in xs` and
+//! `o in xs` (an `o: object`) are allowed, while `"a" in xs` is rejected. a bare
+//! `object()` is inferred `final object` — exactly `object`, so disjoint from
+//! `int` — and is rejected like any other disjoint operand
 //!
 //! `Container.__contains__` is the abstract membership requirement. every other
 //! container that already declares `__contains__` keeps its own declaration

crates/ty/src/cli-reference.md

@@ -50,7 +50,7 @@ transpiled output to stdout:
 
 ```sh
 by transpile hello.by
-echo 'x[(a, b)]' | by transpile
+echo 'a = b ?? 1' | by transpile
 ```
 
 ### `--reverse`

crates/ty_python_semantic/src/api_lockfile.rs

@@ -5,8 +5,9 @@
 //! the lockfile is meant to be diffed, not parsed back into types. any
 //! type-level change in a public symbol surfaces as a line-level diff
 //!
-//! the first line is `#api-lock:v=1` (grammar version). subsequent lines are
-//! sorted lexicographically. one record per line:
+//! four `#`-prefixed header lines come first: `#api-lock:v=1` (grammar
+//! version), `#tool:by=<version>`, `#python:<target>` and `#modules:<count>`.
+//! the records follow, sorted lexicographically, one per line:
 //!
 //! ```text
 //! <qualified>:c[<bases>]                              # class

docs/basedpython/features/api-lock.md

@@ -21,9 +21,11 @@ by generate-api-file -o public.lock
 
 ## record grammar
 
-each non-header line is one record. fields are colon-separated. the first
-line is the format-version header (`#api-lock:v=1`); the remaining lines
-are sorted lexicographically
+the file opens with four `#`-prefixed header lines: the format version
+(`#api-lock:v=1`), the generating `by` version (`#tool:by=0.0.5`), the target
+(`#python:3.13`, or `#python:default` when no `--python-version` was given) and
+the number of modules walked (`#modules:12`). every line after them is one
+record. fields are colon-separated, and the records are sorted lexicographically
 
 ```text
 <qualified>:c[<bases>]                       # class

docs/basedpython/features/checked-cast.md

@@ -28,7 +28,7 @@ def _checked_cast(_v, _t):
         )
     return _v
 
-def f(a):
+def f(a: object):
     b = _checked_cast(a, int)
     print(b)
 ```

docs/basedpython/features/float-literals.md

@@ -105,6 +105,6 @@ surrounding whitespace) — constructs an ordinary `float`
 
 ```by
 def f(x: str) -> None:
-    reveal_type(float(x))  # revealed: float
-    reveal_type(float("1_000.5"))  # revealed: float
+    reveal_type(float(x))  # revealed: final float
+    reveal_type(float("1_000.5"))  # revealed: final float
 ```

docs/basedpython/features/implementations.md

@@ -331,7 +331,7 @@ implementation A for B:
 →
 
 ```python
-class __by_impl__A__B(_by_Implementation, A):  # basedpython: implementation A for B
+class _by_impl__A__B(_by_Implementation, A):  # basedpython: implementation A for B
     __slots__ = ()
 
     def f(self):
@@ -387,16 +387,16 @@ xs: list[A] = [b1, b2]
 →
 
 ```python
-f(__by_impl__A__B(b))
-xs: list[A] = [__by_impl__A__B(b1), __by_impl__A__B(b2)]
+f(_by_impl__A__B(b))
+xs: list[A] = [_by_impl__A__B(b1), _by_impl__A__B(b2)]
 ```
 
 when the implementation lives in another module, the lowering emits the precise
 import of the witness class, keyed off the checker's resolution — the same
 implicit-import treatment extension members get:
 
 ```python
-from adapters import __by_impl__A__B
+from adapters import _by_impl__A__B
 ```
 
 ## round-tripping
@@ -497,7 +497,7 @@ settling separately. adding inherent members is what extensions are for
         (`project_db` + `transpile_typed`), beside
         `imported_extension_rewrites_call_and_adds_import`: a conversion site
         whose witness class lives in another module must wrap the expression *and*
-        emit `from impl_mod import __by_impl__A__B`, and the anonymous mangled
+        emit `from impl_mod import _by_impl__A__B`, and the anonymous mangled
         name must agree between the two files
     - **runtime** — an `implementation_runtime.rs` beside the other `*_runtime.rs`
         integration tests, for shared mutation through a witness, `==` / `hash`

docs/basedpython/features/keyword-variadic.md

@@ -54,7 +54,7 @@ class A[**Kwargs]:
     init(**kwargs: **Kwargs)
 
 a = A(x=1, y="s")
-reveal_type(a)  # A[x=int, y=str]
+reveal_type(a)  # final A[x=int, y=str]
 ```
 
 the pack is solved as a whole rather than per-argument, so `A()` gives the empty pack `A[()]`. field

docs/basedpython/features/none-coalesce.md

@@ -9,9 +9,13 @@ name = user.display_name ?? "anonymous"
 transpiles to:
 
 ```python
-name = user.display_name if user.display_name is not None else "anonymous"
+name = __by_t_0__ if (__by_t_0__ := user.display_name) is not None else "anonymous"
 ```
 
+a compound left operand is bound to a temp by the walrus so it is evaluated
+exactly once. a bare name needs no temp and is repeated directly — `a ?? b` is
+`a if a is not None else b`
+
 ## semantics
 
 `??` tests `is not None` (identity) — not falsiness. an empty string, zero,

docs/basedpython/features/not-type.md

@@ -6,7 +6,7 @@
 def f(x: not int) -> None: ...
 
 f("a")  # ok
-f()1)   # error
+f(1)    # error
 ```
 
 transpiles to: