bakefile 0.0.10__py3-none-any.whl → 0.0.11__py3-none-any.whl

bake/ui/run/run.py

@@ -68,7 +68,8 @@ def _run_with_temp_file(
     stream: bool,
     keep_temp_file: bool = False,
     env: dict[str, str] | None = None,
-    _encoding: str = "utf-8",
+    _encoding: str | None = None,
+    echo_cmd: str | None = None,
     **kwargs,
 ) -> subprocess.CompletedProcess[str] | subprocess.CompletedProcess[None]:
     """Run multi-line script using temp file with shebang support.
@@ -83,6 +84,9 @@ def _run_with_temp_file(
     _encoding : str, optional
         Encoding to use for subprocess output. Defaults to "utf-8" to ensure
         cross-platform UTF-8 support for temp file scripts.
+    echo_cmd : str | None, optional
+        Override the command string displayed in logs and console output.
+        Default is None (show actual command).
 
     Notes
     -----
@@ -122,6 +126,7 @@ def _run_with_temp_file(
             cwd=cwd,
             stream=stream,
             echo=False,
+            echo_cmd=echo_cmd,
             env=env,
             _encoding=_encoding,
             **kwargs,
@@ -147,6 +152,7 @@ def run(
     stream: bool = True,
     shell: bool | None = None,
     echo: bool = True,
+    echo_cmd: str | None = None,
     dry_run: bool = False,
     keep_temp_file: bool = False,
     env: dict[str, str] | None = None,
@@ -165,6 +171,7 @@ def run(
     stream: bool = True,
     shell: bool | None = None,
     echo: bool = True,
+    echo_cmd: str | None = None,
     dry_run: bool = False,
     keep_temp_file: bool = False,
     env: dict[str, str] | None = None,
@@ -182,6 +189,7 @@ def run(
     stream: bool = True,
     shell: bool | None = None,
     echo: bool = True,
+    echo_cmd: str | None = None,
     dry_run: bool = False,
     keep_temp_file: bool = False,
     env: dict[str, str] | None = None,
@@ -215,6 +223,11 @@ def run(
     echo : bool, optional
         Display command before execution using console.cmd().
         Default is True. Set to False for silent execution.
+    echo_cmd : str | None, optional
+        Override the command string displayed in logs and console output.
+        The actual command is still executed, but this string is shown instead.
+        Useful for hiding complex binary paths or secrets in commands.
+        Default is None (show actual command).
     dry_run : bool, optional
         Display command without executing (dry-run mode).
         Default is False. Does NOT auto-echo; combine with echo=True
@@ -249,16 +262,18 @@ def run(
     >>> run("echo hello", echo=True, dry_run=True)  # Show but don't run
     >>> run("ls *.py | wc -l")                # Pipes and wildcards
     >>> run(["echo", "hello"])                # List for direct execution
+    >>> run("/path/to/binary arg", echo_cmd="binary arg")  # Override display
     """
     _validate_params(stream=stream, capture_output=capture_output)
     shell = _detect_shell(cmd=cmd, shell=shell)
     cmd_str = _format_cmd_str(cmd=cmd)
+    cmd_str_for_display = echo_cmd if echo_cmd is not None else cmd_str
 
     if echo:
-        console.cmd(cmd_str)
+        console.cmd(cmd_str_for_display)
 
     if dry_run:
-        return _dry_run_result(cmd=cmd, capture_output=capture_output, cwd=cwd)
+        return _dry_run_result(cmd=cmd, capture_output=capture_output, cwd=cwd, echo_cmd=echo_cmd)
 
     # Handle multi-line scripts that require temp file approach:
     # - Windows: Any multi-line script with shell=True (cmd.exe limitation)
@@ -287,10 +302,12 @@ def run(
             stream=stream,
             keep_temp_file=keep_temp_file,
             env=env,
+            _encoding=_encoding,
+            echo_cmd=echo_cmd,
             **kwargs,
         )
 
