Rename --format-regex and update docs

Docs cover the expected usage, which is not implemented in this
initial change. The rename and alias is all that's covered here.

Author: sirosen

CHANGELOG.rst

@@ -9,6 +9,9 @@ Unreleased
 ----------
 
 .. vendor-insert-here
+- Rename ``--format-regex`` to ``--regex-variant`` and convert
+  ``--format-regex`` to a deprecated alias.
+  It will be removed in a future release.
 
 - Update vendored schemas (2024-12-22)
 - Drop support for Python 3.8

docs/usage.rst

@@ -183,11 +183,11 @@ Example usage:
     # disables all three of time, date-time, and iri
     --disable-formats time,date-time --disable-formats iri
 
-``--format-regex``
+``--regex-variant``
 ~~~~~~~~~~~~~~~~~~
 
-Set a mode for handling of the ``"regex"`` value for ``"format"``. The modes are as
-follows:
+Set a mode for handling of the ``"regex"`` value for ``"format"`` and the mode
+for ``"pattern"`` interpretation. The modes are as follows:
 
 .. list-table:: Regex Options
    :widths: 15 30
@@ -196,9 +196,15 @@ follows:
    * - mode
      - description
    * - default
-     - Require the regex to be valid in ECMAScript regex syntax.
+     - Use ECMAScript regex syntax.
    * - python
-     - Require the regex to be valid in Python regex syntax.
+     - Use Python regex syntax.
+
+.. note::
+
+    This only controls the regex mode used for ``format`` and ``pattern``.
+    ``patternProperties`` is not currently controlled, and always uses the
+    Python engine.
 
 Other Options
 --------------

src/check_jsonschema/checker.py

@@ -28,7 +28,7 @@ def __init__(
         instance_loader: InstanceLoader,
         reporter: Reporter,
         *,
-        format_opts: FormatOptions | None = None,
+        format_opts: FormatOptions,
         traceback_mode: str = "short",
         fill_defaults: bool = False,
     ) -> None:

src/check_jsonschema/cli/main_command.py

@@ -68,10 +68,10 @@ def pretty_helptext_list(values: list[str] | tuple[str, ...]) -> str:
     date, date-time, email, ipv4, ipv6, regex, uuid
 
 \b
-For the "regex" format, there are multiple modes which can be specified with
-'--format-regex':
-    default  |  check that the string is a valid ECMAScript regex
-    python   |  check that the string is a valid python regex
+For handling of regexes, there are multiple modes which can be specified with
+'--regex-variant':
+    default  |  use ECMAScript regex syntax (via regress)
+    python   |  use python regex syntax
 
 \b
 The '--builtin-schema' flag supports the following schema names:
