From ec59a8059517ef024821c2c1de5ff0f45d4b6040 Mon Sep 17 00:00:00 2001
From: DanCardin <ddcardin@gmail.com>
Date: Wed, 15 Jan 2025 10:16:50 -0500
Subject: [PATCH] fix: Reexport Empty/EmptyType types at the root.

---
 CHANGELOG.md          |  3 +++
 docs/source/arg.md    | 16 ++++++++++++++
 pyproject.toml        | 50 ++++++++-----------------------------------
 src/cappa/__init__.py |  3 +++
 uv.lock               |  2 +-
 5 files changed, 32 insertions(+), 42 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 00a115f..c998ed5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,9 @@
 
 ## 0.26
 
+### 0.26.3
+- fix: Reexport Empty/EmptyType types at the root.
+
 ### 0.26.2
 
 - fix: Optional positional arguments should not get a default value from their action.
diff --git a/docs/source/arg.md b/docs/source/arg.md
index 740b000..f8fe5b4 100644
--- a/docs/source/arg.md
+++ b/docs/source/arg.md
@@ -235,6 +235,15 @@ As noted above, a value produced by `Default.default` **does not** invoke the `A
 for similar reasons as to native dataclass defaults. The programmer is supplying the default value
 which should not **need** to be parsed.
 
+```{note}
+`Default`'s fallback behavior will fallback to lower priority handlers in the "default sequence" when
+that item's default returns `cappa.Empty`. All the native (`Env`, `Prompt`, `Confirm`)
+handlers will do this natively, when they fail to produce a value.
+
+A `ValueFrom` (described below) accepts a user-provided function, so it **may** need to be aware of
+this and return `cappa.Empty`, depending on the desired behavior.
+```
+
 ### `Env`
 
 [cappa.Env](cappa.Env) performs environment variable lookups in an attempt to provide a value to the
@@ -297,6 +306,13 @@ As noted above, a value produced by `ValueFrom` **does not** invoke the `Arg.par
 because the called function is programmer-supplied and can/should just return the correct end
 value.
 
+```{info}
+If there are scenarios where `ValueFrom` **should** fail to provide a value and fall back to the
+class-level, or `Default`-level default value, it should return `cappa.Empty` in order to indicate
+to cappa that it shouldn't accept the returned value as the **actual** value to used when constructing
+the resulting class instance.
+```
+
 ## `Arg.show_default`
 
 Defaults to `True` (e.g. `DefaultFormatter(format='{default}', show=True)`). This field controls **both**:
diff --git a/pyproject.toml b/pyproject.toml
index 2e90147..197f1e6 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,36 +1,18 @@
 [project]
 name = "cappa"
-version = "0.26.2"
+version = "0.26.3"
 description = "Declarative CLI argument parser."
 
-urls = {repository = "https://github.com/dancardin/cappa"}
-authors = [
-  {name = "Dan Cardin", email = "ddcardin@gmail.com"},
-]
-license = {file = "LICENSE"}
+urls = { repository = "https://github.com/dancardin/cappa" }
+authors = [{ name = "Dan Cardin", email = "ddcardin@gmail.com" }]
+license = { file = "LICENSE" }
 readme = "README.md"
-keywords = [
-  "CLI",
-  "parser",
-  "argparse",
-  "click",
-  "typer",
-]
-classifiers = [
-  "Topic :: Software Development :: Libraries :: Python Modules",
-]
-
-include = [
-  "py.typed",
-]
+keywords = ["CLI", "parser", "argparse", "click", "typer"]
+classifiers = ["Topic :: Software Development :: Libraries :: Python Modules"]
 
 requires-python = ">=3.8,<4"
 
-dependencies = [
-  "rich",
-  "typing-extensions >= 4.8.0",
-  "type-lens >= 0.2.3",
-]
+dependencies = ["rich", "typing-extensions >= 4.8.0", "type-lens >= 0.2.3"]
 
 [project.optional-dependencies]
 docstring = ["docstring-parser >= 0.15"]
@@ -54,19 +36,7 @@ target-version = "py38"
 
 [tool.ruff.lint]
 select = ["C", "D", "E", "F", "I", "N", "Q", "RET", "RUF", "S", "T", "UP", "YTT"]
-ignore = [
-    "C901",
-    "E501",
-    "S101",
-    "D1",
-    "D203",
-    "D213",
-    "D406",
-    "D407",
-    "D408",
-    "D409",
-    "D413",
-]
+ignore = ["C901", "E501", "S101", "D1", "D203", "D213", "D406", "D407", "D408", "D409", "D413"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/*" = ["T201"]
@@ -103,9 +73,7 @@ doctest_optionflags = "NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL ELLIPSIS"
 addopts = "--doctest-modules -vv --ff --strict-markers"
 norecursedirs = ".* build dist *.egg bin"
 pytester_example_dir = "examples"
-markers = [
-  "help",
-]
+markers = ["help"]
 
 [build-system]
 requires = ["hatchling"]
diff --git a/src/cappa/__init__.py b/src/cappa/__init__.py
index f190a8d..fa447ce 100644
--- a/src/cappa/__init__.py
+++ b/src/cappa/__init__.py
@@ -9,6 +9,7 @@
 from cappa.parse import unpack_arguments
 from cappa.state import State
 from cappa.subcommand import Subcommand, Subcommands
+from cappa.type_view import Empty, EmptyType
 
 # isort: split
 from cappa.arg import Arg, ArgAction, Group
@@ -25,6 +26,8 @@
     "Confirm",
     "Default",
     "Dep",
+    "Empty",
+    "EmptyType",
     "Env",
     "Exit",
     "FileMode",
diff --git a/uv.lock b/uv.lock
index e3f4263..b353afc 100644
--- a/uv.lock
+++ b/uv.lock
@@ -28,7 +28,7 @@ wheels = [
 
 [[package]]
 name = "cappa"
-version = "0.26.1"
+version = "0.26.2"
 source = { editable = "." }
 dependencies = [
     { name = "rich" },