-    logger.debug(f"[run] {cmd_str}", extra={"cwd": cwd})
+    logger.debug(f"[run] {cmd_str_for_display}", extra={"cwd": cwd})
     start = time.perf_counter()
 
     _run = _run_with_stream if stream else _run_without_stream
@@ -305,9 +322,9 @@ def run(
         **kwargs,
     )
 
-    _check_exit_code(returncode=result.returncode, check=check, cmd_str=cmd_str)
+    _check_exit_code(result=result, check=check, cmd_str_for_display=cmd_str_for_display)
 
-    _log_completion(cmd_str=cmd_str, result=result, start=start)
+    _log_completion(cmd_str_for_display=cmd_str_for_display, result=result, start=start)
     return result
 
 
@@ -330,9 +347,11 @@ def _dry_run_result(
     cmd: str | list[str] | tuple[str, ...],
     capture_output: bool,
     cwd: Path | str | None,
+    echo_cmd: str | None = None,
 ) -> subprocess.CompletedProcess[str]:
     cmd_str = _format_cmd_str(cmd)
-    logger.debug(f"[dry-run] {cmd_str}", extra={"cwd": cwd})
+    cmd_str_for_display = echo_cmd if echo_cmd is not None else cmd_str
+    logger.debug(f"[dry-run] {cmd_str_for_display}", extra={"cwd": cwd})
     return subprocess.CompletedProcess(
         args=cmd,
         returncode=0,
@@ -341,10 +360,21 @@ def _dry_run_result(
     )
 
 
-def _check_exit_code(returncode: int, check: bool, cmd_str: str) -> None:
-    if check and returncode != 0:
-        logger.debug(f"[error] {cmd_str}", extra={"returncode": returncode})
-        raise typer.Exit(returncode)
+def _check_exit_code(
+    result: subprocess.CompletedProcess[str] | subprocess.CompletedProcess[None],
+    check: bool,
+    cmd_str_for_display: str,
+) -> None:
+    if check and result.returncode != 0:
+        logger.debug(
+            f"[error] {cmd_str_for_display}",
+            extra={
+                "returncode": result.returncode,
+                "stdout": result.stdout,
+                "stderr": result.stderr,
+            },
+        )
+        raise typer.Exit(result.returncode)
 
 
 def _process_stream_output(
@@ -533,10 +563,12 @@ def _run_without_stream(
     return result
 
 
-def _log_completion(cmd_str: str, result: subprocess.CompletedProcess, start: float) -> None:
+def _log_completion(
+    cmd_str_for_display: str, result: subprocess.CompletedProcess, start: float
+) -> None:
     elapsed_seconds = time.perf_counter() - start
     logger.debug(
-        f"[done] {cmd_str}",
+        f"[done] {cmd_str_for_display}",
         extra={
             "returncode": result.returncode,
             "stdout": result.stdout,

bake/ui/run/uv.py

@@ -4,7 +4,6 @@ from typing import Literal, overload
 
 from uv import find_uv_bin
 
-from bake.ui import console
 from bake.ui.run.run import run
 
 
@@ -59,14 +58,6 @@ def run_uv(
 ) -> subprocess.CompletedProcess[str] | subprocess.CompletedProcess[None]:
     uv_bin = find_uv_bin()
 
-    # Build display string: "uv" + command parts (no full binary path)
-    display_cmd = "uv " + " ".join(cmd)
-
-    # Echo command to console if requested
-    if echo:
-        console.cmd(display_cmd)
-
-    # Call run with full uv binary path, echo=False (already displayed), pass through options
     return run(
         [uv_bin, *cmd],
         capture_output=capture_output,
@@ -74,7 +65,8 @@ def run_uv(
         cwd=cwd,
         stream=stream,
         shell=False,
-        echo=False,
+        echo=echo,
+        echo_cmd="uv " + " ".join(cmd) if echo else None,
         dry_run=dry_run,
         keep_temp_file=keep_temp_file,
         env=env,

bake/utils/__init__.py

@@ -1,11 +1,17 @@
 from bake.utils.constants import DEFAULT_BAKEBOOK_NAME, DEFAULT_FILE_NAME
-from bake.utils.env import should_use_colors
 from bake.utils.exceptions import BakebookError, BaseBakefileError
+from bake.utils.settings import (
+    ENV__BAKE_REINVOKED,
+    ENV_NO_COLOR,
+    bake_settings,
+)
 
 __all__ = [
     "DEFAULT_BAKEBOOK_NAME",
     "DEFAULT_FILE_NAME",
+    "ENV_NO_COLOR",
+    "ENV__BAKE_REINVOKED",
     "BakebookError",
     "BaseBakefileError",
-    "should_use_colors",
+    "bake_settings",
 ]

bake/utils/settings.py

@@ -0,0 +1,25 @@
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+ENV_NO_COLOR = "NO_COLOR"
+ENV__BAKE_REINVOKED = "_BAKE_REINVOKED"
+
+
+class BakeSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+        populate_by_name=True,
+    )
+
+    ci: bool = False
+    github_actions: bool = False
+    no_color: bool = False
+    bake_reinvoked: bool = Field(default=False, alias="_BAKE_REINVOKED")
+
+    def should_use_colors(self) -> bool:
+        return self.no_color
+
+
+bake_settings = BakeSettings()

{bakefile-0.0.10.dist-info → bakefile-0.0.11.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bakefile
-Version: 0.0.10
+Version: 0.0.11
 Summary: Add your description here
 Author: Wisaroot Lertthaweedech
 Author-email: Wisaroot Lertthaweedech <l.wisaroot@gmail.com>
@@ -18,7 +18,9 @@ Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
 Requires-Dist: ty>=0.0.8
 Requires-Dist: typer>=0.21.0
 Requires-Dist: uv>=0.9.20
+Requires-Dist: keyring>=25.7.0 ; extra == 'lib'
 Requires-Dist: pathspec>=1.0.3 ; extra == 'lib'
+Requires-Dist: tenacity>=9.1.2 ; extra == 'lib'
 Requires-Python: >=3.10
 Provides-Extra: lib
 Description-Content-Type: text/markdown

{bakefile-0.0.10.dist-info → bakefile-0.0.11.dist-info}/RECORD

@@ -6,8 +6,8 @@ bake/bakebook/get.py,sha256=fx5WV66OIBrywPN0thePXAJk2gt7wvTVAxYQqZ_PMao,5807
 bake/cli/__init__.py,sha256=da1PTClDMl-IBkrSvq6JC1lnS-K_BASzCvxVhNxN5Ls,13
 bake/cli/bake/__init__.py,sha256=CJokSP1t1KXaIqjkjFQ8_gbaSZ9RRB4YdemIoSTqRcI,56
 bake/cli/bake/__main__.py,sha256=5Ui5_OD1-oG1ou6boak63EPQDmRsW9sGOVVDgXJaNec,133
-bake/cli/bake/main.py,sha256=Lr6eyfaf4-zDRrF0GK9bjjFWop66ydewV5tNUluDd9M,2262
-bake/cli/bake/reinvocation.py,sha256=Ifqc8ZAM7NMyrKU2jkmw1agCEI-Sx7yvLLBiFRi23_0,1985
+bake/cli/bake/main.py,sha256=286zCeRpxq2sGm7_vbX55YVm13dHrrCBtVNEXeZcNzg,3630
+bake/cli/bake/reinvocation.py,sha256=Df_rRylarejI0nj2dV7s9YAhgN0B5iJnclzU0EcfN5Q,2100
 bake/cli/bakefile/__init__.py,sha256=_zD3rXQHLr6EWHADdPLAmnc2A5C3dhmBuvP5uJ-_A58,60
 bake/cli/bakefile/__main__.py,sha256=FVntzkZdzdygSWjMzyneXCXsM-MDTPmC3GUk4JZiYFU,137
 bake/cli/bakefile/add_inline.py,sha256=V98T50SLMPqnWVtyEO_6hL17r4n3ZtkSC8NSEqdyHzc,919
@@ -15,54 +15,58 @@ bake/cli/bakefile/export.py,sha256=m9X0u6FgbjUzneQuh39H1CaFUT444jOPTFBNjnjs_Dg,6
 bake/cli/bakefile/find_python.py,sha256=J2HDs_nfNODqCHBZCNM64ESB4kVZK-C04i-KNmVUoSs,539
 bake/cli/bakefile/init.py,sha256=0QuvADFOZZUBN2BUJfK90aEY1oUzoSNVRiljlUSjLu0,1825
 bake/cli/bakefile/lint.py,sha256=DJkIJNBOef6JvgwQ3iL9jTrLqgUyn66Mhv6cuAgqXk0,2509
-bake/cli/bakefile/main.py,sha256=jbpzNQa55thbzhpcmEtys1M1CvNUJBvi5UmgVzSbOM8,1414
+bake/cli/bakefile/main.py,sha256=pxDIefHx-_PrbGbE133eODHwC7UQC7NkjMUm_7EGFKg,2435
 bake/cli/bakefile/uv.py,sha256=PMFG3BdofzGWkor4fMEi3GE4G7hGtclCgPm2xlaPDso,4013
 bake/cli/common/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bake/cli/common/app.py,sha256=_XzBOy0OK2GB14E-cyfLV6CBCn70G62QqjUscj_DHfA,1443
-bake/cli/common/callback.py,sha256=NmrZUl5eRr95nluomTwcKjTU7dSKjWcQVli5VEdZk-4,439
-bake/cli/common/context.py,sha256=RtFHUDCZLcD88Ys17u_zXoHUq-12jkoXc9f_D4jh_7M,3871
+bake/cli/common/app.py,sha256=6tWCyMKHwSynYI3qzc1AfSfLS4p2P25AilOsThqLN7k,1296
+bake/cli/common/context.py,sha256=miyA87yaZLeuTsBnjIQdo4f5QKsI3CtOByTrzAWtweQ,4013
 bake/cli/common/exception_handler.py,sha256=2vLbqMeZlLxKqNWUkTs3cA-8l6IjK0dU3SyZlRb96YI,1759
-bake/cli/common/obj.py,sha256=ShDsQtHCxex17IrKb9kSdC1t459qBsam53SFCUB_DSA,7094
-bake/cli/common/params.py,sha256=rhLa34SY92nXfUaKo0SQMKK__xRnrmHejHa25tRyKdg,2002
+bake/cli/common/obj.py,sha256=IcURtAHXRrwFkXZsVTTruEMeLddwowtBvpa5lBknpEk,7181
+bake/cli/common/params.py,sha256=229B4PPTv84InlDSA0sjlU3ToCjyzvhjNpRIp2iFano,2278
 bake/cli/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bake/cli/utils/version.py,sha256=aiweLD0vDezBlJAcCC99oMms71WGD9CWSJuZ4i3VLHA,390
 bake/manage/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bake/manage/add_inline.py,sha256=yefHmF33ghCB8NZ-v61ybeVsaeE8iDFvfRGeTAKg4I8,2245
 bake/manage/find_python.py,sha256=67PAFPDA3fdSsDGjYfPcXOVUcgC63wg5mipjVIt1VUQ,7730
-bake/manage/lint.py,sha256=OqwYFF8GGvzHGVPuJcWMRAv5esXEIX4nQXdGcChnkqA,2394
+bake/manage/lint.py,sha256=4opV1EanzPUz5tmdzvNclM-qK4TmL85IixbzP5z-zRY,2472
 bake/manage/run_uv.py,sha256=QzlKeVpr20dXNDcwUgyJqnXT4MofRqK-6XkWpzBbUhE,3234
 bake/manage/write_bakefile.py,sha256=efGViLk7sh-QX9Mox7yQw_A1Tp7EOuc_vmSTbFmXUm0,736
 bake/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bake/samples/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 bake/samples/simple.py,sha256=hP2TW-D7BQBGJseqRPpilxkoQ8ScTuZZePICupyvFKA,155
 bake/ui/__init__.py,sha256=6OhZVKjfC9aumbhraxkGtx7KLpV1ouepeHRA2dUVoSo,209
-bake/ui/console.py,sha256=C5wrbsOc-wwcx0hGmCozHvGCNTWgGhsh-5vxl880xS4,1689
+bake/ui/console.py,sha256=y5pZ5i_Iqh4bzaHGJQFDMnqRILsIClr8004EkLydLr4,3289
 bake/ui/logger/__init__.py,sha256=bup2cssTHhergh47s6uYbGtY2dJNxlKKH6otBc4ECFM,728
 bake/ui/logger/capsys.py,sha256=KZL6k7Werp_8styfJKfIvQyv0-gJq54vY3hSJFIacEM,5267
 bake/ui/logger/setup.py,sha256=OrX9UiY0iBGfWWfhMJCdfqCRJsL5yC3rIdIEOn7rveo,1377
 bake/ui/logger/utils.py,sha256=dcppxoS_pX92AFcHIerJGI2_JBHBNghRQmQqlZmmj2Q,7218
 bake/ui/params.py,sha256=yNDChJQkbeZSxQzXTSBrAPCbwsJ5zOK4s4sFHQPSnHs,140
 bake/ui/run/__init__.py,sha256=A671l5YVTRAtS47ewvaMCNwPRim_Wkof1am0WibxA2I,205
-bake/ui/run/run.py,sha256=qfDgy-YqcexJyHhSjnQ5IXipBDoK-umwKq-wAn8ZITU,17504
+bake/ui/run/run.py,sha256=t06v1E2TD8PGymnUsIHfZxwiBGeqFZ7Mt9W3IwowsMc,18842
 bake/ui/run/script.py,sha256=fk7KiDklYDYpFGkH3wu-hZGI4OnvgcB8z5jtNt41Hg0,2263
 bake/ui/run/splitter.py,sha256=L6uCU3bzpoMgj891Q1BZnOtiWF07QFDcCOx9RyUqHKk,9198
-bake/ui/run/uv.py,sha256=3NpnjgAwQNijJiUT_H6U-3mTHQgBZPlJbNWEeYCZY1g,2077
+bake/ui/run/uv.py,sha256=LC1Eo3rbmRug8_MsmXxZYVGWcyr79WGzFfXQrEwtWH0,1810
 bake/ui/style.py,sha256=v9dferzV317Acb0GHpVK_niCj_s2HtL-yiToBZtXky4,70
-bake/utils/__init__.py,sha256=GUu_xlJy3RAHo6UcZXu2x4khxGqLHMA9Zos4hDiQIY8,326
+bake/utils/__init__.py,sha256=1XKY-YbhTIwkWM-goTwek82mcQhwKqMW_bNTirUSrfI,422
 bake/utils/constants.py,sha256=mRq5IpgOTdlHOTWPq5dx0A-LwhiFkWgYHfr8cLWG7rY,471
-bake/utils/env.py,sha256=bzNdH_2bTJebQaw7D0uVJv-vzZ-uYl0pCAS8oQONVsA,190
 bake/utils/exceptions.py,sha256=pwsQnKH5ljMNxmqEREutXa7TohiBHATHg_D5kQUPT30,519
-bakelib/__init__.py,sha256=7lWfLpL82AVkot3BXodJpyuEzEAiythFevMtzxzd_i4,455
+bake/utils/settings.py,sha256=SRFU9WVHRMB1cE0TjReKEgL1nbIFM9NBLJWcGiODdOk,612
+bakelib/__init__.py,sha256=yj72sp5MbSebIxIGHh183gbNE5oIdv-OG-8IYnoJ6AE,529
 bakelib/environ/__init__.py,sha256=XIFVtu8SQySjPetu9WR_Q8HgqxUzenMNm1K24pYSfNo,356
 bakelib/environ/bakebook.py,sha256=gnOvi3t5Ww0_6N5wozXLVvLe8KAK-u-6_v0UYCl_iKY,749
 bakelib/environ/base.py,sha256=azPUdc9C5zVU8iyXJrEm3uDfe39nG48DRAZiF9rTdHI,3753
 bakelib/environ/get_bakebook.py,sha256=LihxB3VDcVq81KJy1HT-N-beyt2C7ReWm2kMPrd7VlA,1563
 bakelib/environ/presets.py,sha256=IwHGeDeQe4e57k9_u_vBQ61bjMS5Z2Jj9zkXw6YJHAE,1943
+bakelib/refreshable_cache/__init__.py,sha256=hNylzA9X9GpAiuG3WYBvgGRY-z8Gcu_BxsyHOIwtTOQ,347
+bakelib/refreshable_cache/cache.py,sha256=P8gX63FP1vgdwNOwKLf-U0ly1P1LvNsB7KqDS9XdG5Q,7629
+bakelib/refreshable_cache/exceptions.py,sha256=d15dd0RbapXneWZpDwfvDt7k49cB6jZBMxULi5DLU9Q,97
 bakelib/space/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-bakelib/space/base.py,sha256=4afkB2Cmq3kP-xBeL45lvmmOhARsA-m5F1-rEPLAgEc,5871
-bakelib/space/python.py,sha256=0qxjIQ1SYIvDkaeQjkykE2t8doBUTl1MONK8cuG5juo,2793
-bakelib/space/utils.py,sha256=xx4X_txhDH_p97CKJ-KuvFpgfNBC0y_din1IBlUVusU,2983
-bakefile-0.0.10.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-bakefile-0.0.10.dist-info/entry_points.txt,sha256=Ecvvh7BYHCPJ0UdntrDc3Od6AZdRPXN5Z7o_7ok_0Qw,107
-bakefile-0.0.10.dist-info/METADATA,sha256=sb-rcoJxanUjkn2dA-9ZfOg0aaXdlVF4ys-ATVVjuuk,2368
-bakefile-0.0.10.dist-info/RECORD,,
+bakelib/space/base.py,sha256=7vwVw19hkPimvamvTVySkc7Ndk8san3EF_5pg-8jf7w,6260
+bakelib/space/lib.py,sha256=MZnS_vP9zxalRE_eFb-fkW5NU5-6l8w8Rsz63PMCVS8,5617
+bakelib/space/python.py,sha256=o7t46DnBOcHf_bcJ8HOhiisjMf-UQsWCcykgLYxffu4,3400
+bakelib/space/python_lib.py,sha256=kkfdoMOWMX_qP3uGafQbLXy5NFbvv4ZKwmOXrgzH6Cs,2729
+bakelib/space/utils.py,sha256=Mp82CgpNMeG76slXaDs9GXa1r_ugoiJICvpsOaH_2tg,3206
+bakefile-0.0.11.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+bakefile-0.0.11.dist-info/entry_points.txt,sha256=Ecvvh7BYHCPJ0UdntrDc3Od6AZdRPXN5Z7o_7ok_0Qw,107
+bakefile-0.0.11.dist-info/METADATA,sha256=sDQXFSpH61wMHVp8mBsWgNzXLJWMR1upvBP3wsEMu9E,2464
+bakefile-0.0.11.dist-info/RECORD,,

{bakefile-0.0.10.dist-info → bakefile-0.0.11.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.26
+Generator: uv 0.9.28
 Root-Is-Purelib: true
 Tag: py3-none-any

bakelib/__init__.py

@@ -9,6 +9,7 @@ from bakelib.environ import (
 )
 from bakelib.space.base import BaseSpace
 from bakelib.space.python import PythonSpace
+from bakelib.space.python_lib import PythonLibSpace
 
 __all__ = [
     "BaseEnv",
@@ -17,6 +18,7 @@ __all__ = [
     "EnvBakebook",
     "GcpLandingZoneEnv",
     "ProdEnvBakebook",
+    "PythonLibSpace",
     "PythonSpace",
     "StagingEnvBakebook",
     "get_bakebook",

bakelib/refreshable_cache/__init__.py

@@ -0,0 +1,17 @@
+from bakelib.refreshable_cache.cache import (
+    ChainedCache,
+    KeyringCache,
+    MemoryCache,
+    NullCache,
+    RefreshableCache,
+)
+from bakelib.refreshable_cache.exceptions import RefreshNeededError
+
+__all__ = [
+    "ChainedCache",
+    "KeyringCache",
+    "MemoryCache",
+    "NullCache",
+    "RefreshNeededError",
+    "RefreshableCache",
+]

bakelib/refreshable_cache/cache.py

@@ -0,0 +1,250 @@
+import contextlib
+import functools
+import inspect
+import logging
+import time
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, ClassVar, Generic, ParamSpec, TypeVar
+
+import keyring as kr
+from keyring.errors import PasswordDeleteError
+from pydantic import BaseModel, TypeAdapter
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_none
+
+from bakelib.refreshable_cache.exceptions import RefreshNeededError
+
+if TYPE_CHECKING:
+    from tenacity.stop import StopBaseT
+    from tenacity.wait import WaitBaseT
+
+
+logger = logging.getLogger(__name__)
+
+P = ParamSpec("P")
+F = TypeVar("F", bound=Callable[..., Any])
+T = TypeVar("T")
+CachedT = TypeVar("CachedT", covariant=True)
+
+
+class CacheEntry(BaseModel, Generic[CachedT]):
+    """Cache entry containing the cached value and timestamp."""
+
+    value: CachedT
+    timestamp: float
+
+
+DEFAULT_NAMESPACE = "bakelib.refreshable_cache"
+
+
+class RefreshableCache(ABC, Generic[CachedT]):
+    """Cache that can be refreshed when values expire or become invalid."""
+
+    RefreshNeededError: type[RefreshNeededError] = RefreshNeededError
+
+    def __init__(
+        self,
+        key: str,
+        fetch_fn: Callable[[], CachedT],
+        ttl: float | None = None,
+        namespace: str | None = None,
+        stop: "StopBaseT | None" = None,
+        wait: "WaitBaseT | None" = None,
+        cached_type: Any = None,
+    ) -> None:
+        self._key = key
+        self._fetch_fn = fetch_fn
+        self._ttl = ttl
+        self._namespace = namespace if namespace is not None else DEFAULT_NAMESPACE
+        self._stop = stop if stop is not None else stop_after_attempt(2)
+        self._wait = wait if wait is not None else wait_none()
+
+        # Determine cached type: explicit cached_type or infer from fetch_fn
+        if cached_type is not None:
+            return_type = cached_type
+        else:
+            return_type = inspect.signature(fetch_fn).return_annotation
+            if return_type is inspect.Parameter.empty:
+                msg = "fetch_fn must have a return type annotation or cached_type must be provided"
+                raise TypeError(msg)
+
+        self._adapter = TypeAdapter(CacheEntry[return_type])
+
+    def _get_full_key(self) -> str:
+        return f"{self._namespace}:{self._key}"
+
+    def _serialize_entry(self, value: CachedT) -> bytes:
+        entry = CacheEntry(value=value, timestamp=time.time())
+        return self._adapter.dump_json(entry)
+
+    def _deserialize_entry(self, data: bytes) -> CacheEntry[CachedT]:
+        return self._adapter.validate_json(data)
+
+    def _is_expired(self, timestamp: float) -> bool:
+        if self._ttl is None:
+            return False
+        return time.time() - timestamp > self._ttl
+
+    def get_value(self) -> CachedT:
+        cached = self._get_entry()
+        if cached is None:
+            logger.debug(f"Cache miss for key '{self._key}', fetching value")
+            return self._refresh()
+        if self._is_expired(cached.timestamp):
+            logger.debug(f"Cache expired for key '{self._key}', fetching fresh value")
+            return self._refresh()
+        logger.debug(f"Cache hit for key '{self._key}'")
+        return cached.value
+
+    def _refresh(self) -> CachedT:
+        logger.debug(f"Refreshing value for key '{self._key}'")
+        value = self._fetch_fn()
+        self.set(value)
+        return value
+
+    def catch_refresh(self, func: Callable[P, T]) -> Callable[P, T]:
+        @functools.wraps(func)
+        @retry(
+            stop=self._stop,
+            wait=self._wait,
+            retry=retry_if_exception_type(self.RefreshNeededError),
+            reraise=True,
+        )
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
+            try:
+                return func(*args, **kwargs)
+            except self.RefreshNeededError:
+                self.delete()
+                raise
+
+        return wrapper
+
+    @abstractmethod
+    def _get_entry(self) -> CacheEntry[CachedT] | None: ...
+
+    @abstractmethod
+    def set(self, value: CachedT) -> None: ...
+
+    @abstractmethod
+    def delete(self) -> None: ...
+
+
+class KeyringCache(RefreshableCache[CachedT]):
+    """Cache using system keyring for persistent storage."""
+
+    def _get_entry(self) -> CacheEntry[CachedT] | None:
+        data = kr.get_password(self._namespace, self._key)
+        if data is None:
+            return None
+        return self._deserialize_entry(data.encode())
+
+    def set(self, value: CachedT) -> None:
+        data = self._serialize_entry(value).decode()
+        kr.set_password(self._namespace, self._key, data)
+
+    def delete(self) -> None:
+        with contextlib.suppress(PasswordDeleteError):
+            kr.delete_password(self._namespace, self._key)
+
+
+class MemoryCache(RefreshableCache[CachedT]):
+    """In-memory cache for ephemeral storage."""
+
+    _storage: ClassVar[dict[str, CacheEntry[CachedT]]] = {}
+
+    def _get_entry(self) -> CacheEntry[CachedT] | None:
+        entry = self._storage.get(self._get_full_key())
+        if entry is None:
+            return None
+        return entry
+
+    def set(self, value: CachedT) -> None:
+        self._storage[self._get_full_key()] = CacheEntry(value=value, timestamp=time.time())
+
+    def delete(self) -> None:
+        self._storage.pop(self._get_full_key(), None)
+
+
+class NullCache(RefreshableCache[CachedT]):
+    """Cache that doesn't cache anything (Null Object pattern).
+
+    Useful as a final fallback when you want to explicitly disable caching.
+    Reads always return None (triggering fetch), writes/deletes do nothing.
+    """
+
+    def _get_entry(self) -> CacheEntry[CachedT] | None:
+        return None
+
+    def set(self, value: CachedT) -> None:
+        pass
+
+    def delete(self) -> None:
+        pass
+
+
+class ChainedCache(RefreshableCache[CachedT]):
+    """Tries multiple backends in order.
+
+    Reads from the first backend that has data.
+    Writes to all backends (stops on first success).
+    """
+
+    _backends: list[RefreshableCache[CachedT]]
+
+    def __init__(
+        self,
+        backends: list[type[RefreshableCache[CachedT]]],
+        key: str,
+        fetch_fn: Callable[[], CachedT],
+        ttl: float | None = None,
+        namespace: str | None = None,
+        stop: "StopBaseT | None" = None,
+        wait: "WaitBaseT | None" = None,
+        cached_type: Any = None,
+    ) -> None:
+        super().__init__(
+            key=key,
+            fetch_fn=fetch_fn,
+            ttl=ttl,
+            namespace=namespace,
+            stop=stop,
+            wait=wait,
+            cached_type=cached_type,
+        )
+        self._backends = [
+            backend(
+                key=key,
+                fetch_fn=fetch_fn,
+                ttl=ttl,
+                namespace=namespace,
+                stop=stop,
+                wait=wait,
+                cached_type=cached_type,
+            )
+            for backend in backends
+        ]
+
+    def _get_entry(self) -> CacheEntry[CachedT] | None:
+        for backend in self._backends:
+            try:
+                entry = backend._get_entry()
+                if entry is not None:
+                    return entry
+            except Exception:
+                continue
+        return None
+
+    def set(self, value: CachedT) -> None:
+        for backend in self._backends:
+            try:
+                backend.set(value)
+                return
+            except Exception:
+                continue
+
+    def delete(self) -> None:
+        for backend in self._backends:
+            try:
+                backend.delete()
+            except Exception:
+                continue

bakelib/refreshable_cache/exceptions.py

@@ -0,0 +1,2 @@
+class RefreshNeededError(Exception):
+    """Raised when a cached value needs to be refreshed."""