Merge branch 'speced:main' into main

MANIFEST.in

@@ -1,6 +1,7 @@
 include README.md
 include requirements.txt
 include bikeshed/semver.txt
+include bikeshed/py.typed
 recursive-include bikeshed *.js *.css *.bsfont
 graft docs
 graft bikeshed/spec-data

bikeshed/Spec.py

@@ -490,7 +490,7 @@ def printTargets(self) -> None:
     def isOpaqueElement(self, el: t.ElementT) -> bool:
         if el.tag in self.md.opaqueElements:
             return True
-        if el.get("data-opaque") is not None or el.get("bs-opaque") is not None:  # needless-bool
+        if el.get("data-opaque") is not None or el.get("bs-opaque") is not None:  # noqa: SIM103
             return True
         return False
 

bikeshed/boilerplate.py

@@ -11,7 +11,7 @@
 from . import conditional, config, dfnpanels, h, retrieve, t
 from . import messages as m
 from . import refs as r
-from .translate import _
+from .translate import _t
 
 if t.TYPE_CHECKING:
     MetadataT: t.TypeAlias = t.Mapping[str, t.Sequence[MetadataValueT]]
@@ -267,7 +267,7 @@ def addIndexSection(doc: t.SpecT) -> None:
     container = getFillContainer("index", doc=doc, default=True)
     if container is None:
         return
-    h.appendChild(container, h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "index")}, _("Index")))
+    h.appendChild(container, h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "index")}, _t("Index")))
 
     if hasLocalDfns:
         addIndexOfLocallyDefinedTerms(doc, container)
@@ -281,7 +281,7 @@ def addIndexOfLocallyDefinedTerms(doc: t.SpecT, container: t.ElementT) -> None:
         container,
         h.E.h3(
             {"class": "no-num no-ref", "id": h.safeID(doc, "index-defined-here")},
-            _("Terms defined by this specification"),
+            _t("Terms defined by this specification"),
         ),
     )
 
@@ -292,17 +292,17 @@ def addIndexOfLocallyDefinedTerms(doc: t.SpecT, container: t.ElementT) -> None:
         if dfnID is None or dfnType is None:
             continue
         linkTexts = h.linkTextsFromElement(el)
-        headingLevel = h.headingLevelOfElement(el) or _("Unnumbered section")
+        headingLevel = h.headingLevelOfElement(el) or _t("Unnumbered section")
         if dfnType == "argument":
             # Don't generate index entries for arguments.
             continue
         if el.get("data-dfn-for") is not None:
-            disamb = _("{type} for {forVals}").format(
+            disamb = _t("{type} for {forVals}").format(
                 type=dfnType,
                 forVals=", ".join(config.splitForValues(el.get("data-dfn-for", ""))),
             )
         elif dfnType == "dfn":
-            disamb = _("definition of")
+            disamb = _t("definition of")
         else:
             disamb = "({})".format(dfnType)
 
@@ -324,9 +324,9 @@ def disambiguator(ref: r.RefWrapper, types: set[str] | None, specs: list[str] |
     if types is None or len(types) > 1:
         disambInfo.append(ref.type)
     if specs is None or len(specs) > 1:
-        disambInfo.append(_("in {spec}").format(spec=ref.spec))
+        disambInfo.append(_t("in {spec}").format(spec=ref.spec))
     if ref.for_:
-        disambInfo.append(_("for {forVals}").format(forVals=", ".join(x.strip() for x in ref.for_)))
+        disambInfo.append(_t("for {forVals}").format(forVals=", ".join(x.strip() for x in ref.for_)))
     return ", ".join(disambInfo)
 
 
@@ -481,7 +481,7 @@ def entryKey(x: tuple[str, t.Any]) -> tuple[str, str, str]:
                 topList,
                 h.E.li(
                     h.E.a({"href": item.url}, text),
-                    h.E.span(_(", in "), item.label) if item.label else "",
+                    h.E.span(_t(", in "), item.label) if item.label else "",
                 ),
             )
         else:
@@ -492,7 +492,7 @@ def entryKey(x: tuple[str, t.Any]) -> tuple[str, str, str]:
                     ul,
                     h.E.li(
                         h.E.a({"href": item.url}, item.disambiguator),
-                        h.E.span(_(", in "), item.label) if item.label else "",
+                        h.E.span(_t(", in "), item.label) if item.label else "",
                     ),
                 )
     return topList
