tmpkit 1.0.0__tar.gz → 1.1.0__tar.gz

{tmpkit-1.0.0 → tmpkit-1.1.0}/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -59,7 +59,7 @@ body:
     id: tmpkit-version
     attributes:
       label: tmpkit Version
-      placeholder: "0.1.0"
+      placeholder: "1.1.0"
     validations:
       required: true
 

{tmpkit-1.0.0 → tmpkit-1.1.0}/.github/dependabot.yml

@@ -1,7 +1,7 @@
 version: 2
 updates:
   - package-ecosystem: pip
-    directory: /
+    directory: "/"
     schedule:
       interval: weekly
       day: monday
@@ -14,7 +14,7 @@ updates:
       include: scope
 
   - package-ecosystem: github-actions
-    directory: /
+    directory: "/"
     schedule:
       interval: weekly
       day: monday

{tmpkit-1.0.0 → tmpkit-1.1.0}/.github/workflows/ci.yml

@@ -13,8 +13,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install dev deps
@@ -36,8 +36,8 @@ jobs:
         python-version: ["3.11", "3.12", "3.13", "3.14"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dev deps
@@ -46,7 +46,7 @@ jobs:
         run: pytest --cov=tmpkit --cov-report=xml --cov-branch
       - name: Upload coverage
         if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
-        uses: codecov/codecov-action@v4
+        uses: codecov/codecov-action@v7
         with:
           files: ./coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}

{tmpkit-1.0.0 → tmpkit-1.1.0}/.github/workflows/release.yml

@@ -14,8 +14,8 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@v7
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install build
@@ -23,7 +23,7 @@ jobs:
       - name: Build dist
         run: python -m build
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -35,7 +35,7 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -48,8 +48,8 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/download-artifact@v4
+      - uses: actions/checkout@v7
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -88,12 +88,25 @@ jobs:
     needs: publish-pypi
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v7
         with:
           python-version: "3.13"
       - name: Install from PyPI
         run: |
           VERSION="${GITHUB_REF_NAME#v}"
-          pip install "tmpkit==${VERSION}"
+          # PyPI indexing can lag behind publication; retry until available.
+          for i in $(seq 1 12); do
+            if pip install "tmpkit==${VERSION}" 2>/dev/null; then
+              echo "Installed tmpkit==${VERSION} after ${i} attempt(s)."
+              break
+            fi
+            echo "Attempt ${i}: tmpkit==${VERSION} not yet indexed on PyPI. Retrying in 15s..."
+            sleep 15
+          done
+          INSTALLED="$(python -c 'import importlib.metadata; print(importlib.metadata.version("tmpkit"))' 2>/dev/null)"
+          [ "$INSTALLED" = "$VERSION" ] || {
+            echo "ERROR: expected tmpkit==${VERSION}, got '${INSTALLED:-not installed}' after 3 minutes."
+            exit 1
+          }
       - name: Smoke test
         run: python -c "from tmpkit import temp_file, temp_dir; print('ok')"

{tmpkit-1.0.0 → tmpkit-1.1.0}/.pre-commit-config.yaml

@@ -1,12 +1,12 @@
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.6.0
+    rev: v0.16.1
     hooks:
       - id: ruff
         args: [--fix]
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.0
+    rev: v2.3.1
     hooks:
       - id: mypy
         additional_dependencies: []

{tmpkit-1.0.0 → tmpkit-1.1.0}/CHANGELOG.md

@@ -5,31 +5,64 @@ All notable changes to tmpkit will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.1.0] - 2026-10-07
 
 ### Added
 
-- Nothing yet.
+- `keep=True` and `cleanup_hook=` parameters on `atomic_write()` (sync and async).
+- `cleanup_hook=` parameter on `@temp_dir()` and `@temp_file()` decorators.
+- `TempRecord` and `TempFileLike` are now exported from `tmpkit`.
+- `atomic_write()` fsyncs the destination directory after `os.replace()`
+  for rename durability (best-effort, no-op on Windows).
 
 ### Changed
 
