Place contrast lessons across examples

Author: adewale

src/asset_manifest.py

@@ -1,3 +1,3 @@
 # Generated by scripts/fingerprint_assets.py. Do not edit by hand.
 ASSET_PATHS = {'SITE_CSS': '/site.06e133dcde6a.css', 'SYNTAX_JS': '/syntax-highlight.3b6c7f730d46.js', 'EDITOR_JS': '/editor.dd81f5171b14.js'}
-HTML_CACHE_VERSION = 'e289cc4cc5c2'
+HTML_CACHE_VERSION = 'd3f04ba18268'

src/example_sources/mutability.md

@@ -2,41 +2,43 @@
 slug = "mutability"
 title = "Mutability"
 section = "Data Model"
-summary = "Some objects can change in place, and names can share one object."
+summary = "Some objects change in place, while others return new values."
 doc_path = "/reference/datamodel.html#objects-values-and-types"
 +++
 
-Objects in Python can be mutable or immutable. Mutable objects such as lists can change in place, while immutable objects such as strings produce new values instead.
+Objects in Python can be mutable or immutable. Mutable objects such as lists and dictionaries can change in place, while immutable objects such as strings and tuples produce new values instead.
 
 Names can share one mutable object, so a change through one name is visible through another. This is powerful, but it is also the source of many beginner surprises.
 
-Understanding mutability explains why copying containers, avoiding mutable defaults, and returning new values are recurring Python design choices.
+The boundary matters across Python: `append()` mutates a list, string methods return new strings, and `sorted()` returns a new list while `list.sort()` mutates an existing one.
 
 :::program
 ```python
 first = ["python"]
 second = first
 second.append("workers")
-
 print(first)
 print(second)
 
 text = "python"
-text.upper()
+upper_text = text.upper()
 print(text)
+print(upper_text)
+
+numbers = [3, 1, 2]
+ordered = sorted(numbers)
+print(ordered)
+print(numbers)
 ```
 :::
 
 :::cell
-Objects in Python can be mutable or immutable. Mutable objects such as lists can change in place, while immutable objects such as strings produce new values instead.
-
-Names can share one mutable object, so a change through one name is visible through another. This is powerful, but it is also the source of many beginner surprises.
+Mutable objects can change in place. `first` and `second` point to the same list, so appending through one name changes the object seen through both names.
 
 ```python
 first = ["python"]
 second = first
 second.append("workers")
-
 print(first)
 print(second)
 ```
@@ -48,20 +50,39 @@ print(second)
 :::
 
 :::cell
-Understanding mutability explains why copying containers, avoiding mutable defaults, and returning new values are recurring Python design choices.
+Immutable objects do not change in place. String methods such as `upper()` return a new string, leaving the original string unchanged.
 
 ```python
 text = "python"
-text.upper()
+upper_text = text.upper()
 print(text)
+print(upper_text)
 ```
 
 ```output
 python
+PYTHON
+```
+:::
+
+:::cell
+Some APIs make the boundary explicit. `sorted()` returns a new list, while methods such as `append()` and `list.sort()` mutate an existing list.
+
+```python
+numbers = [3, 1, 2]
+ordered = sorted(numbers)
+print(ordered)
+print(numbers)
+```
+
+```output
+[1, 2, 3]
+[3, 1, 2]
 ```
 :::
 
 :::note
 - Lists and dictionaries are mutable; strings and tuples are immutable.
 - Aliasing is useful, but copy mutable containers when independent changes are needed.
+- Pay attention to whether an operation mutates in place or returns a new value.
 :::

src/example_sources/none.md

@@ -2,15 +2,15 @@
 slug = "none"
 title = "None"
 section = "Basics"
-summary = "None represents the absence of a value."
+summary = "None represents expected absence, distinct from missing keys and errors."
 doc_path = "/library/constants.html#None"
 +++
 
 `None` represents the absence of a value. It is the usual sentinel when a function has no result to return but the absence itself is meaningful.
 
 Because `None` is a singleton, idiomatic Python checks it with `is None` or `is not None`. This avoids confusing identity with value equality.
 
-A function that reaches the end without a `return` statement returns `None`, so explicit `None` results should be documented by names and control flow.
+Absence has several nearby shapes in Python. A function can return `None`, a dictionary lookup can supply a default for a missing key, and an invalid operation can raise an exception.
 
 :::program
 ```python
@@ -23,13 +23,20 @@ def find_score(name):
     return None
 
 score = find_score("Grace")
-if score is None:
-    print("missing score")
+print(score is None)
+
+profile = {"name": "Ada"}
+print(profile.get("timezone", "UTC"))
+
+try:
+    int("python")
+except ValueError:
+    print("invalid number")
 ```
 :::
 
 :::cell
