prefect-client 3.1.9__py3-none-any.whl → 3.1.11__py3-none-any.whl

prefect/_internal/schemas/validators.py

@@ -6,41 +6,51 @@ format.
 This will be subject to consolidation and refactoring over the next few months.
 """
 
-import json
+import os
 import re
 import urllib.parse
 import warnings
+from collections.abc import Iterable, Mapping, MutableMapping
 from copy import copy
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Dict, List, Mapping, Optional, Tuple, Union
+from typing import TYPE_CHECKING, Any, Optional, TypeVar, Union, overload
 from uuid import UUID
 
 import jsonschema
 import pendulum
-import yaml
+import pendulum.tz
 
-from prefect.exceptions import InvalidRepositoryURLError
-from prefect.types import DateTime
 from prefect.utilities.collections import isiterable
-from prefect.utilities.dockerutils import get_prefect_image_name
 from prefect.utilities.filesystem import relative_path_to_current_platform
 from prefect.utilities.importtools import from_qualified_name
 from prefect.utilities.names import generate_slug
-from prefect.utilities.pydantic import JsonPatch
+
+if TYPE_CHECKING:
+    from prefect.serializers import Serializer
+
+T = TypeVar("T")
+M = TypeVar("M", bound=Mapping[str, Any])
+MM = TypeVar("MM", bound=MutableMapping[str, Any])
+
 
 LOWERCASE_LETTERS_NUMBERS_AND_DASHES_ONLY_REGEX = "^[a-z0-9-]*$"
 LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX = "^[a-z0-9_]*$"
 
-if TYPE_CHECKING:
-    from prefect.blocks.core import Block
-    from prefect.serializers import Serializer
-    from prefect.utilities.callables import ParameterSchema
+
+@overload
+def raise_on_name_alphanumeric_dashes_only(value: str, field_name: str = ...) -> str:
+    ...
+
+
+@overload
+def raise_on_name_alphanumeric_dashes_only(value: None, field_name: str = ...) -> None:
+    ...
 
 
 def raise_on_name_alphanumeric_dashes_only(
     value: Optional[str], field_name: str = "value"
-):
-    if value and not bool(
+) -> Optional[str]:
+    if value is not None and not bool(
         re.match(LOWERCASE_LETTERS_NUMBERS_AND_DASHES_ONLY_REGEX, value)
     ):
         raise ValueError(
@@ -49,40 +59,38 @@ def raise_on_name_alphanumeric_dashes_only(
     return value
 
 
-def raise_on_name_alphanumeric_underscores_only(value, field_name: str = "value"):
-    if not bool(re.match(LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX, value)):
-        raise ValueError(
-            f"{field_name} must only contain lowercase letters, numbers, and"
-            " underscores."
-        )
-    return value
+@overload
+def raise_on_name_alphanumeric_underscores_only(
+    value: str, field_name: str = ...
+) -> str:
+    ...
 
 
-def validate_schema(schema: dict):
-    """
-    Validate that the provided schema is a valid json schema.
+@overload
+def raise_on_name_alphanumeric_underscores_only(
+    value: None, field_name: str = ...
+) -> None:
+    ...
 
-    Args:
-        schema: The schema to validate.
 
-    Raises:
-        ValueError: If the provided schema is not a valid json schema.
-
-    """
-    try:
-        if schema is not None:
-            # Most closely matches the schemas generated by pydantic
-            jsonschema.Draft202012Validator.check_schema(schema)
-    except jsonschema.SchemaError as exc:
+def raise_on_name_alphanumeric_underscores_only(
+    value: Optional[str], field_name: str = "value"
+) -> Optional[str]:
+    if value is not None and not re.match(
+        LOWERCASE_LETTERS_NUMBERS_AND_UNDERSCORES_REGEX, value
+    ):
         raise ValueError(
-            "The provided schema is not a valid json schema. Schema error:"
-            f" {exc.message}"
-        ) from exc
+            f"{field_name} must only contain lowercase letters, numbers, and"
+            " underscores."
+        )
+    return value
 
 
 def validate_values_conform_to_schema(
-    values: dict, schema: dict, ignore_required: bool = False
-):
+    values: Optional[Mapping[str, Any]],
+    schema: Optional[Mapping[str, Any]],
+    ignore_required: bool = False,
+) -> None:
     """
     Validate that the provided values conform to the provided json schema.
 