@@ -531,25 +531,25 @@ def makeEntry(ref: t.RefWrapper, contents: t.NodesT) -> t.ElementT:
             h.E.li(h.E.a(attrs, "[", formatBiblioTerm(printableSpec), "]"), " defines the following terms:"),
         )
         termsUl = h.appendChild(specLi, h.E.ul())
-        for refText, refGroup in specData.sorted():
+        for _, refGroup in specData.sorted():
             if len(refGroup) == 1:
                 ref = refGroup.single()
-                entry = makeEntry(ref, refText)
+                entry = makeEntry(ref, ref.displayText)
                 h.appendChild(termsUl, h.E.li(entry))
                 dfnpanels.addExternalDfnPanel(entry, ref, doc)
             else:
                 for forVal, ref in refGroup.sorted():
                     if forVal:
-                        entry = makeEntry(ref, [refText, " ", h.E.small({}, f"({_('for')} {forVal})")])
+                        entry = makeEntry(ref, [ref.displayText, " ", h.E.small({}, f"({_t('for')} {forVal})")])
                     else:
-                        entry = makeEntry(ref, refText)
+                        entry = makeEntry(ref, ref.displayText)
                     h.appendChild(termsUl, h.E.li(entry))
                     dfnpanels.addExternalDfnPanel(entry, ref, doc)
     h.appendChild(
         container,
         h.E.h3(
             {"class": "no-num no-ref", "id": h.safeID(doc, "index-defined-elsewhere")},
-            _(
+            _t(
                 "Terms defined by reference",
             ),
         ),
@@ -570,7 +570,7 @@ def addPropertyIndex(doc: t.SpecT) -> None:
         html,
         h.E.h2(
             {"class": "no-num no-ref", "id": h.safeID(doc, "property-index")},
-            _("Property Index"),
+            _t("Property Index"),
         ),
     )
 
@@ -723,7 +723,7 @@ def addIDLSection(doc: t.SpecT) -> None:
 
     h.appendChild(
         html,
-        h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "idl-index")}, _("IDL Index")),
+        h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "idl-index")}, _t("IDL Index")),
     )
 
     container = h.appendChild(html, h.E.pre({"class": "idl"}))
@@ -749,7 +749,7 @@ def addTOCSection(doc: t.SpecT) -> None:
         toc,
         h.E.h2(
             {"class": "no-num no-toc no-ref", "id": h.safeID(doc, "contents")},
-            _("Table of Contents"),
+            _t("Table of Contents"),
         ),
     )
 
@@ -1053,12 +1053,12 @@ def createMdEntry(key: str, dirtyVals: t.Sequence[MetadataValueT], doc: t.SpecT)
     }
     if len(vals) > 1 and displayKey in pluralization:
         displayKey = pluralization[displayKey]
-    displayKey = _(displayKey)
+    displayKey = _t(displayKey)
     # Handle some custom <dt> structures
     if key in ("Editor", "Former Editor"):
         ret = [h.E.dt({"class": "editor"}, displayKey, ":")]
     elif key == "Translations":
-        ret = [h.E.dt(displayKey, " ", h.E.small(_("(non-normative)")), ":")]
+        ret = [h.E.dt(displayKey, " ", h.E.small(_t("(non-normative)")), ":")]
     else:
         ret = [h.E.dt(displayKey, ":")]
     # Add all the values, wrapping in a <dd> if necessary.
@@ -1113,7 +1113,7 @@ def addReferencesSection(doc: t.SpecT) -> None:
 
     h.appendChild(
         container,
-        h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "references")}, _("References")),
+        h.E.h2({"class": "no-num no-ref", "id": h.safeID(doc, "references")}, _t("References")),
     )
 
     normRefs = sorted(doc.normativeRefs.values(), key=lambda r: r.linkText.lower())
@@ -1123,7 +1123,7 @@ def addReferencesSection(doc: t.SpecT) -> None:
             container,
             h.E.h3(
                 {"class": "no-num no-ref", "id": h.safeID(doc, "normative")},
-                _("Normative References"),
+                _t("Normative References"),
             ),
             h.E.dl(),
         )
@@ -1148,7 +1148,7 @@ def addReferencesSection(doc: t.SpecT) -> None:
             container,
             h.E.h3(
                 {"class": "no-num no-ref", "id": h.safeID(doc, "informative")},
-                _("Informative References"),
+                _t("Informative References"),
             ),
             h.E.dl(),
         )
@@ -1176,7 +1176,7 @@ def addIssuesSection(doc: t.SpecT) -> None:
         container,
         h.E.h2(
             {"class": "no-num no-ref", "id": h.safeID(doc, "issues-index")},
-            _("Issues Index"),
+            _t("Issues Index"),
         ),
     )
     container = h.appendChild(container, h.E.div({"style": "counter-reset:issue"}))
