dycw-utilities 0.108.1__py3-none-any.whl → 0.108.3__py3-none-any.whl

{dycw_utilities-0.108.1.dist-info → dycw_utilities-0.108.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dycw-utilities
-Version: 0.108.1
+Version: 0.108.3
 Author-email: Derek Wan <d.wan@icloud.com>
 License-File: LICENSE
 Requires-Python: >=3.12

{dycw_utilities-0.108.1.dist-info → dycw_utilities-0.108.3.dist-info}/RECORD

@@ -1,4 +1,4 @@
-utilities/__init__.py,sha256=IeBN4DoVYNosR_DmJpLKbjCsXl79LuQiIIKs3QarfVo,60
+utilities/__init__.py,sha256=932kugeJpmqtWXsJGSf5NBQ-6ig0_Xf-TGDJSK9b28w,60
 utilities/altair.py,sha256=NSyDsm8QlkAGmsGdxVwCkHnPxt_35yJBa9Lg7bz9Ays,9054
 utilities/astor.py,sha256=xuDUkjq0-b6fhtwjhbnebzbqQZAjMSHR1IIS5uOodVg,777
 utilities/asyncio.py,sha256=41oQUurWMvadFK5gFnaG21hMM0Vmfn2WS6OpC0R9mas,14757
@@ -18,7 +18,7 @@ utilities/errors.py,sha256=BtSNP0JC3ik536ddPyTerLomCRJV9f6kdMe6POz0QHM,361
 utilities/eventkit.py,sha256=bG2rjgQqPaaOEW879Pc8vOCX6zRAl1frIhB1Y6fqQXg,13149
 utilities/fastapi.py,sha256=uwqOGbGwzIbP-lfm-ApG1ZEN3BA_TDsaiuTghhLmxb8,2413
 utilities/fpdf2.py,sha256=zM3gwOYcAfv7P4qhbyvzPmRY4PPAiAQ-ZnPC6I9SZ1M,1832
-utilities/functions.py,sha256=1yeJqFc6OO0W8N5x6Wc0BaEyz094Ny_oYY3qYILOho4,26706
+utilities/functions.py,sha256=BH4F_X34tqHuk-BzG9lzooYIP1OmVKm6GQw51qqYShM,27461
 utilities/functools.py,sha256=WrpHt7NLNWSUn9A1Q_ZIWlNaYZOEI4IFKyBG9HO3BC4,1643
 utilities/getpass.py,sha256=DfN5UgMAtFCqS3dSfFHUfqIMZX2shXvwphOz_6J6f6A,103
 utilities/git.py,sha256=wpt5dZ5Oi5931pN24_VLZYaQOvmR0OcQuVtgHzFUN1k,2359
@@ -40,6 +40,7 @@ utilities/operator.py,sha256=0M2yZJ0PODH47ogFEnkGMBe_cfxwZR02T_92LZVZvHo,3715
 utilities/optuna.py,sha256=loyJGWTzljgdJaoLhP09PT8Jz6o_pwBOwehY33lHkhw,1923
 utilities/orjson.py,sha256=DW5pOpMyrR5Q8caQYly9AqRPazDBqrWv5GRWfULqka4,36291
 utilities/os.py,sha256=D_FyyT-6TtqiN9KSS7c9g1fnUtgxmyMtzAjmYLkk46A,3587
+utilities/parse.py,sha256=vKVWIqR5JykQzPSnMHQr7_h43M6TwfYEnPmjmbgSA-o,4585
 utilities/pathlib.py,sha256=31WPMXdLIyXgYOMMl_HOI2wlo66MGSE-cgeelk-Lias,1410
 utilities/period.py,sha256=ikHXsWtDLr553cfH6p9mMaiCnIAP69B7q84ckWV3HaA,10884
 utilities/pickle.py,sha256=Bhvd7cZl-zQKQDFjUerqGuSKlHvnW1K2QXeU5UZibtg,657
@@ -52,14 +53,14 @@ utilities/pyinstrument.py,sha256=ROq2txPwbe2ZUuYJ2IDNbfT97lu2ca0v5_C_yn6sSlM,800
 utilities/pyrsistent.py,sha256=TLJfiiKO4cKNU_pCoM3zDqmSM421qpuoaeaBNnyC_Ac,2489
 utilities/pytest.py,sha256=85QUax4g2VBBAqAHtM9wekcSLB7_9O8AKFTaCshztL8,7989
 utilities/pytest_regressions.py,sha256=Kp1NS_cyXvBFqyiF_oSzYmSJzIOdAZ0SFcSGmbL_UtI,5001
-utilities/python_dotenv.py,sha256=vcjTodgb3IAQEtUgPODsxGAYwPaXHPuV3G_iDcXm0zY,7886
+utilities/python_dotenv.py,sha256=7N4ZbBxXpPNttOTfg-hpaLFFWA5iJwF7tREBzUnbPOM,3415
 utilities/random.py,sha256=lYdjgxB7GCfU_fwFVl5U-BIM_HV3q6_urL9byjrwDM8,4157
 utilities/re.py,sha256=5J4d8VwIPFVrX2Eb8zfoxImDv7IwiN_U7mJ07wR2Wvs,3958
 utilities/redis.py,sha256=CsDQqc9V6ASLzLQwtbQXZQEndyG9pJiCOhPlPeszt7Y,21203
 utilities/reprlib.py,sha256=Re9bk3n-kC__9DxQmRlevqFA86pE6TtVfWjUgpbVOv0,1849
 utilities/rich.py,sha256=t50MwwVBsoOLxzmeVFSVpjno4OW6Ufum32skXbV8-Bs,1911
 utilities/scipy.py,sha256=X6ROnHwiUhAmPhM0jkfEh0-Fd9iRvwiqtCQMOLmOQF8,945
-utilities/sentinel.py,sha256=Y_UnVkIMlbN6pJquUz2ghY1rTmCo93k_os3PjyoqE9Q,684
+utilities/sentinel.py,sha256=0X1GWWcnPxGCo7wDgVTOfhU5iKlXdvVZudlMM0iezDw,1246
 utilities/shelve.py,sha256=HZsMwK4tcIfg3sh0gApx4-yjQnrY4o3V3ZRimvRhoW0,738
 utilities/slack_sdk.py,sha256=SeDNMh24IPiEBWoGMdgvrflUaFa9TGlTS03H9-NKaQw,4132
 utilities/socket.py,sha256=K77vfREvzoVTrpYKo6MZakol0EYu2q1sWJnnZqL0So0,118
@@ -69,7 +70,7 @@ utilities/streamlit.py,sha256=U9PJBaKP1IdSykKhPZhIzSPTZsmLsnwbEPZWzNhJPKk,2955
 utilities/sys.py,sha256=h0Xr7Vj86wNalvwJVP1wj5Y0kD_VWm1vzuXZ_jw94mE,2743
 utilities/tempfile.py,sha256=VqmZJAhTJ1OaVywFzk5eqROV8iJbW9XQ_QYAV0bpdRo,1384
 utilities/tenacity.py,sha256=1PUvODiBVgeqIh7G5TRt5WWMSqjLYkEqP53itT97WQc,4914
-utilities/text.py,sha256=4DSi_m0E1Bxqp5LhMiPH_m38ag6wQAGrWP_iPkfBo9Q,2688
+utilities/text.py,sha256=X_EjRQeV_PsG3oP7OiGYIyXGKWqciTnSwoKhM2tsy6M,3120
 utilities/threading.py,sha256=GvBOp4CyhHfN90wGXZuA2VKe9fGzMaEa7oCl4f3nnPU,1009
 utilities/timer.py,sha256=Rkc49KSpHuC8s7vUxGO9DU55U9I6yDKnchsQqrUCVBs,4075
 utilities/traceback.py,sha256=KwHPLdEbdj0fFhXo8MBfxcvem8A-VXYDwFMNJ6f0cTM,27328
@@ -83,7 +84,7 @@ utilities/warnings.py,sha256=yUgjnmkCRf6QhdyAXzl7u0qQFejhQG3PrjoSwxpbHrs,1819
 utilities/whenever.py,sha256=5x2t47VJmJRWcd_NLFy54NkB3uom-XQYxEbLtEfL1bs,17775
 utilities/zipfile.py,sha256=24lQc9ATcJxHXBPc_tBDiJk48pWyRrlxO2fIsFxU0A8,699
 utilities/zoneinfo.py,sha256=-DQz5a0Ikw9jfSZtL0BEQkXOMC9yGn_xiJYNCLMiqEc,1989
-dycw_utilities-0.108.1.dist-info/METADATA,sha256=VOAnUEUC7wcoSrSFoy7zijMLaJYHCt-euTVZdVZThEU,13004
-dycw_utilities-0.108.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-dycw_utilities-0.108.1.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
-dycw_utilities-0.108.1.dist-info/RECORD,,
+dycw_utilities-0.108.3.dist-info/METADATA,sha256=A5j6OCjBswwlY0SpdfckG4fb3_nZCjlgIDluLCVAdVY,13004
+dycw_utilities-0.108.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+dycw_utilities-0.108.3.dist-info/licenses/LICENSE,sha256=gppZp16M6nSVpBbUBrNL6JuYfvKwZiKgV7XoKKsHzqo,1066
+dycw_utilities-0.108.3.dist-info/RECORD,,

utilities/__init__.py

@@ -1,3 +1,3 @@
 from __future__ import annotations
 
-__version__ = "0.108.1"
+__version__ = "0.108.3"

utilities/functions.py

@@ -5,6 +5,7 @@ from collections.abc import Callable, Iterable, Iterator, Sequence
 from dataclasses import asdict, dataclass, is_dataclass
 from functools import _lru_cache_wrapper, cached_property, partial, reduce, wraps
 from inspect import getattr_static
+from pathlib import Path
 from re import findall
 from types import (
     BuiltinFunctionType,
@@ -405,6 +406,31 @@ class EnsureNumberError(Exception):
 ##
 
 
+@overload
+def ensure_path(obj: Any, /, *, nullable: bool) -> Path | None: ...
+@overload
+def ensure_path(obj: Any, /, *, nullable: Literal[False] = False) -> Path: ...
+def ensure_path(obj: Any, /, *, nullable: bool = False) -> Path | None:
+    """Ensure an object is a Path."""
+    try:
+        return ensure_class(obj, Path, nullable=nullable)
+    except EnsureClassError as error:
+        raise EnsurePathError(obj=error.obj, nullable=nullable) from None
+
+
+@dataclass(kw_only=True, slots=True)
+class EnsurePathError(Exception):
+    obj: Any
+    nullable: bool
+
+    @override
+    def __str__(self) -> str:
+        return _make_error_msg(self.obj, "a Path", nullable=self.nullable)
+
+
+##
+
+
 def ensure_sized(obj: Any, /) -> Sized:
     """Ensure an object is sized."""
     if is_sized(obj):
@@ -985,6 +1011,7 @@ __all__ = [
     "EnsureMemberError",
     "EnsureNotNoneError",
     "EnsureNumberError",
+    "EnsurePathError",
     "EnsureSizedError",
     "EnsureSizedNotStrError",
     "EnsureStrError",
@@ -1004,6 +1031,7 @@ __all__ = [
     "ensure_member",
     "ensure_not_none",
     "ensure_number",
+    "ensure_path",
     "ensure_sized",
     "ensure_sized_not_str",
     "ensure_str",

utilities/parse.py

@@ -0,0 +1,129 @@
+from __future__ import annotations
+
+import datetime as dt
+from contextlib import suppress
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+from types import NoneType
+from typing import Any, get_args, override
+
+from utilities.datetime import is_subclass_date_not_datetime
+from utilities.enum import ParseEnumError, parse_enum
+from utilities.functions import is_subclass_int_not_bool
+from utilities.iterables import one, one_str
+from utilities.sentinel import ParseSentinelError, Sentinel, parse_sentinel
+from utilities.text import ParseBoolError, ParseNoneError, parse_bool, parse_none
+from utilities.typing import is_literal_type, is_optional_type
+from utilities.version import ParseVersionError, Version, parse_version
+
+
+def parse_text(
+    obj: Any, text: str, /, *, case_sensitive: bool = False, head: bool = False
+) -> Any:
+    """Parse text."""
+    if obj is None:
+        try:
+            return parse_none(text)
+        except ParseNoneError:
+            raise ParseTextError(obj=obj, text=text) from None
+    if isinstance(obj, type):
+        return _parse_text_type(obj, text, case_sensitive=case_sensitive)
+    if is_literal_type(obj):
+        return one_str(get_args(obj), text, head=head, case_sensitive=case_sensitive)
+    if is_optional_type(obj):
+        with suppress(ParseNoneError):
+            return parse_none(text)
+        inner = one(arg for arg in get_args(obj) if arg is not NoneType)
+        if isinstance(
+            inner := one(arg for arg in get_args(obj) if arg is not NoneType), type
+        ):
+            try:
+                return _parse_text_type(inner, text, case_sensitive=case_sensitive)
+            except ParseTextError:
+                raise ParseTextError(obj=obj, text=text) from None
+    raise ParseTextError(obj=obj, text=text) from None
+
+
+def _parse_text_type(
+    cls: type[Any], text: str, /, *, case_sensitive: bool = False
+) -> Any:
+    """Parse text."""
+    if issubclass(cls, NoneType):
+        try:
+            return parse_none(text)
+        except ParseNoneError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, str):
+        return text
+    if issubclass(cls, bool):
+        try:
+            return parse_bool(text)
+        except ParseBoolError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if is_subclass_int_not_bool(cls):
+        try:
+            return int(text)
+        except ValueError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, float):
+        try:
+            return float(text)
+        except ValueError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, Enum):
+        try:
+            return parse_enum(text, cls, case_sensitive=case_sensitive)
+        except ParseEnumError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, Path):
+        return Path(text).expanduser()
+    if issubclass(cls, Sentinel):
+        try:
+            return parse_sentinel(text)
+        except ParseSentinelError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, Version):
+        try:
+            return parse_version(text)
+        except ParseVersionError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if is_subclass_date_not_datetime(cls):
+        from utilities.whenever import ParseDateError, parse_date
+
+        try:
+            return parse_date(text)
+        except ParseDateError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, dt.datetime):
+        from utilities.whenever import ParseDateTimeError, parse_datetime
+
+        try:
+            return parse_datetime(text)
+        except ParseDateTimeError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, dt.time):
+        from utilities.whenever import ParseTimeError, parse_time
+
+        try:
+            return parse_time(text)
+        except ParseTimeError:
+            raise ParseTextError(obj=cls, text=text) from None
+    if issubclass(cls, dt.timedelta):
+        from utilities.whenever import ParseTimedeltaError, parse_timedelta
+
+        try:
+            return parse_timedelta(text)
+        except ParseTimedeltaError:
+            raise ParseTextError(obj=cls, text=text) from None
+    raise ParseTextError(obj=cls, text=text) from None
+
+
+@dataclass
+class ParseTextError(Exception):
+    obj: Any
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse {self.obj!r}; got {self.text!r}"