@@ -127,90 +135,46 @@ def validate_values_conform_to_schema(
 ### DEPLOYMENT SCHEMA VALIDATORS ###
 
 
-def infrastructure_must_have_capabilities(
-    value: Union[Dict[str, Any], "Block", None],
-) -> Optional["Block"]:
-    """
-    Ensure that the provided value is an infrastructure block with the required capabilities.
-    """
-
-    from prefect.blocks.core import Block
-
-    if isinstance(value, dict):
-        if "_block_type_slug" in value:
-            # Replace private attribute with public for dispatch
-            value["block_type_slug"] = value.pop("_block_type_slug")
-        block = Block(**value)
-    elif value is None:
-        return value
-    else:
-        block = value
-
-    if "run-infrastructure" not in block.get_block_capabilities():
-        raise ValueError(
-            "Infrastructure block must have 'run-infrastructure' capabilities."
+def validate_parameters_conform_to_schema(
+    parameters: M, values: Mapping[str, Any]
+) -> M:
+    """Validate that the parameters conform to the parameter schema."""
+    if values.get("enforce_parameter_schema"):
+        validate_values_conform_to_schema(
+            parameters, values.get("parameter_openapi_schema"), ignore_required=True
         )
-    return block
+    return parameters
 
 
-def storage_must_have_capabilities(
-    value: Union[Dict[str, Any], "Block", None],
-) -> Optional["Block"]:
-    """
-    Ensure that the provided value is a storage block with the required capabilities.
-    """
-    from prefect.blocks.core import Block
-
-    if isinstance(value, dict):
-        block_type = Block.get_block_class_from_key(value.pop("_block_type_slug"))
-        block = block_type(**value)
-    elif value is None:
-        return value
-    else:
-        block = value
+@overload
+def validate_parameter_openapi_schema(schema: M, values: Mapping[str, Any]) -> M:
+    ...
 
-    capabilities = block.get_block_capabilities()
-    if "get-directory" not in capabilities:
-        raise ValueError("Remote Storage block must have 'get-directory' capabilities.")
-    return block
 
-
-def handle_openapi_schema(value: Optional["ParameterSchema"]) -> "ParameterSchema":
-    """
-    This method ensures setting a value of `None` is handled gracefully.
-    """
-    from prefect.utilities.callables import ParameterSchema
-
-    if value is None:
-        return ParameterSchema()
-    return value
-
-
-def validate_parameters_conform_to_schema(value: dict, values: dict) -> dict:
-    """Validate that the parameters conform to the parameter schema."""
-    if values.get("enforce_parameter_schema"):
-        validate_values_conform_to_schema(
-            value, values.get("parameter_openapi_schema"), ignore_required=True
-        )
-    return value
+@overload
+def validate_parameter_openapi_schema(schema: None, values: Mapping[str, Any]) -> None:
+    ...
 
 
-def validate_parameter_openapi_schema(value: dict, values: dict) -> dict:
+def validate_parameter_openapi_schema(
+    schema: Optional[M], values: Mapping[str, Any]
+) -> Optional[M]:
     """Validate that the parameter_openapi_schema is a valid json schema."""
     if values.get("enforce_parameter_schema"):
-        validate_schema(value)
-    return value
-
-
-def return_none_schedule(v: Optional[Union[str, dict]]) -> Optional[Union[str, dict]]:
-    from prefect.client.schemas.schedules import NoSchedule
+        try:
+            if schema is not None:
+                # Most closely matches the schemas generated by pydantic
+                jsonschema.Draft202012Validator.check_schema(schema)
+        except jsonschema.SchemaError as exc:
+            raise ValueError(
+                "The provided schema is not a valid json schema. Schema error:"
+                f" {exc.message}"
+            ) from exc
 
-    if isinstance(v, NoSchedule):
-        return None
-    return v
+    return schema
 
 
-def convert_to_strings(value: Union[Any, List[Any]]) -> Union[str, List[str]]:
+def convert_to_strings(value: Union[Any, Iterable[Any]]) -> Union[str, list[str]]:
     if isiterable(value):
         return [str(item) for item in value]
     return str(value)
@@ -219,7 +183,7 @@ def convert_to_strings(value: Union[Any, List[Any]]) -> Union[str, List[str]]:
 ### SCHEDULE SCHEMA VALIDATORS ###
 
 
-def reconcile_schedules_runner(values: dict) -> dict:
+def reconcile_schedules_runner(values: MM) -> MM:
     from prefect.deployments.schedules import (
         normalize_to_deployment_schedule_create,
     )
@@ -231,13 +195,23 @@ def reconcile_schedules_runner(values: dict) -> dict:
     return values
 
 
+@overload
+def validate_schedule_max_scheduled_runs(v: int, limit: int) -> int:
+    ...
+
+
+@overload
+def validate_schedule_max_scheduled_runs(v: None, limit: int) -> None:
+    ...
+
+
 def validate_schedule_max_scheduled_runs(v: Optional[int], limit: int) -> Optional[int]:
     if v is not None and v > limit:
         raise ValueError(f"`max_scheduled_runs` must be less than or equal to {limit}.")
     return v
 
 
-def remove_old_deployment_fields(values: dict) -> dict:
+def remove_old_deployment_fields(values: MM) -> MM:
     # 2.7.7 removed worker_pool_queue_id in lieu of worker_pool_name and
     # worker_pool_queue_name. Those fields were later renamed to work_pool_name
     # and work_queue_name. This validator removes old fields provided
@@ -270,7 +244,7 @@ def remove_old_deployment_fields(values: dict) -> dict:
     return values_copy
 
 
-def reconcile_paused_deployment(values):
+def reconcile_paused_deployment(values: MM) -> MM:
     paused = values.get("paused")
 
     if paused is None:
@@ -279,45 +253,44 @@ def reconcile_paused_deployment(values):
     return values
 
 
-def default_anchor_date(v: DateTime) -> DateTime:
+def default_anchor_date(v: pendulum.DateTime) -> pendulum.DateTime:
     return pendulum.instance(v)
 
 
-def get_valid_timezones(v: Optional[str]) -> Tuple[str, ...]:
-    # pendulum.tz.timezones is a callable in 3.0 and above
-    # https://github.com/PrefectHQ/prefect/issues/11619
-    if callable(pendulum.tz.timezones):
-        return pendulum.tz.timezones()
-    else:
-        return pendulum.tz.timezones
+@overload
+def default_timezone(v: str, values: Optional[Mapping[str, Any]] = ...) -> str:
+    ...
 
 
-def validate_timezone(v: str, timezones: Tuple[str, ...]) -> str:
-    if v and v not in timezones:
-        raise ValueError(
-            f'Invalid timezone: "{v}" (specify in IANA tzdata format, for example,'
-            " America/New_York)"
-        )
-    return v
+@overload
+def default_timezone(
+    v: None, values: Optional[Mapping[str, Any]] = ...
+) -> Optional[str]:
+    ...
 
 
-def default_timezone(v: Optional[str], values: Optional[dict] = None) -> str:
+def default_timezone(
+    v: Optional[str], values: Optional[Mapping[str, Any]] = None
+) -> Optional[str]:
     values = values or {}
-    timezones = get_valid_timezones(v)
+    timezones = pendulum.tz.timezones()
 
     if v is not None:
-        return validate_timezone(v, timezones)
+        if v and v not in timezones:
+            raise ValueError(
+                f'Invalid timezone: "{v}" (specify in IANA tzdata format, for example,'
+                " America/New_York)"
+            )
+        return v
 
     # anchor schedules
-    elif v is None and values and values.get("anchor_date"):
-        tz = getattr(values["anchor_date"].tz, "name", None) or "UTC"
-        if tz in timezones:
-            return tz
+    elif "anchor_date" in values:
+        anchor_date: pendulum.DateTime = values["anchor_date"]
+        tz = "UTC" if anchor_date.tz is None else anchor_date.tz.name
         # sometimes anchor dates have "timezones" that are UTC offsets
         # like "-04:00". This happens when parsing ISO8601 strings.
         # In this case we, the correct inferred localization is "UTC".
-        else:
-            return "UTC"
+        return tz if tz in timezones else "UTC"
 
     # cron schedules
     return v
@@ -360,119 +333,18 @@ def validate_rrule_string(v: str) -> str:
     return v
 
 
-### INFRASTRUCTURE SCHEMA VALIDATORS ###
-
-
-def validate_k8s_job_required_components(cls, value: Dict[str, Any]):
-    """
-    Validate that a Kubernetes job manifest has all required components.
-    """
-    from prefect.utilities.pydantic import JsonPatch
-
-    patch = JsonPatch.from_diff(value, cls.base_job_manifest())
-    missing_paths = sorted([op["path"] for op in patch if op["op"] == "add"])
-    if missing_paths:
-        raise ValueError(
-            "Job is missing required attributes at the following paths: "
-            f"{', '.join(missing_paths)}"
-        )
-    return value
-
-
-def validate_k8s_job_compatible_values(cls, value: Dict[str, Any]):
-    """
-    Validate that the provided job values are compatible with the job type.
-    """
-    from prefect.utilities.pydantic import JsonPatch
-
-    patch = JsonPatch.from_diff(value, cls.base_job_manifest())
-    incompatible = sorted(
-        [
-            f"{op['path']} must have value {op['value']!r}"
-            for op in patch
-            if op["op"] == "replace"
-        ]
-    )
-    if incompatible:
-        raise ValueError(
-            "Job has incompatible values for the following attributes: "
-            f"{', '.join(incompatible)}"
-        )
-    return value
-
-
-def cast_k8s_job_customizations(
-    cls, value: Union[JsonPatch, str, List[Dict[str, Any]]]
-):
-    if isinstance(value, list):
-        return JsonPatch(value)
-    elif isinstance(value, str):
-        try:
-            return JsonPatch(json.loads(value))
-        except json.JSONDecodeError as exc:
-            raise ValueError(
-                f"Unable to parse customizations as JSON: {value}. Please make sure"
-                " that the provided value is a valid JSON string."
-            ) from exc
-    return value
-
-
-def set_default_namespace(values: dict) -> dict:
-    """
-    Set the default namespace for a Kubernetes job if not provided.
-    """
-    job = values.get("job")
-
-    namespace = values.get("namespace")
-    job_namespace = job["metadata"].get("namespace") if job else None
-
-    if not namespace and not job_namespace:
-        values["namespace"] = "default"
-
-    return values
-
-
-def set_default_image(values: dict) -> dict:
-    """
-    Set the default image for a Kubernetes job if not provided.
-    """
-
-    job = values.get("job")
-    image = values.get("image")
-    job_image = (
-        job["spec"]["template"]["spec"]["containers"][0].get("image") if job else None
-    )
-
-    if not image and not job_image:
-        values["image"] = get_prefect_image_name()
-
-    return values
-
-
 ### STATE SCHEMA VALIDATORS ###
 
 
-def get_or_create_state_name(v: str, values: dict) -> str:
-    """If a name is not provided, use the type"""
-
-    # if `type` is not in `values` it means the `type` didn't pass its own
-    # validation check and an error will be raised after this function is called
-    if v is None and values.get("type"):
-        v = " ".join([v.capitalize() for v in values.get("type").value.split("_")])
-    return v
-
-
-def get_or_create_run_name(name):
+def get_or_create_run_name(name: Optional[str]) -> str:
     return name or generate_slug(2)
 
 
 ### FILESYSTEM SCHEMA VALIDATORS ###
 
 
-def stringify_path(value: Union[str, Path]) -> str:
-    if isinstance(value, Path):
-        return str(value)
-    return value
+def stringify_path(value: Union[str, os.PathLike[str]]) -> str:
+    return os.fspath(value)
 
 
 def validate_basepath(value: str) -> str:
@@ -495,25 +367,6 @@ def validate_basepath(value: str) -> str:
     return value
 
 
-def validate_github_access_token(v: str, values: dict) -> str:
-    """Ensure that credentials are not provided with 'SSH' formatted GitHub URLs.
-
-    Note: validates `access_token` specifically so that it only fires when
-    private repositories are used.
-    """
-    if v is not None:
-        if urllib.parse.urlparse(values["repository"]).scheme != "https":
-            raise InvalidRepositoryURLError(
-                "Crendentials can only be used with GitHub repositories "
-                "using the 'HTTPS' format. You must either remove the "
-                "credential if you wish to use the 'SSH' format and are not "
-                "using a private repository, or you must change the repository "
-                "URL to the 'HTTPS' format. "
-            )
-
-    return v
-
-
 ### SERIALIZER SCHEMA VALIDATORS ###
 
 
@@ -537,49 +390,7 @@ def validate_picklelib(value: str) -> str:
     return value
 
 
-def validate_picklelib_version(values: dict) -> dict:
-    """
-    Infers a default value for `picklelib_version` if null or ensures it matches
-    the version retrieved from the `pickelib`.
-    """
-    picklelib = values.get("picklelib")
-    picklelib_version = values.get("picklelib_version")
-
-    if not picklelib:
-        raise ValueError("Unable to check version of unrecognized picklelib module")
-
-    pickler = from_qualified_name(picklelib)
-    pickler_version = getattr(pickler, "__version__", None)
-
-    if not picklelib_version:
-        values["picklelib_version"] = pickler_version
-    elif picklelib_version != pickler_version:
-        warnings.warn(
-            (
-                f"Mismatched {picklelib!r} versions. Found {pickler_version} in the"
-                f" environment but {picklelib_version} was requested. This may"
-                " cause the serializer to fail."
-            ),
-            RuntimeWarning,
-            stacklevel=3,
-        )
-
-    return values
-
-
-def validate_picklelib_and_modules(values: dict) -> dict:
-    """
-    Prevents modules from being specified if picklelib is not cloudpickle
-    """
-    if values.get("picklelib") != "cloudpickle" and values.get("pickle_modules"):
-        raise ValueError(
-            "`pickle_modules` cannot be used without 'cloudpickle'. Got"
-            f" {values.get('picklelib')!r}."
-        )
-    return values
-
-
-def validate_dump_kwargs(value: dict[str, Any]) -> dict[str, Any]:
+def validate_dump_kwargs(value: M) -> M:
     # `default` is set by `object_encoder`. A user provided callable would make this
     # class unserializable anyway.
     if "default" in value:
@@ -587,7 +398,7 @@ def validate_dump_kwargs(value: dict[str, Any]) -> dict[str, Any]:
     return value
 
 
-def validate_load_kwargs(value: dict[str, Any]) -> dict[str, Any]:
+def validate_load_kwargs(value: M) -> M:
     # `object_hook` is set by `object_decoder`. A user provided callable would make
     # this class unserializable anyway.
     if "object_hook" in value:
@@ -597,7 +408,19 @@ def validate_load_kwargs(value: dict[str, Any]) -> dict[str, Any]:
     return value
 
 
-def cast_type_names_to_serializers(value: Union[str, "Serializer"]) -> "Serializer":
+@overload
+def cast_type_names_to_serializers(value: str) -> "Serializer[Any]":
+    ...
+
+
+@overload
+def cast_type_names_to_serializers(value: "Serializer[T]") -> "Serializer[T]":
+    ...
+
+
+def cast_type_names_to_serializers(
+    value: Union[str, "Serializer[Any]"],
+) -> "Serializer[Any]":
     from prefect.serializers import Serializer
 
     if isinstance(value, str):
@@ -631,19 +454,49 @@ def validate_compressionlib(value: str) -> str:
 
 
 # TODO: if we use this elsewhere we can change the error message to be more generic
-def list_length_50_or_less(v: Optional[List[float]]) -> Optional[List[float]]:
+@overload
+def list_length_50_or_less(v: list[float]) -> list[float]:
+    ...
+
+
+@overload
+def list_length_50_or_less(v: None) -> None:
+    ...
+
+
+def list_length_50_or_less(v: Optional[list[float]]) -> Optional[list[float]]:
     if isinstance(v, list) and (len(v) > 50):
         raise ValueError("Can not configure more than 50 retry delays per task.")
     return v
 
 
 # TODO: if we use this elsewhere we can change the error message to be more generic
+@overload
+def validate_not_negative(v: float) -> float:
+    ...
+
+
+@overload
+def validate_not_negative(v: None) -> None:
+    ...
+
+
 def validate_not_negative(v: Optional[float]) -> Optional[float]:
     if v is not None and v < 0:
         raise ValueError("`retry_jitter_factor` must be >= 0.")
     return v
 
 
+@overload
+def validate_message_template_variables(v: str) -> str:
+    ...
+
+
+@overload
+def validate_message_template_variables(v: None) -> None:
+    ...
+
+
 def validate_message_template_variables(v: Optional[str]) -> Optional[str]:
     from prefect.client.schemas.objects import FLOW_RUN_NOTIFICATION_TEMPLATE_KWARGS
 
@@ -665,11 +518,19 @@ def validate_default_queue_id_not_none(v: Optional[UUID]) -> UUID:
     return v
 
 
-def validate_max_metadata_length(
-    v: Optional[Dict[str, Any]],
-) -> Optional[Dict[str, Any]]:
+@overload
+def validate_max_metadata_length(v: MM) -> MM:
+    ...
+
+
+@overload
+def validate_max_metadata_length(v: None) -> None:
+    ...
+
+
+def validate_max_metadata_length(v: Optional[MM]) -> Optional[MM]:
     max_metadata_length = 500
-    if not isinstance(v, dict):
+    if v is None:
         return v
     for key in v.keys():
         if len(str(v[key])) > max_metadata_length:
@@ -677,79 +538,17 @@ def validate_max_metadata_length(
     return v
 
 
-### DOCKER SCHEMA VALIDATORS ###
-
-
-def validate_registry_url(value: Optional[str]) -> Optional[str]:
-    if isinstance(value, str):
-        if "://" not in value:
-            return "https://" + value
-    return value
-
-
-def convert_labels_to_docker_format(labels: Dict[str, str]) -> Dict[str, str]:
-    labels = labels or {}
-    new_labels = {}
-    for name, value in labels.items():
-        if "/" in name:
-            namespace, key = name.split("/", maxsplit=1)
-            new_namespace = ".".join(reversed(namespace.split(".")))
-            new_labels[f"{new_namespace}.{key}"] = value
-        else:
-            new_labels[name] = value
-    return new_labels
-
-
-def check_volume_format(volumes: List[str]) -> List[str]:
-    for volume in volumes:
-        if ":" not in volume:
-            raise ValueError(
-                "Invalid volume specification. "
-                f"Expected format 'path:container_path', but got {volume!r}"
-            )
-
-    return volumes
-
-
-def base_image_xor_dockerfile(values: Mapping[str, Any]):
-    if values.get("base_image") and values.get("dockerfile"):
-        raise ValueError(
-            "Either `base_image` or `dockerfile` should be provided, but not both"
-        )
-    return values
-
-
-### SETTINGS SCHEMA VALIDATORS ###
-
+### TASK RUN SCHEMA VALIDATORS ###
 
-def validate_settings(value: dict) -> dict:
-    from prefect.settings import Setting, Settings
-    from prefect.settings.legacy import _get_settings_fields
 
-    if value is None:
-        return value
+@overload
+def validate_cache_key_length(cache_key: str) -> str:
+    ...
 
-    # Cast string setting names to variables
-    validated = {}
-    for setting, val in value.items():
-        settings_fields = _get_settings_fields(Settings)
-        if isinstance(setting, str) and setting in settings_fields:
-            validated[settings_fields[setting]] = val
-        elif isinstance(setting, Setting):
-            validated[setting] = val
-        else:
-            warnings.warn(f"Setting {setting!r} is not recognized and will be ignored.")
 
-    return validated
-
-
-def validate_yaml(value: Union[str, dict]) -> dict:
-    if isinstance(value, str):
-        return yaml.safe_load(value)
-    return value
-
-
-### TASK RUN SCHEMA VALIDATORS ###
+@overload
+def validate_cache_key_length(cache_key: None) -> None:
+    ...
 
 
 def validate_cache_key_length(cache_key: Optional[str]) -> Optional[str]:
@@ -765,7 +564,7 @@ def validate_cache_key_length(cache_key: Optional[str]) -> Optional[str]:
     return cache_key
 
 
-def set_run_policy_deprecated_fields(values: dict) -> dict:
+def set_run_policy_deprecated_fields(values: MM) -> MM:
     """
     If deprecated fields are provided, populate the corresponding new fields
     to preserve orchestration behavior.
@@ -785,6 +584,16 @@ def set_run_policy_deprecated_fields(values: dict) -> dict:
 ### PYTHON ENVIRONMENT SCHEMA VALIDATORS ###
 
 
+@overload
+def return_v_or_none(v: str) -> str:
+    ...
+
+
+@overload
+def return_v_or_none(v: None) -> None:
+    ...
+
+
 def return_v_or_none(v: Optional[str]) -> Optional[str]:
     """Make sure that empty strings are treated as None"""
     if not v:
@@ -795,7 +604,7 @@ def return_v_or_none(v: Optional[str]) -> Optional[str]:
 ### BLOCK SCHEMA VALIDATORS ###
 
 
-def validate_parent_and_ref_diff(values: dict) -> dict:
+def validate_parent_and_ref_diff(values: M) -> M:
     parent_id = values.get("parent_block_document_id")
     ref_id = values.get("reference_block_document_id")
     if parent_id and ref_id and parent_id == ref_id:
@@ -806,7 +615,7 @@ def validate_parent_and_ref_diff(values: dict) -> dict:
     return values
 
 
-def validate_name_present_on_nonanonymous_blocks(values: dict) -> dict:
+def validate_name_present_on_nonanonymous_blocks(values: M) -> M:
     # anonymous blocks may have no name prior to actually being
     # stored in the database
     if not values.get("is_anonymous") and not values.get("name"):
@@ -817,9 +626,19 @@ def validate_name_present_on_nonanonymous_blocks(values: dict) -> dict:
 ### PROCESS JOB CONFIGURATION VALIDATORS ###
 
 
+@overload
 def validate_command(v: str) -> Path:
+    ...
+
+
+@overload
+def validate_command(v: None) -> None:
+    ...
+
+
+def validate_command(v: Optional[str]) -> Optional[Path]:
     """Make sure that the working directory is formatted for the current platform."""
-    if v:
+    if v is not None:
         return relative_path_to_current_platform(v)
     return v
 
@@ -830,23 +649,43 @@ def validate_command(v: str) -> Path:
 # catch-all for validators until we organize these into files
 
 
-def validate_block_document_name(value):
+@overload
+def validate_block_document_name(value: str) -> str:
+    ...
+
+
+@overload
+def validate_block_document_name(value: None) -> None:
+    ...
+
+
+def validate_block_document_name(value: Optional[str]) -> Optional[str]:
     if value is not None:
         raise_on_name_alphanumeric_dashes_only(value, field_name="Block document name")
     return value
 
 
-def validate_artifact_key(value):
+def validate_artifact_key(value: str) -> str:
     raise_on_name_alphanumeric_dashes_only(value, field_name="Artifact key")
     return value
 
 
-def validate_variable_name(value):
+@overload
+def validate_variable_name(value: str) -> str:
+    ...
+
+
+@overload
+def validate_variable_name(value: None) -> None:
+    ...
+
+
+def validate_variable_name(value: Optional[str]) -> Optional[str]:
     if value is not None:
         raise_on_name_alphanumeric_underscores_only(value, field_name="Variable name")
     return value
 
 
-def validate_block_type_slug(value):
+def validate_block_type_slug(value: str):
     raise_on_name_alphanumeric_dashes_only(value, field_name="Block type slug")
     return value