-`None` is Python's value for “nothing here.” It is commonly used as a sentinel when a real result is unavailable.
+`None` is Python's value for “nothing here.” Check it with `is None` because it is a singleton identity value.
 
 ```python
 result = None
@@ -42,9 +49,7 @@ True
 :::
 
 :::cell
-Functions often return `None` when lookup or parsing fails without raising an exception.
-
-Check for `None` with `is None`. That tests identity with the singleton object instead of asking for value equality.
+Functions often return `None` when absence is expected and callers can continue. The function name and surrounding code should make that possibility clear.
 
 ```python
 def find_score(name):
@@ -53,16 +58,35 @@ def find_score(name):
     return None
 
 score = find_score("Grace")
-if score is None:
-    print("missing score")
+print(score is None)
+```
+
+```output
+True
+```
+:::
+
+:::cell
+A missing dictionary key is another absence boundary. Use `get()` when the mapping can supply a default, and use exceptions for invalid operations that cannot produce a value.
+
+```python
+profile = {"name": "Ada"}
+print(profile.get("timezone", "UTC"))
+
+try:
+    int("python")
+except ValueError:
+    print("invalid number")
 ```
 
 ```output
-missing score
+UTC
+invalid number
 ```
 :::
 
 :::note
 - Use `is None` rather than `== None`; `None` is a singleton identity value.
-- A function that reaches the end without `return` also returns `None`.
+- Use `None` for expected absence that callers can test.
+- Use dictionary defaults for missing mapping keys and exceptions for invalid operations.
 :::

src/example_sources/sets.md

@@ -2,37 +2,40 @@
 slug = "sets"
 title = "Sets"
 section = "Collections"
-summary = "Sets store unique values and support set algebra."
+summary = "Sets store unique values and make membership checks explicit."
 doc_path = "/tutorial/datastructures.html#sets"
 +++
 
 Sets store unique hashable values. Use them when membership and de-duplication matter more than order.
 
-The `in` operator is the everyday membership test. Set algebra then expresses how groups relate to each other.
+A list can answer membership with `in`, but a set communicates that membership is the main operation. Set algebra then expresses how groups relate to each other.
 
 Because sets are unordered, examples often wrap output in `sorted()` so the display is deterministic.
 
 :::program
 ```python
-languages = {"python", "go", "python"}
-compiled = {"go", "rust"}
+languages = ["python", "go", "python"]
+unique_languages = set(languages)
+print(sorted(unique_languages))
+
+allowed = {"python", "rust"}
+print("python" in allowed)
+print("ruby" in allowed)
 
-print(sorted(languages))
-print("python" in languages)
-print(sorted(languages | compiled))
-print(sorted(languages & compiled))
-print(sorted(languages - compiled))
+compiled = {"go", "rust"}
+print(sorted(allowed | compiled))
+print(sorted(allowed & compiled))
+print(sorted(allowed - compiled))
 ```
 :::
 
 :::cell
-Creating a set automatically removes duplicates. The repeated `python` value appears only once.
+Creating a set removes duplicates. Keep a list when order and repeated values matter; convert to a set when uniqueness is the point.
 
 ```python
-languages = {"python", "go", "python"}
-compiled = {"go", "rust"}
-
-print(sorted(languages))
+languages = ["python", "go", "python"]
+unique_languages = set(languages)
+print(sorted(unique_languages))
 ```
 
 ```output
@@ -41,35 +44,39 @@ print(sorted(languages))
 :::
 
 :::cell
-Membership checks are the most common set operation.
+Membership checks are the everyday set operation. A list can also use `in`, but a set says that membership is central to the data shape.
 
 ```python
-print("python" in languages)
+allowed = {"python", "rust"}
+print("python" in allowed)
+print("ruby" in allowed)
 ```
 
 ```output
 True
+False
 ```
 :::
 
 :::cell
 Union, intersection, and difference describe relationships between groups without manual loops.
 
 ```python
-print(sorted(languages | compiled))
-print(sorted(languages & compiled))
-print(sorted(languages - compiled))
+compiled = {"go", "rust"}
+print(sorted(allowed | compiled))
+print(sorted(allowed & compiled))
+print(sorted(allowed - compiled))
 ```
 
 ```output
 ['go', 'python', 'rust']
-['go']
+['rust']
 ['python']
 ```
 :::
 
 :::note
-- Sets remove duplicates and support fast membership tests.
-- Set algebra operators make union, intersection, and difference explicit.
+- Use lists when order and repeated values matter.
+- Use sets when uniqueness and membership are the main operations.
 - Sets are unordered, so sort them when examples need deterministic display.
 :::