utilities/python_dotenv.py

@@ -1,12 +1,8 @@
 from __future__ import annotations
 
-import datetime as dt
 from dataclasses import dataclass
-from enum import Enum
 from functools import partial
 from os import environ
-from pathlib import Path
-from re import IGNORECASE, search
 from typing import TYPE_CHECKING, Any, override
 
 from dotenv import dotenv_values
@@ -16,16 +12,15 @@ from utilities.dataclasses import (
     _YieldFieldsClass,
     mapping_to_dataclass,
 )
-from utilities.enum import EnsureEnumError, ensure_enum
-from utilities.functions import get_class_name
 from utilities.git import get_repo_root
-from utilities.iterables import MergeStrMappingsError, merge_str_mappings, one, one_str
+from utilities.iterables import MergeStrMappingsError, merge_str_mappings
+from utilities.parse import ParseTextError, parse_text
 from utilities.pathlib import PWD
 from utilities.reprlib import get_repr
-from utilities.typing import get_args, is_literal_type, is_optional_type
 
 if TYPE_CHECKING:
     from collections.abc import Mapping
+    from pathlib import Path
 
     from utilities.types import PathLike, StrMapping, TDataclass
 
@@ -65,72 +60,14 @@ def load_settings(
 
 
 def _load_settings_post(
-    field: _YieldFieldsClass[Any], value: Any, /, *, path: Path, values: StrMapping
+    field: _YieldFieldsClass[Any], text: str, /, *, path: Path, values: StrMapping
 ) -> Any:
-    type_ = field.type_
-    if type_ is str:
-        return value
-    if type_ is bool:
-        if value == "0" or search("false", value, flags=IGNORECASE):
-            return False
-        if value == "1" or search("true", value, flags=IGNORECASE):
-            return True
-        raise _LoadSettingsInvalidBoolError(
-            path=path, values=values, field=field.name, value=value
-        )
-    if type_ is float:
-        try:
-            return float(value)
-        except ValueError:
-            raise _LoadSettingsInvalidFloatError(
-                path=path, values=values, field=field.name, value=value
-            ) from None
-    if type_ is int:
-        try:
-            return int(value)
-        except ValueError:
-            raise _LoadSettingsInvalidIntError(
-                path=path, values=values, field=field.name, value=value
-            ) from None
-    if type_ is Path:
-        return Path(value).expanduser()
-    if type_ is dt.date:
-        from utilities.whenever import ParseDateError, parse_date
-
-        try:
-            return parse_date(value)
-        except ParseDateError:
-            raise _LoadSettingsInvalidDateError(
-                path=path, values=values, field=field.name, value=value
-            ) from None
-    if type_ is dt.timedelta:
-        from utilities.whenever import ParseTimedeltaError, parse_timedelta
-
-        try:
-            return parse_timedelta(value)
-        except ParseTimedeltaError:
-            raise _LoadSettingsInvalidTimeDeltaError(
-                path=path, values=values, field=field.name, value=value
-            ) from None
-    if isinstance(type_, type) and issubclass(type_, Enum):
-        try:
-            return ensure_enum(value, type_)
-        except EnsureEnumError:
-            raise _LoadSettingsInvalidEnumError(
-                path=path, values=values, field=field.name, type_=type_, value=value
-            ) from None
-    if is_literal_type(type_):
-        return one_str(get_args(type_), value)
-    if is_optional_type(type_) and (one(get_args(type_)) is int):
-        if (value is None) or (value == "") or search("none", value, flags=IGNORECASE):
-            return None
-        try:
-            return int(value)
-        except ValueError:
-            raise _LoadSettingsInvalidNullableIntError(
-                path=path, values=values, field=field.name, value=value
-            ) from None
-    raise _LoadSettingsTypeError(path=path, field=field.name, type=type_)
+    try:
+        return parse_text(field.type_, text)
+    except ParseTextError:
+        raise _LoadSettingsParseTextError(
+            path=path, values=values, field=field, text=text
+        ) from None
 
 
 @dataclass(kw_only=True, slots=True)
@@ -138,13 +75,6 @@ class LoadSettingsError(Exception):
     path: Path
 
 
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsFileNotFoundError(LoadSettingsError):
-    @override
-    def __str__(self) -> str:
-        return f"Path {str(self.path)!r} must exist"
-
-
 @dataclass(kw_only=True, slots=True)
 class _LoadSettingsDuplicateKeysError(LoadSettingsError):
     values: StrMapping
@@ -166,94 +96,21 @@ class _LoadSettingsEmptyError(LoadSettingsError):
 
 
 @dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidBoolError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Field {self.field!r} must contain a valid boolean; got {self.value!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidDateError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Field {self.field!r} must contain a valid date; got {self.value!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidEnumError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    type_: type[Enum]
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        type_ = get_class_name(self.type_)
-        return f"Field {self.field!r} must contain a valid member of {type_!r}; got {self.value!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidFloatError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Field {self.field!r} must contain a valid float; got {self.value!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidIntError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        return f"Field {self.field!r} must contain a valid integer; got {self.value!r}"
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidNullableIntError(LoadSettingsError):
-    values: StrMapping
-    field: str
-    value: str
-
+class _LoadSettingsFileNotFoundError(LoadSettingsError):
     @override
     def __str__(self) -> str:
-        return f"Field {self.field!r} must contain a valid nullable integer; got {self.value!r}"
+        return f"Path {str(self.path)!r} must exist"
 
 
 @dataclass(kw_only=True, slots=True)
-class _LoadSettingsInvalidTimeDeltaError(LoadSettingsError):
+class _LoadSettingsParseTextError(LoadSettingsError):
     values: StrMapping
-    field: str
-    value: str
-
-    @override
-    def __str__(self) -> str:
-        return (
-            f"Field {self.field!r} must contain a valid timedelta; got {self.value!r}"
-        )
-
-
-@dataclass(kw_only=True, slots=True)
-class _LoadSettingsTypeError(LoadSettingsError):
-    field: str
-    type: Any
+    field: _YieldFieldsClass[Any]
+    text: str
 
     @override
     def __str__(self) -> str:
-        return f"Field {self.field!r} has unsupported type {self.type!r}"
+        return f"Unable to parse field {self.field.name!r} of type {self.field.type_!r}; got {self.text!r}"
 
 
 __all__ = ["LoadSettingsError", "load_settings"]

utilities/sentinel.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
+from re import IGNORECASE, search
 from typing import Any, override
 
 
@@ -33,4 +35,29 @@ class Sentinel(metaclass=_Meta):
 sentinel = Sentinel()
 
 
-__all__ = ["SENTINEL_REPR", "Sentinel", "sentinel"]
+##
+
+
+def parse_sentinel(text: str, /) -> Sentinel:
+    """Parse text into the Sentinel value."""
+    if text == "" or search("Sentinel", text, flags=IGNORECASE):
+        return sentinel
+    raise ParseSentinelError(text=text)
+
+
+@dataclass(kw_only=True, slots=True)
+class ParseSentinelError(Exception):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse sentinel value; got {self.text!r}"
+
+
+__all__ = [
+    "SENTINEL_REPR",
+    "ParseSentinelError",
+    "Sentinel",
+    "parse_sentinel",
+    "sentinel",
+]

utilities/text.py

@@ -45,7 +45,26 @@ class ParseBoolError(Exception):
 
     @override
     def __str__(self) -> str:
-        return f"Unable to parse {self.text!r} into a boolean value"
+        return f"Unable to parse boolean value; got {self.text!r}"
+
+
+##
+
+
+def parse_none(text: str, /) -> None:
+    """Parse text into the None value."""
+    if text == "" or search("None", text, flags=IGNORECASE):
+        return
+    raise ParseNoneError(text=text)
+
+
+@dataclass(kw_only=True, slots=True)
+class ParseNoneError(Exception):
+    text: str
+
+    @override
+    def __str__(self) -> str:
+        return f"Unable to parse null value; got {self.text!r}"
 
 
 ##
@@ -108,8 +127,10 @@ def strip_and_dedent(text: str, /, *, trailing: bool = False) -> str:
 
 __all__ = [
     "ParseBoolError",
+    "ParseNoneError",
     "join_strs",
     "parse_bool",
+    "parse_none",
     "repr_encode",
     "snake_case",
     "split_str",