@@ -1189,7 +1189,7 @@ def addIssuesSection(doc: t.SpecT) -> None:
         h.appendChild(
             el,
             " ",
-            h.E.a({"href": "#" + issue.get("id", ""), "class": "issue-return", "title": _("Jump to section")}, "↵"),
+            h.E.a({"href": "#" + issue.get("id", ""), "class": "issue-return", "title": _t("Jump to section")}, "↵"),
         )
     for idel in h.findAll("[id]", container):
         del idel.attrib["id"]

bikeshed/caniuse/caniuse.py

@@ -6,7 +6,7 @@
 
 from .. import h, t
 from .. import messages as m
-from ..translate import _
+from ..translate import _t
 
 
 def addCanIUsePanels(doc: t.SpecT) -> list[t.ElementT]:
@@ -65,7 +65,7 @@ def canIUsePanelFor(id: str, data: t.JSONT, update: str, classFromBrowser: dict[
         {"class": "caniuse-status unpositioned", "data-deco": ""},
         h.E.summary({}, "CanIUse"),
     )
-    mainPara = h.E.p({"class": "support"}, h.E.b({}, _("Support:")))
+    mainPara = h.E.p({"class": "support"}, h.E.b({}, _t("Support:")))
     h.appendChild(panel, mainPara)
     for browser, support in data["support"].items():
         statusCode = support[0]
@@ -80,9 +80,9 @@ def canIUsePanelFor(id: str, data: t.JSONT, update: str, classFromBrowser: dict[
         panel,
         h.E.p(
             {"class": "caniuse"},
-            _("Source: "),
+            _t("Source: "),
             h.E.a({"href": "https://caniuse.com/#feat=" + id}, "caniuse.com"),
-            _(" as of {date}").format(date=update),
+            _t(" as of {date}").format(date=update),
         ),
     )
     return panel
@@ -105,7 +105,7 @@ def browserCompatSpan(
     statusClass = {"y": "yes", "n": "no", "a": "partial"}[statusCode]
     outer = h.E.span({"class": browserCodeName + " " + statusClass})
     if statusCode == "a":
-        h.appendChild(outer, h.E.span({}, h.E.span({}, browserFullName, _(" (limited)"))))
+        h.appendChild(outer, h.E.span({}, h.E.span({}, browserFullName, _t(" (limited)"))))
     else:
         h.appendChild(outer, h.E.span({}, browserFullName))
     h.appendChild(outer, h.E.span({}, minVersion))

bikeshed/cli.py

@@ -83,10 +83,8 @@ def main() -> None:
     )
     argparser.add_argument(
         "--no-update",
-        dest="updateMode",
-        default=update.UpdateMode.MANIFEST,
-        action="store_const",
-        const=update.UpdateMode.NONE,
+        dest="skipUpdate",
+        action="store_true",
         help="Skips checking if your data files are up-to-date.",
     )
     argparser.add_argument(
@@ -456,7 +454,8 @@ def main() -> None:
     constants.executeCode = options.allowExecute
 
     if options.subparserName in ("spec", "echnida", "watch", "serve", "refs"):
-        update.fixupDataFiles(updateMode=options.updateMode)
+        updateMode = update.UpdateMode.NONE if options.skipUpdate else update.UpdateMode.BOTH
+        update.fixupDataFiles(updateMode=updateMode)
     if options.subparserName == "update":
         handleUpdate(options)
     elif options.subparserName == "spec":
@@ -693,12 +692,12 @@ def handleProfile(options: argparse.Namespace) -> None:
     root = f'--root="{options.root}"' if options.root else ""
     leaf = f'--leaf="{options.leaf}"' if options.leaf else ""
     if options.svgFile:
-        os.system(
-            f"time python -m cProfile -o stat.prof -m bikeshed -f spec && gprof2dot -f pstats --skew=.0001 {root} {leaf} stat.prof | dot -Tsvg -o {options.svgFile} && rm stat.prof",  # noqa: S605
+        os.system(  # noqa: S605
+            f"time python -m cProfile -o stat.prof -m bikeshed -f spec && gprof2dot -f pstats --skew=.0001 {root} {leaf} stat.prof | dot -Tsvg -o {options.svgFile} && rm stat.prof",
         )
     else:
-        os.system(
-            f"time python -m cProfile -o /tmp/stat.prof -m bikeshed -f spec && gprof2dot -f pstats --skew=.0001 {root} {leaf} /tmp/stat.prof | xdot &",  # noqa: S605
+        os.system(  # noqa: S605
+            f"time python -m cProfile -o /tmp/stat.prof -m bikeshed -f spec && gprof2dot -f pstats --skew=.0001 {root} {leaf} /tmp/stat.prof | xdot &",
         )
 
 

bikeshed/config/__init__.py

@@ -1,5 +1,6 @@
 from .BoolSet import BoolSet
 from .dfnTypes import (
+    adjustKey,
     anchorishElements,
     cssTypes,
     dfnClassToType,

bikeshed/config/dfnTypes.py

@@ -133,6 +133,36 @@
 )
 
 
+def adjustKey(text: str, type: str) -> tuple[str, str]:
+    # For some types, upper/lowercase is just display, not semantic
+    if type not in lowercaseTypes:
+        return text, text
+    # For those, use lowercased version for link-resolving...
+    key = text.lower()
+    # ...and heuristically decide if the original casing should be preserved or not.
+    # 1. If it's already lowercase, great.
+    # 2. If it's got uppercase letters anywhere but the very first letter, keep the casing.
+    # 3. If it looks non-trivial, keep the casing.
+    # This hopefully removes casing from dfns that just start a sentence,
+    # without removing it from many dfns that need it.
+    # At some point we'll probably add an override for when this is wrong.
+    if re.match(r"[A-Z][^A-Z]+$", text):
+        # only one uppercase letter, right at the beginning.
+        # check if it's "non-trivial"; aka contains something other than
+        # letters, dashes, or whitespace
+        if re.search(r"[^\w\s-]", text):
+            # looks non-trivial, leave it alone
+            displayKey = text
+        else:
+            displayKey = text.lower()
+    else:
+        # Has either 0 or 2+ uppercase letters,
+        # or 1 uppercase in a non-initial position;
+        # leave it alone.
+        displayKey = text
+    return key, displayKey
+
+
 linkTypeToDfnType = {
     "propdesc": frozenset(["property", "descriptor"]),
     "functionish": functionishTypes,

bikeshed/datablocks.py

@@ -727,13 +727,18 @@ def processAnchors(anchors: InfoTreeT, doc: t.SpecT, lineNum: int | None = None)
                 continue
         else:
             status = "anchor-block"
-        if anchor["type"][0] in config.lowercaseTypes:
-            anchor["text"][0] = anchor["text"][0].lower()
-        doc.refs.anchorBlockRefs.refs[anchor["text"][0]].append(
+        aType = anchor["type"][0].lower()
+        displayText = anchor["text"][0]
+        if aType in config.lowercaseTypes:
+            aText = displayText.lower()
+        else:
+            aText = displayText
+        doc.refs.anchorBlockRefs.refs[aText].append(
             refs.RefWrapper(
-                anchor["text"][0],
+                aText,
+                displayText,
                 {
-                    "type": anchor["type"][0].lower(),
+                    "type": aType,
                     "url": url,
                     "shortname": shortname.lower() if shortname is not None else doc.md.shortname,
                     "level": level if level is not None else doc.md.level,

bikeshed/dfnpanels/dfnpanels.py

@@ -4,7 +4,7 @@
 
 from .. import h, t
 from .. import messages as m
-from ..translate import _
+from ..translate import _t
 
 
 def addDfnPanels(doc: t.SpecT, dfns: list[t.ElementT]) -> None:
@@ -77,7 +77,7 @@ def addExternalDfnPanel(termEl: t.ElementT, ref: t.RefWrapper, doc: t.SpecT) ->
     # Group the relevant links according to the section they're in.
     refsFromSection: OrderedDict[str, list[t.ElementT]] = OrderedDict()
     for link in doc.cachedLinksFromHref[ref.url]:
-        section = h.sectionName(doc, link) or _("Unnumbered Section")
+        section = h.sectionName(doc, link) or _t("Unnumbered Section")
         refsFromSection.setdefault(section, []).append(link)
 
     h.addClass(doc, termEl, "dfn-paneled")

bikeshed/doctypes/manager.py

@@ -166,7 +166,7 @@ def looselyMatch(self, rawStatus: str) -> bool:
         orgName, statusName = utils.splitOrg(rawStatus)
         if statusName and self.name.upper() != statusName.upper():
             return False
-        if orgName and self.org.name != orgName.upper():  # needless-bool
+        if orgName and self.org.name != orgName.upper():  # noqa: SIM103
             return False
         return True