-- Nothing yet.
+- `read`/`write`/`seek`/`tell`/`.path`/`__fspath__` before `__enter__` now
+  raise `RuntimeError` instead of `AssertionError`.
+- `@temp_file()` on a class now raises `TypeError` instead of silently
+  producing a broken function.
+- Class decoration with `@temp_dir()` now skips `staticmethod` and
+  `classmethod` members named `test_*` (they have no `self`).
+- Tests are now type-checked under `mypy --strict` with relaxed per-module
+  rules (`[[tool.mypy.overrides]]`); `tests/` is now a package.
+- Dev dependency floors bumped (`ruff>=0.16.0`, `mypy>=2.3.0`) and
+  pre-commit hook revisions aligned (`ruff v0.16.1`, `mypy v2.3.1`).
 
-### Deprecated
+### Fixed
 
-- Nothing yet.
+- Release workflow: the PyPI verify job used `pip show tmpkit==X.Y.Z`,
+  which always failed (`pip show` doesn't accept version specifiers).
+- Body exceptions are no longer masked by cleanup failures: a failing
+  `close()`/`flush()`/`fsync()`/`rmtree` during exception propagation
+  no longer replaces the original error.
+- `temp_dir(cwd=True)`: a non-`OSError` failure while restoring the
+  working directory no longer leaks the temp directory.
+- `atomic_write()` raises `IsADirectoryError` early when `dest` is an
+  existing directory.
+- `__repr__` now reports `kept` for temps kept via the close/flush
+  failure path.
+- `__enter__` re-entry fully resets internal state (`_path`, `_file`).
+- README: fixed the `temp_dir` `.keep()` example (it called `.keep()`
+  after the `with` block, which raises `RuntimeError`), corrected
+  `async_temp_file()` naming, and documented the process-global nature
+  of `cwd=True`.
 
 ### Removed
 
-- Nothing yet.
-
-### Fixed
+- `tests/conftest.py`: dropped the unused `assert_no_temps_left` fixture.
+- `TestWindowsNameMock` tests, which mocked `os.name` to `"nt"` — a no-op
+  on Windows (the only platform they ran on).
 
-- Nothing yet.
+## [1.0.1] - 2025-01-24
 
-### Security
+### Fixed
 
-- Nothing yet.
+- Bump `codecov/codecov-action` from v4 to v7 to resolve Node.js 20
+  deprecation warnings in CI.
+- Fix `test_windows.py` failures on Linux/macOS — `TestWindowsNameMock`
+  tests now skip on non-Windows platforms.
+- Fix macOS CI failures from `/var` symlink resolution — cwd tests now
+  compare resolved paths.
 
 ## [1.0.0] - 2025-01-24
 

{tmpkit-1.0.0 → tmpkit-1.1.0}/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-**conduct@mathiaspaulenko.com**.
+**mathias.paulenko@outlook.com**.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

{tmpkit-1.0.0 → tmpkit-1.1.0}/CONTRIBUTING.md

@@ -38,9 +38,11 @@ Thank you for your interest in contributing to tmpkit! This document describes t
 - **Type checker**: [mypy](https://mypy-lang.org/) with `--strict`.
 
   ```bash
-  mypy --strict tmpkit/
+  mypy --strict tmpkit/ tests/
   ```
 
+  Tests are checked with relaxed rules (see `[[tool.mypy.overrides]]` in `pyproject.toml`) since they exercise decorator-injected arguments and private internals.
+
 - **Python**: Target 3.11+ syntax. Use `from __future__ import annotations` in all modules.
 - **Imports**: Sorted by ruff (isort-compatible). Stdlib first, then third-party, then local.
 
@@ -108,8 +110,7 @@ tmpkit/
 │   ├── unit/            # Unit tests
 │   ├── integration/     # Integration tests
 │   └── e2e/             # End-to-end tests
-├── pyproject.toml       # Build config, tool config
-└── ref/                 # Internal design docs (not shipped)
+└── pyproject.toml       # Build config, tool config
 ```
 
 ## Reporting Issues

{tmpkit-1.0.0 → tmpkit-1.1.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Mathias Paulenko
+Copyright (c) 2025-2026 Mathias Paulenko
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{tmpkit-1.0.0 → tmpkit-1.1.0}/PKG-INFO

@@ -1,16 +1,16 @@
 Metadata-Version: 2.5
 Name: tmpkit
-Version: 1.0.0
+Version: 1.1.0
 Summary: Ergonomic tempfile & tempdir context managers with auto-cleanup, atomic writes, async support, and zero dependencies.
 Project-URL: Homepage, https://github.com/MathiasPaulenko/tmpkit
 Project-URL: Repository, https://github.com/MathiasPaulenko/tmpkit
 Project-URL: Issues, https://github.com/MathiasPaulenko/tmpkit/issues
 Project-URL: Changelog, https://github.com/MathiasPaulenko/tmpkit/blob/main/CHANGELOG.md
-Author: Mathias Paulenko
+Author-email: Mathias Paulenko <mathias.paulenko@outlook.com>
 License-Expression: MIT
 License-File: LICENSE
 Keywords: async,atomic,cleanup,context manager,filesystem,temp,tempfile,temporary,tmp
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
@@ -24,11 +24,11 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
-Requires-Dist: mypy>=1.11.0; extra == 'dev'
+Requires-Dist: mypy>=2.3.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
-Requires-Dist: ruff>=0.6.0; extra == 'dev'
+Requires-Dist: ruff>=0.16.0; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # tmpkit
@@ -39,7 +39,8 @@ Ergonomic tempfile & tempdir context managers with auto-cleanup, atomic writes,
 [![PyPI](https://img.shields.io/pypi/v/tmpkit)](https://pypi.org/project/tmpkit/)
 [![Python](https://img.shields.io/pypi/pyversions/tmpkit)](https://pypi.org/project/tmpkit/)
 [![License](https://img.shields.io/pypi/l/tmpkit)](https://github.com/MathiasPaulenko/tmpkit/blob/main/LICENSE)
-[![Coverage](https://img.shields.io/codecov/c/github/MathiasPaulenko/tmpkit)](https://codecov.io/gh/MathiasPaulenko/tmpkit)
+[![Coverage](https://codecov.io/gh/MathiasPaulenko/tmpkit/graph/badge.svg)](https://codecov.io/gh/MathiasPaulenko/tmpkit)
+[![Downloads](https://img.shields.io/pypi/dm/tmpkit)](https://pypi.org/project/tmpkit/)
 
 ---
 
@@ -70,7 +71,7 @@ Ergonomic tempfile & tempdir context managers with auto-cleanup, atomic writes,
 
 ## Why tmpkit?
 
-Python's `tempfile` gives you the pieces but forces you to write cleanup boilerplate every time. tmpkit wraps it in ergonomic context managers that **guarantee cleanup** — with features nobody else offers.
+Python's `tempfile` gives you the pieces but forces you to write cleanup boilerplate every time. tmpkit wraps it in ergonomic context managers that **always attempt cleanup** on exit — with features nobody else offers.
 
 ```python
 # stdlib — verbose, easy to forget cleanup
@@ -82,7 +83,7 @@ try:
 finally:
     shutil.rmtree(tmpdir, ignore_errors=True)
 
-# tmpkit — one line, always cleans up
+# tmpkit — one line, cleans up on exit
 from tmpkit import temp_file
 with temp_file(suffix=".csv") as f:
     f.write(data)
@@ -113,7 +114,7 @@ This installs `pytest`, `pytest-asyncio`, `pytest-cov`, `ruff`, `mypy`, and `bui
 ```python
 from tmpkit import temp_file, temp_dir, atomic_write, async_temp_file
 
-# Temp file
+# Temp file (default mode is "w+b" — binary; use mode="w+" for str)
 with temp_file(suffix=".csv", prefix="myapp_") as f:
     f.write(data)
     # deleted on exit
@@ -143,7 +144,7 @@ with temp_file(dest="output.csv") as f:
 # Async
 async def main() -> None:
     async with async_temp_file(suffix=".json") as f:
-        await f.write(data)
+        await f.write(data)  # bytes by default; mode="w+" for str
 ```
 
 ---
@@ -163,7 +164,7 @@ async def main() -> None:
 - **`@temp_dir()` / `@temp_file()` decorators** — inject temps into functions and test classes.
 - **Close without delete** — file survives `close()`, deleted on context exit (Windows subprocess friendly).
 - **`.path` attribute** — `Path` object, no more `Path(f.name)` boilerplate.
-- **Async support** — `async with temp_file() as f:` with async I/O methods.
+- **Async support** — `async with async_temp_file() as f:` with async I/O methods.
 - **Windows-safe by default** — no `O_TEMPORARY` lock, `ignore_cleanup_errors=True`.
 - **Zero dependencies** — stdlib only.
 
@@ -182,7 +183,7 @@ with temp_file(
     dir: str | Path | None = None,    # parent directory
     mode: str = "w+b",                # open mode
     content: str | bytes | None = None,  # pre-populate
-    dest: str | Path | None = None,   # move here on success
+    dest: str | Path | None = None,   # move here on success (parent must exist at exit)
     keep: bool = False,               # always keep
     keep_on_error: bool = False,      # keep only on exception
     ignore_cleanup_errors: bool = True,
@@ -225,12 +226,12 @@ with temp_dir(
 td = temp_dir()
 with td as d:
     (d / "file.txt").write_text("hello")
-td.keep()           # runtime decision to keep
+    td.keep()       # runtime decision to keep (must be inside the block)
 ```
 
-**Returns:** A `Path` object (the temp directory path) with `/` operator support. To call `.keep()`, use the context manager object directly (see example above).
+**Returns:** A `Path` object (the temp directory path) with `/` operator support. To call `.keep()`, use the context manager object directly (see example above) — it must be called **inside** the `with` block; calling it after exit raises `RuntimeError`.
 
-**`cwd=True`:** Changes the working directory to the temp dir on `__enter__`, restores the original on `__exit__`.
+**`cwd=True`:** Changes the working directory to the temp dir on `__enter__`, restores the original on `__exit__`. Warning: `os.chdir` is process-global — do not use `cwd=True` from multiple threads or concurrent async tasks.
 
 ### `atomic_write()`
 
@@ -245,8 +246,10 @@ with atomic_write(
     prefix: str | None = None,
     suffix: str = ".tmp",
     fsync: bool = True,               # fsync before rename
+    keep: bool = False,               # keep temp, dest untouched
     keep_on_error: bool = False,
     ignore_cleanup_errors: bool = True,
+    cleanup_hook: Callable[[Path], None] | None = None,
 ) as f:
     f.write(data)
 # on success: atomically renamed to dest
@@ -255,6 +258,10 @@ with atomic_write(
 
 Writes to a temp file in `dest`'s parent directory, then atomically replaces `dest` via `os.replace()` on success. On error, the temp is cleaned up and `dest` is left untouched.
 
+**Note:** with `keep=True`, `.keep()`, `keep_on_error=True` + exception, or `DEBUG=1`, the temp file is kept and **the replace is skipped** — `dest` is left untouched even on success.
+
+**Validation on enter:** raises `IsADirectoryError` if `dest` is an existing directory, `FileNotFoundError` if `dest`'s parent doesn't exist, and `NotADirectoryError` if the parent exists but isn't a directory — before writing anything.
+
 ### `@temp_dir()` Decorator
 
 ```python
@@ -281,9 +288,9 @@ class TestMyApp:
         assert self.tmpdir.exists()
 ```
 
-**Decorator defaults:** `cwd=True` (unlike the context manager where `cwd=False` by default).
+**Decorator defaults:** `cwd=True` (unlike the context manager where `cwd=False` by default). Accepts the same parameters as `temp_dir()`, including `cleanup_hook`. Only plain functions and classes — decorating a single method injects the temp path in place of `self`.
 
-**Class decoration:** Each method starting with `test_` is wrapped. The temp dir is available as `self.tmpdir`. Works with both sync and async test methods.
+**Class decoration:** Each method starting with `test_` is wrapped (`staticmethod`/`classmethod` members are skipped). The temp dir is available as `self.tmpdir`. Works with both sync and async test methods.
 
 ### `@temp_file()` Decorator
 
@@ -304,7 +311,7 @@ async def process_async(f, data: str) -> None:
     await f.write(data)
 ```
 
-The temp file object is injected as the **first positional argument**.
+The temp file object is injected as the **first positional argument**. Accepts the same parameters as `temp_file()`, including `cleanup_hook`. Plain functions only — decorating a class raises `TypeError`.
 
 ### `temp_registry`
 
@@ -340,7 +347,7 @@ temp_registry.clear_history()
 temp_registry.disable()
 ```
 
-**`TempRecord` fields:**
+**`TempRecord`** is importable for type annotations: `from tmpkit import TempRecord`. Fields:
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -352,6 +359,8 @@ temp_registry.disable()
 
 **Thread-safe:** All operations are protected by `threading.Lock`.
 
+**Note:** records accumulate for the lifetime of the process. In long-running applications, call `temp_registry.clear_history()` periodically (or `reset()`) to bound memory usage.
+
 ### Async API
 
 All sync APIs have async counterparts with identical parameters:
@@ -384,7 +393,7 @@ Async file objects support `await f.read()`, `await f.write()`, `await f.seek()`
 | `DEBUG` | `1` | Same as `TMPKIT_DEBUG=1` (fallback) |
 | `TMPKIT_REGISTRY` | `1` | Enable `temp_registry` at import time |
 
-`TMPKIT_DEBUG` takes precedence over `DEBUG`.
+`TMPKIT_DEBUG` takes precedence over `DEBUG`. Since `DEBUG` is a common variable name in other tools, you can set `TMPKIT_DEBUG=0` to explicitly disable keep-all even when `DEBUG=1` is present.
 
 ---
 
@@ -431,6 +440,11 @@ with temp_file(cleanup_hook=my_hook) as f:
     f.write(data)
 # hook is called, then standard cleanup runs
 
+# Hook also runs when the temp is moved via dest=
+with temp_file(dest="output.csv", cleanup_hook=my_hook) as f:
+    f.write(data)
+# hook is called, then temp is moved to output.csv
+
 # Hook is called even on exceptions
 with temp_file(cleanup_hook=my_hook) as f:
     raise RuntimeError("oops")
@@ -503,4 +517,4 @@ See [CHANGELOG.md](CHANGELOG.md) for a full list of changes.
 
 ## License
 
-[MIT](LICENSE) — Copyright (c) 2025 Mathias Paulenko
+[MIT](LICENSE) — Copyright (c) 2025-2026 Mathias Paulenko

{tmpkit-1.0.0 → tmpkit-1.1.0}/README.md

@@ -6,7 +6,8 @@ Ergonomic tempfile & tempdir context managers with auto-cleanup, atomic writes,
 [![PyPI](https://img.shields.io/pypi/v/tmpkit)](https://pypi.org/project/tmpkit/)
 [![Python](https://img.shields.io/pypi/pyversions/tmpkit)](https://pypi.org/project/tmpkit/)
 [![License](https://img.shields.io/pypi/l/tmpkit)](https://github.com/MathiasPaulenko/tmpkit/blob/main/LICENSE)
-[![Coverage](https://img.shields.io/codecov/c/github/MathiasPaulenko/tmpkit)](https://codecov.io/gh/MathiasPaulenko/tmpkit)
+[![Coverage](https://codecov.io/gh/MathiasPaulenko/tmpkit/graph/badge.svg)](https://codecov.io/gh/MathiasPaulenko/tmpkit)
+[![Downloads](https://img.shields.io/pypi/dm/tmpkit)](https://pypi.org/project/tmpkit/)
 
 ---
 
@@ -37,7 +38,7 @@ Ergonomic tempfile & tempdir context managers with auto-cleanup, atomic writes,
 
 ## Why tmpkit?
 
-Python's `tempfile` gives you the pieces but forces you to write cleanup boilerplate every time. tmpkit wraps it in ergonomic context managers that **guarantee cleanup** — with features nobody else offers.
+Python's `tempfile` gives you the pieces but forces you to write cleanup boilerplate every time. tmpkit wraps it in ergonomic context managers that **always attempt cleanup** on exit — with features nobody else offers.
 
 ```python
 # stdlib — verbose, easy to forget cleanup
@@ -49,7 +50,7 @@ try:
 finally:
     shutil.rmtree(tmpdir, ignore_errors=True)
 
-# tmpkit — one line, always cleans up
+# tmpkit — one line, cleans up on exit
 from tmpkit import temp_file
 with temp_file(suffix=".csv") as f:
     f.write(data)
@@ -80,7 +81,7 @@ This installs `pytest`, `pytest-asyncio`, `pytest-cov`, `ruff`, `mypy`, and `bui
 ```python
 from tmpkit import temp_file, temp_dir, atomic_write, async_temp_file
 
-# Temp file
+# Temp file (default mode is "w+b" — binary; use mode="w+" for str)
 with temp_file(suffix=".csv", prefix="myapp_") as f:
     f.write(data)
     # deleted on exit
@@ -110,7 +111,7 @@ with temp_file(dest="output.csv") as f:
 # Async
 async def main() -> None:
     async with async_temp_file(suffix=".json") as f:
-        await f.write(data)
+        await f.write(data)  # bytes by default; mode="w+" for str
 ```
 
 ---
@@ -130,7 +131,7 @@ async def main() -> None:
 - **`@temp_dir()` / `@temp_file()` decorators** — inject temps into functions and test classes.
 - **Close without delete** — file survives `close()`, deleted on context exit (Windows subprocess friendly).
 - **`.path` attribute** — `Path` object, no more `Path(f.name)` boilerplate.
-- **Async support** — `async with temp_file() as f:` with async I/O methods.
+- **Async support** — `async with async_temp_file() as f:` with async I/O methods.
 - **Windows-safe by default** — no `O_TEMPORARY` lock, `ignore_cleanup_errors=True`.
 - **Zero dependencies** — stdlib only.
 
@@ -149,7 +150,7 @@ with temp_file(
     dir: str | Path | None = None,    # parent directory
     mode: str = "w+b",                # open mode
     content: str | bytes | None = None,  # pre-populate
-    dest: str | Path | None = None,   # move here on success
+    dest: str | Path | None = None,   # move here on success (parent must exist at exit)
     keep: bool = False,               # always keep
     keep_on_error: bool = False,      # keep only on exception
     ignore_cleanup_errors: bool = True,
@@ -192,12 +193,12 @@ with temp_dir(
 td = temp_dir()
 with td as d:
     (d / "file.txt").write_text("hello")
-td.keep()           # runtime decision to keep
+    td.keep()       # runtime decision to keep (must be inside the block)
 ```
 
-**Returns:** A `Path` object (the temp directory path) with `/` operator support. To call `.keep()`, use the context manager object directly (see example above).
+**Returns:** A `Path` object (the temp directory path) with `/` operator support. To call `.keep()`, use the context manager object directly (see example above) — it must be called **inside** the `with` block; calling it after exit raises `RuntimeError`.
 
-**`cwd=True`:** Changes the working directory to the temp dir on `__enter__`, restores the original on `__exit__`.
+**`cwd=True`:** Changes the working directory to the temp dir on `__enter__`, restores the original on `__exit__`. Warning: `os.chdir` is process-global — do not use `cwd=True` from multiple threads or concurrent async tasks.
 
 ### `atomic_write()`
 
@@ -212,8 +213,10 @@ with atomic_write(
     prefix: str | None = None,
     suffix: str = ".tmp",
     fsync: bool = True,               # fsync before rename
+    keep: bool = False,               # keep temp, dest untouched
     keep_on_error: bool = False,
     ignore_cleanup_errors: bool = True,
+    cleanup_hook: Callable[[Path], None] | None = None,
 ) as f:
     f.write(data)
 # on success: atomically renamed to dest
@@ -222,6 +225,10 @@ with atomic_write(
 
 Writes to a temp file in `dest`'s parent directory, then atomically replaces `dest` via `os.replace()` on success. On error, the temp is cleaned up and `dest` is left untouched.
 
+**Note:** with `keep=True`, `.keep()`, `keep_on_error=True` + exception, or `DEBUG=1`, the temp file is kept and **the replace is skipped** — `dest` is left untouched even on success.
+
+**Validation on enter:** raises `IsADirectoryError` if `dest` is an existing directory, `FileNotFoundError` if `dest`'s parent doesn't exist, and `NotADirectoryError` if the parent exists but isn't a directory — before writing anything.
+
 ### `@temp_dir()` Decorator
 
 ```python
@@ -248,9 +255,9 @@ class TestMyApp:
         assert self.tmpdir.exists()
 ```
 
-**Decorator defaults:** `cwd=True` (unlike the context manager where `cwd=False` by default).
+**Decorator defaults:** `cwd=True` (unlike the context manager where `cwd=False` by default). Accepts the same parameters as `temp_dir()`, including `cleanup_hook`. Only plain functions and classes — decorating a single method injects the temp path in place of `self`.
 
-**Class decoration:** Each method starting with `test_` is wrapped. The temp dir is available as `self.tmpdir`. Works with both sync and async test methods.
+**Class decoration:** Each method starting with `test_` is wrapped (`staticmethod`/`classmethod` members are skipped). The temp dir is available as `self.tmpdir`. Works with both sync and async test methods.
 
 ### `@temp_file()` Decorator
 
@@ -271,7 +278,7 @@ async def process_async(f, data: str) -> None:
     await f.write(data)
 ```
 
-The temp file object is injected as the **first positional argument**.
+The temp file object is injected as the **first positional argument**. Accepts the same parameters as `temp_file()`, including `cleanup_hook`. Plain functions only — decorating a class raises `TypeError`.
 
 ### `temp_registry`
 
@@ -307,7 +314,7 @@ temp_registry.clear_history()
 temp_registry.disable()
 ```
 
-**`TempRecord` fields:**
+**`TempRecord`** is importable for type annotations: `from tmpkit import TempRecord`. Fields:
 
 | Field | Type | Description |
 | --- | --- | --- |
@@ -319,6 +326,8 @@ temp_registry.disable()
 
 **Thread-safe:** All operations are protected by `threading.Lock`.
 
+**Note:** records accumulate for the lifetime of the process. In long-running applications, call `temp_registry.clear_history()` periodically (or `reset()`) to bound memory usage.
+
 ### Async API
 
 All sync APIs have async counterparts with identical parameters:
@@ -351,7 +360,7 @@ Async file objects support `await f.read()`, `await f.write()`, `await f.seek()`
 | `DEBUG` | `1` | Same as `TMPKIT_DEBUG=1` (fallback) |
 | `TMPKIT_REGISTRY` | `1` | Enable `temp_registry` at import time |
 
-`TMPKIT_DEBUG` takes precedence over `DEBUG`.
+`TMPKIT_DEBUG` takes precedence over `DEBUG`. Since `DEBUG` is a common variable name in other tools, you can set `TMPKIT_DEBUG=0` to explicitly disable keep-all even when `DEBUG=1` is present.
 
 ---
 
@@ -398,6 +407,11 @@ with temp_file(cleanup_hook=my_hook) as f:
     f.write(data)
 # hook is called, then standard cleanup runs
 
+# Hook also runs when the temp is moved via dest=
+with temp_file(dest="output.csv", cleanup_hook=my_hook) as f:
+    f.write(data)
+# hook is called, then temp is moved to output.csv
+
 # Hook is called even on exceptions
 with temp_file(cleanup_hook=my_hook) as f:
     raise RuntimeError("oops")
@@ -470,4 +484,4 @@ See [CHANGELOG.md](CHANGELOG.md) for a full list of changes.
 
 ## License
 
-[MIT](LICENSE) — Copyright (c) 2025 Mathias Paulenko
+[MIT](LICENSE) — Copyright (c) 2025-2026 Mathias Paulenko

{tmpkit-1.0.0 → tmpkit-1.1.0}/SECURITY.md

@@ -4,15 +4,15 @@
 
 | Version | Supported          |
 |---------|--------------------|
-| 0.1.x   | :white_check_mark: |
-| < 0.1   | :x:                |
+| 1.0.x   | :white_check_mark: |
+| < 1.0   | :x:                |
 
 ## Reporting a Vulnerability
 
 If you discover a security vulnerability in tmpkit, please report it responsibly.
 
 1. **Do NOT open a public GitHub issue.**
-2. Email **security@mathiaspaulenko.com** with a description of the vulnerability and, if possible, a proof of concept.
+2. Email **mathias.paulenko@outlook.com** with a description of the vulnerability and, if possible, a proof of concept.
 3. You will receive an acknowledgment within **48 hours**.
 4. We will investigate and, if confirmed, release a fix as soon as possible depending on severity.
 
@@ -27,5 +27,5 @@ If you discover a security vulnerability in tmpkit, please report it responsibly
 tmpkit is a zero-dependency library that wraps Python's `tempfile` module. The main security considerations are:
 
 - **Temp file permissions**: Uses `tempfile.mkstemp()` which creates files with restrictive permissions (0600 on Unix).
-- **Symlink attacks**: Uses `shutil.rmtree()` for directory cleanup. On Python 3.11+, this is protected against symlink attacks by default.
+- **Symlink attacks**: Uses `shutil.rmtree()` for directory cleanup, which includes partial protections against symlink-based races on Python 3.11+. Avoid pointing `dir` at world-writable locations you don't control.
 - **Path traversal**: Temp paths are generated by the stdlib and are not user-controlled beyond `suffix`, `prefix`, and `dir` parameters. If you pass a user-controlled `dir`, validate it.