@@ -138,11 +138,18 @@ def pretty_helptext_list(values: list[str] | tuple[str, ...]) -> str:
 )
 @click.option(
     "--format-regex",
+    hidden=True,
+    help="Legacy name for `--regex-variant`.",
+    default=None,
+    type=click.Choice([x.value for x in RegexVariantName], case_sensitive=False),
+)
+@click.option(
+    "--regex-variant",
     help=(
-        "Set the mode of format validation for regexes. "
-        "If `--disable-formats regex` is used, this option has no effect."
+        "Name of which regex dialect should be used for format checking "
+        "and 'pattern' matching."
     ),
-    default=RegexVariantName.default.value,
+    default=None,
     type=click.Choice([x.value for x in RegexVariantName], case_sensitive=False),
 )
 @click.option(
@@ -230,7 +237,8 @@ def main(
     no_cache: bool,
     cache_filename: str | None,
     disable_formats: tuple[list[str], ...],
-    format_regex: t.Literal["python", "default"],
+    format_regex: t.Literal["python", "default"] | None,
+    regex_variant: t.Literal["python", "default"] | None,
     default_filetype: t.Literal["json", "yaml", "toml", "json5"],
     traceback_mode: t.Literal["full", "short"],
     data_transform: t.Literal["azure-pipelines", "gitlab-ci"] | None,
@@ -243,6 +251,8 @@ def main(
 ) -> None:
     args = ParseResult()
 
+    args.set_regex_variant(regex_variant, legacy_opt=format_regex)
+
     args.set_schema(schemafile, builtin_schema, check_metaschema)
     args.set_validator(validator_class)
 
@@ -257,7 +267,6 @@ def main(
     else:
         args.disable_formats = normalized_disable_formats
 
-    args.format_regex = RegexVariantName(format_regex)
     args.disable_cache = no_cache
     args.default_filetype = default_filetype
     args.fill_defaults = fill_defaults

src/check_jsonschema/cli/parse_result.py

@@ -1,14 +1,21 @@
 from __future__ import annotations
 
 import enum
+import sys
 import typing as t
 
 import click
 import jsonschema
 
-from ..formats import FormatOptions, RegexVariantName
+from ..formats import FormatOptions
+from ..regex_variants import RegexVariantName
 from ..transforms import Transform
 
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
 
 class SchemaLoadingMode(enum.Enum):
     filepath = "filepath"
@@ -36,12 +43,22 @@ def __init__(self) -> None:
         # regex format options
         self.disable_all_formats: bool = False
         self.disable_formats: tuple[str, ...] = ()
-        self.format_regex: RegexVariantName = RegexVariantName.default
+        self.regex_variant: RegexVariantName = RegexVariantName.default
         # error and output controls
         self.verbosity: int = 1
         self.traceback_mode: str = "short"
         self.output_format: str = "text"
 
+    def set_regex_variant(
+        self,
+        variant_opt: Literal["python", "default"] | None,
+        *,
+        legacy_opt: Literal["python", "default"] | None = None,
+    ) -> None:
+        variant_name: Literal["python", "default"] | None = variant_opt or legacy_opt
+        if variant_name:
+            self.regex_variant = RegexVariantName(variant_name)
+
     def set_schema(
         self, schemafile: str | None, builtin_schema: str | None, check_metaschema: bool
     ) -> None:
@@ -83,6 +100,6 @@ def set_validator(
     def format_opts(self) -> FormatOptions:
         return FormatOptions(
             enabled=not self.disable_all_formats,
-            regex_variant=self.format_regex,
+            regex_variant=self.regex_variant,
             disabled_formats=self.disable_formats,
         )

src/check_jsonschema/formats/__init__.py

@@ -1,14 +1,11 @@
 from __future__ import annotations
 
 import copy
-import enum
-import re
-import typing as t
 
 import jsonschema
 import jsonschema.validators
-import regress
 
+from ..regex_variants import RegexImplementation, RegexVariantName
 from .implementations import validate_rfc3339, validate_time
 
 # all known format strings except for a selection from draft3 which have either
@@ -39,32 +36,6 @@
 )
 
 
-class RegexVariantName(enum.Enum):
-    default = "default"
-    python = "python"
-
-
-class RegexImplementation:
-    def __init__(self, variant: RegexVariantName) -> None:
-        self.variant = variant
-
-    def check_format(self, instance: t.Any) -> bool:
-        if not isinstance(instance, str):
-            return True
-
-        try:
-            if self.variant == RegexVariantName.default:
-                regress.Regex(instance)
-            else:
-                re.compile(instance)
-        # something is wrong with RegressError getting into the published types
-        # needs investigation... for now, ignore the error
-        except (regress.RegressError, re.error):  # type: ignore[attr-defined]
-            return False
-
-        return True
-
-
 class FormatOptions:
     def __init__(
         self,

src/check_jsonschema/regex_variants.py

@@ -0,0 +1,31 @@
+import enum
+import re
+import typing as t
+
+import regress
+
+
+class RegexVariantName(enum.Enum):
+    default = "default"
+    python = "python"
+
+
+class RegexImplementation:
+    def __init__(self, variant: RegexVariantName) -> None:
+        self.variant = variant
+
+    def check_format(self, instance: t.Any) -> bool:
+        if not isinstance(instance, str):
+            return True
+
+        try:
+            if self.variant == RegexVariantName.default:
+                regress.Regex(instance)
+            else:
+                re.compile(instance)
+        # something is wrong with RegressError getting into the published types
+        # needs investigation... for now, ignore the error
+        except (regress.RegressError, re.error):  # type: ignore[attr-defined]
+            return False
+
+        return True