Merge pull request #272 from kjd/condense-exception-attrs-doc

Condense the README section on machine-readable exception attributes

Author: kjd

README.md

@@ -74,47 +74,13 @@ base class. The more specific exceptions are:
   codepoint appears in a position whose contextual requirements are
   not satisfied.
 
-Exceptions carry machine-readable attributes so that applications
-do not need to parse the message: `code` is a short, stable identifier
-for the rule that failed (listed below); and, when the failure can be
-attributed to a particular character, `text` (the label, or domain for
-UTS #46 processing, being validated), `codepoint` (the offending
-codepoint as an integer) and `position` (its 1-based index within
-`text`, as quoted in the message) are set. Each is `None` when it does
-not apply. Message wording is not part of the API and may change.
-
-```pycon
->>> try:
-...     idna.encode('Königsgäßchen')
-... except idna.IDNAError as err:
-...     print(err.code, err.codepoint, err.position, err.text)
-disallowed_codepoint 75 1 Königsgäßchen
-```
-
-| `code` | Meaning |
-|---|---|
-| `input_too_long` | Input exceeds the library's defensive length limit and was not processed |
-| `label_too_long` | A label exceeds 63 octets |
-| `domain_too_long` | The domain exceeds 253 octets |
-| `empty_label` | A label is empty (e.g. consecutive dots) |
-| `empty_domain` | The domain is empty |
-| `not_nfc` | The label is not in Unicode Normalization Form C |
-| `hyphen_3_4` | The label has hyphens in the 3rd and 4th positions |
-| `hyphen_start_end` | The label starts or ends with a hyphen |
-| `leading_combiner` | The label starts with a combining mark |
-| `disallowed_codepoint` | A codepoint is DISALLOWED or UNASSIGNED under IDNA 2008 |
-| `contextj` | A CONTEXTJ codepoint (joiner) appears in an invalid context |
-| `contexto` | A CONTEXTO codepoint appears in an invalid context |
-| `unknown_codepoint` | A codepoint next to a joiner is unknown to this Python's Unicode database |
-| `bidi_rule_1` … `bidi_rule_6` | The corresponding rule of RFC 5893 (the Bidi Rule) is violated |
-| `bidi_unknown_direction` | A codepoint's directionality is unknown to this Python's Unicode database |
-| `invalid_alabel` | An `xn--` label is malformed or is not valid Punycode |
-| `non_canonical_alabel` | An `xn--` label is not the canonical Punycode encoding of its U-label (a "fake A-label") |
-| `invalid_ascii` | Byte input is not ASCII |
-| `invalid_utf8` | Byte input is not UTF-8 |
-| `uts46_disallowed` | A codepoint is disallowed by the UTS #46 mapping table |
-| `uts46_std3` | An ASCII character is rejected by the UTS #46 STD3 rules |
-| `unsupported_errors` | The codec was given an `errors` handler other than `strict` |
+Exceptions carry machine-readable attributes so that applications do
+not need to parse the message: `code` is a short, stable identifier
+for the rule that failed (such as `disallowed_codepoint` or
+`label_too_long`); and, when the failure can be attributed to a
+particular character, `text` (the label or domain being validated),
+`codepoint` (the offending codepoint as an integer) and `position`
+are set. 
 
 
 ## Command-line tool

tests/test_idna_errors.py

@@ -4,7 +4,6 @@
 import pickle
 import re
 import unittest
-from pathlib import Path
 from typing import get_args
 from unittest import mock
 
@@ -53,9 +52,8 @@ def test_attributes_are_populated(self):
                 if match:
                     self.assertEqual(int(match.group(1)), err.position)
 
-    def test_every_error_code_is_documented_and_raisable(self):
-        """Each code has an input that produces it, and vice versa; the README
-        table must list exactly this set."""
+    def test_every_error_code_is_raisable(self):
+        """Each code has an input that produces it, and vice versa."""
         r = "\u05d0"
         an = "\u0660"
         triggers = {
@@ -94,18 +92,6 @@ def test_every_error_code_is_documented_and_raisable(self):
                 with self.assertRaises(idna.IDNAError) as ctx:
                     trigger()
                 self.assertEqual(ctx.exception.code, code)
-        readme = Path(__file__).resolve().parent.parent / "README.md"
-        if not readme.is_file():
-            self.skipTest("README.md not present")
-        documented = set()
-        for first, last in re.findall(r"^\| `([a-z0-9_]+)`(?: \u2026 `([a-z0-9_]+)`)? \|", readme.read_text(), re.MULTILINE):
-            if last:  # a `x_1` … `x_6` range row
-                stem, lo = first.rsplit("_", 1)
-                documented.update(f"{stem}_{i}" for i in range(int(lo), int(last.rsplit("_", 1)[1]) + 1))
-            else:
-                documented.add(first)
-        documented.discard("code")  # the table header
-        self.assertEqual(documented, codes)
 
     # Conditions that depend on the host's Unicode database being older than
     # the input cannot be triggered portably (from Python 3.15,