cascade-cms-rest 3.2.2__tar.gz → 3.4.0__tar.gz

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/.github/workflows/release.yml

@@ -6,7 +6,7 @@ on:
       - "v*.*.*"
 
 permissions:
-  contents: write
+  contents: read
   id-token: write
 
 jobs:
@@ -28,20 +28,6 @@ jobs:
           name: dist
           path: dist/
 
-  release:
-    needs: build
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/download-artifact@v4
-        with:
-          name: dist
-          path: dist/
-      - name: Create GitHub release
-        uses: softprops/action-gh-release@v2
-        with:
-          files: dist/*
-          generate_release_notes: true
-
   publish:
     name: Publish to PyPI
     needs: build

cascade_cms_rest-3.4.0/AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md
+
+`cascade-cms-rest` — a typed, async REST client for Hannon Hill Cascade CMS 8.
+Library source is `src/cascade_cms/`.
+
+
+## Repo commands
+
+```bash
+pip install -e ".[dev]"
+pytest
+ruff check .
+mypy src/
+```
+
+CI runs `ruff check .`, `mypy src/`, and `pytest`. Run all three before
+considering a change to the library done.
+
+## Writing scripts that use this library
+
+Script-writing skills (`cascade-script-writer`/`cascade-script-writer-lite`)
+and the MCP server both moved to their own repo, `cascade-cms-tools`
+(sibling to this one), so this library repo stays dependency-light and
+focused on `src/cascade_cms/`. See that repo's `AGENTS.md` for the
+skill-authoring workflow and how to rebuild release artifacts — both depend
+on the *published* `cascade-cms-rest` package, not a local copy, so nothing
+here needs to stay in sync with them beyond tagging a release.
+
+## Logging and console output
+
+- `CascadeWrapperBase(environmentVariables, debug=None, *, exit_on_failure=True,
+  log_dir=None)` — there is no response cache and no `configurationVariables`.
+- Status lines (`[INIT]`, `[LOG]: <path>`, `[DONE]`, the tally, `[EXIT]`, console `[ERROR]`)
+  go to **stderr**; stdout belongs to the caller's script.
+- The logfile records the tally line and, last, `[EXIT-CODE]: <outcome>` (see the README's
+  Logging section for the outcomes). Agents verify a run by reading the logfile at the
+  `[LOG]` path, not by capturing console output.
+- `log_dir` (explicit parameter) beats a debug config's `log_dir`; default `./logs`. Log
+  filenames are `{SERVER}[_debug]_{timestamp}_{n}.log`.
+- Successful writes log `[RESULT]: ...` automatically; scripts log `[NOTE]: <text>` with
+  `from cascade_cms.utils import script_log` then `script_log.note(text)` inside the `with`
+  block (formats in the README). Process-pool callbacks return values and the main script notes
+  them.
+- Package layout: `cascade_cms/utils/` holds `operation_logger.py`, `redaction.py` and
+  `script_notes.py`. `cascade_cms.operation_logger` and `cascade_cms.redaction` no longer exist
+  (no shim); `from cascade_cms import OperationLogger` still works.
+- The API bearer token is masked (`cascade_cms.utils.redaction.mask_token`) wherever it could surface.
+
+## Maintaining the CHANGELOG
+
+Each section in `CHANGELOG.md` should include a note at the bottom listing
+which files were touched. For example:
+
+```markdown
+### Fixed
+- Fixed async callback execution order (affects callback chains)
+- Fixed nested payload aliasing issue
+
+**Files changed:** `src/cascade_cms/operations.py`, `src/cascade_cms/cmstypes.py`
+```
+
+This helps readers quickly understand the scope of changes and identify which
+parts of the library were affected.

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.4.0]
+
+### Added
+- **`[RESULT]` lines:** each successful write operation now writes one line to the logfile, after its chain's pipeline line, naming what Cascade returned (`create` → new type, id and path; other writes → operation, target and `succeeded`). Reads and failed writes write none. See the README for the exact format.
+- **`script_log.note(text)`** (`from cascade_cms.utils import script_log`): writes `[NOTE]: <text>` to the active run's logfile. A stateless singleton routed through a `ContextVar` set by `CascadeWrapperBase`'s `with` block, so concurrent wrappers on different threads keep their notes separate. Called outside a run it drops the note and emits a `RuntimeWarning`. API keys in the text are masked.
+- `cascade_cms/utils/` package.
+
+### Changed
+- **BREAKING: `cascade_cms.operation_logger` moved to `cascade_cms.utils.operation_logger`**, with no shim at the old path. `from cascade_cms import OperationLogger` still works.
+- **BREAKING: `cascade_cms.redaction` (new in 3.3.0) moved to `cascade_cms.utils.redaction`**, also with no shim.
+- Sync callbacks run in a thread pool now execute in a copy of the caller's context (neither `run_in_executor` nor `Executor.submit` copies it), so `script_log.note()` works from them. Process-pool callbacks are unchanged and cannot call `note()`.
+
+**Files changed:** `src/cascade_cms/utils/` (added: `__init__.py`, `script_notes.py`; moved: `operation_logger.py`, `redaction.py`), `src/cascade_cms/operations.py`, `src/cascade_cms/wrapper.py`, `src/cascade_cms/driver.py`, `src/cascade_cms/__init__.py`, `pyproject.toml`, `README.md`, `AGENTS.md`, `tests/test_result_lines.py` (added), `tests/test_script_log.py` (added), `tests/test_logging_exit.py`, `tests/test_operation_chains.py`, `tests/test_operation_logger.py`, `tests/test_redaction.py`, `tests/test_wrapper.py`
+
+## [3.3.0]
+
+### Removed
+- **BREAKING: response caching is removed entirely** (no persistent and no in-memory cache): `CacheHandler`, `default_cache_backend()`, `OperationLogger.log_cache_hit()` and `ResponseParser._cacheable`. No `./cache` directory is created.
+- **BREAKING: `configurationVariables` is removed from `CascadeWrapperBase`** with no deprecation period. `CascadeWrapperBase(environmentVariables, debug=None, *, exit_on_failure=True, log_dir=None)`; `exit_on_failure` is now keyword-only.
+- **BREAKING: `backendConfig` is removed from `CascadeCMSRestDriver`.**
+- **BREAKING: `python-dotenv` is no longer a dependency**, and `aiohttp-client-cache` is dropped. `aiohttp` is now a direct dependency (`>=3.14.3`).
+
+### Changed
+- **BREAKING: status lines go to stderr instead of stdout** (`[INIT]`, `[DEBUG]`, `[DONE]`, the tally, `[EXIT]`, console `[ERROR]`). Anything reading the tally from stdout must read stderr or the logfile.
+- **BREAKING: a non-200 HTTP status is now a `CascadeError` (category CASCADE, message `"<status> <reason>"`)**, no longer a NETWORK failure. The response body is never read or logged.
+- **BREAKING: `ResponseParser.serializer` is now required**; the `RuntimeWarning` branch is gone.
+- **BREAKING: `RequestExecutor.parser` is now required** (the unused default was removed). `RequestExecutor` is exported from `cascade_cms/__init__.py`.
+- Log filenames now include microseconds and a per-process serial (`{SERVER}[_debug]_{timestamp}_{n}.log`), so two wrappers created in the same second never share a file.
+- A batch-level failure's prefix follows its cause: `[NETWORK]` for network causes, `[CASCADE-REST-CMS]` otherwise.
+- `CascadeCMSRestDriver.close()` clears the closed event loop as the current loop.
+- Release process: the tag-triggered workflow no longer creates a GitHub release (PyPI publishing on tag push is unchanged, with `contents: read`), and `PUBLISHING.md` no longer has a manual `twine upload` step.
+
+### Added
+- `log_dir` keyword-only parameter on `CascadeWrapperBase` (normal and debug mode; created if missing; wins over a debug config's `log_dir`).
+- `[LOG]: <path>` is printed to stderr right after `[INIT]`.
+- The logfile records the tally line and a final `[EXIT-CODE]: <outcome>` line.
+- `cascade_cms.redaction.mask_token()`; the debug logfile masks the `Authorization` header to its last four characters (`Bearer ****abcd`).
+
+### Fixed
+- Each wrapper closes and releases its logfile handle on exit.
+- Verified (Python 3.12): Cascade's `Partitioned` session cookie no longer breaks requests now that the cache library is gone; no compatibility patch is needed in the library.
+
+**Files changed:** `src/cascade_cms/driver.py`, `src/cascade_cms/wrapper.py`, `src/cascade_cms/operation_logger.py`, `src/cascade_cms/cmstypes.py`, `src/cascade_cms/redaction.py` (added), `pyproject.toml`, `.github/workflows/release.yml`, `PUBLISHING.md`, `README.md`, `AGENTS.md`, `tests/test_driver.py`, `tests/test_non200.py` (added), `tests/test_redaction.py` (added), `tests/test_logging_exit.py` (added), `tests/edit_test.py`
+
 ## [3.2.2]
 
 ### Added

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/PKG-INFO

@@ -1,15 +1,14 @@
 Metadata-Version: 2.5
 Name: cascade-cms-rest
-Version: 3.2.2
+Version: 3.4.0
 Summary: A typed, async REST client for Hannon Hill Cascade CMS
 Project-URL: Homepage, https://github.com/Sharkdroid/py-cascade-cms
 Author: Keith Shark
 License-Expression: MIT
 License-File: LICENSE
 Requires-Python: >=3.12
-Requires-Dist: aiohttp-client-cache[sqlite]
+Requires-Dist: aiohttp>=3.14.3
 Requires-Dist: pydantic>=2
-Requires-Dist: python-dotenv
 Provides-Extra: dev
 Requires-Dist: build; extra == 'dev'
 Requires-Dist: mypy; extra == 'dev'
@@ -36,13 +35,8 @@ environment_variables = {
     "CASCADE_URL": "...",
     "SERVER": "prod",  # label used for logfile naming
 }
-configuration_variables = {
-    "cache_name": "./cache/cache.sqlite",
-    "allowed_codes": (200,),
-    "allowed_methods": ("GET",),
-}
 
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     identifier = IdentifierType(identifier="e868f539ac1001062cfa029c4c5df4d0", asset_type="folder")
     cascade.operations.read(identifier)
     results = cascade.submit_requests(Asset)
@@ -69,7 +63,7 @@ def rewrite(asset):
     asset.keywords = "updated"
     return asset
 
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     cascade.operations.read(page_a).edit(page_a, rewrite).publish(page_a)
     cascade.operations.read(page_b).then(report)
     cascade.operations.delete(old_page)
@@ -114,14 +108,17 @@ manager owns it end to end:
   server) — `__exit__` then never raises; read `.success`/`.failed` off the results yourself.
 - The logfile's `!ERROR:` line is prefixed `[NETWORK]` for a network-layer failure or
   `[CASCADE-REST-CMS]` for any other library-side failure; a `CascadeError` or a callback
-  exception gets no prefix.
+  exception gets no prefix. A batch-level failure takes the prefix that matches its cause.
+- Cascade always answers HTTP 200 with a JSON body; a non-200 status (an HTML page from the
+  server layer, e.g. `501 Not Implemented`) is reported as a `CascadeError` whose message is the
+  status code and reason. The HTML body is never read or logged.
 - At exit, the console always prints a tally: `"{failed} failed, {succeeded} succeeded"`,
   cumulative across every `submit_requests()` call in the session, with `": reference log for
   details"` appended only when at least one failure came from the API, the network, or the
-  library itself (not from a callback-only failure).
+  library itself (not from a callback-only failure). The tally is also written to the logfile.
 
 ```python
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     cascade.operations.read(identifier)
     results = cascade.submit_requests(Asset)
     for asset in results.success:
@@ -132,11 +129,24 @@ with CascadeWrapperBase(environment_variables, configuration_variables) as casca
 
 ### Logging
 
-`CascadeWrapperBase` accepts an optional third `debug` argument. Leaving it as `None`
-(the default) runs in **normal mode**: a minimal console (`[INIT]`/`[RUNNING]`/`Processed: n/N`/
-`[DONE]`/`[EXIT]`) plus a simple logfile at `./logs/{SERVER}_{timestamp}.log`. Passing a dict
+`CascadeWrapperBase` accepts an optional second `debug` argument. Leaving it as `None`
+(the default) runs in **normal mode**: a minimal console (`[INIT]`/`[LOG]`/`[RUNNING]`/`n/N succeeded`/
+`[DONE]`/`[EXIT]`) plus a simple logfile at `./logs/{SERVER}_{timestamp}_{n}.log`. Passing a dict
 switches to **debug mode**: a quiet console and a verbose, nested logfile at
-`./logs/{SERVER}_debug_{timestamp}.log` describing every request, response, callback, and error.
+`./logs/{SERVER}_debug_{timestamp}_{n}.log` describing every request, response, callback, and error.
+Each wrapper gets its own file, even when two are created in the same second.
+
+- **Status lines go to stderr**, not stdout (`[INIT]`, `[LOG]`, `[DONE]`, the tally, `[EXIT]`,
+  console `[ERROR]` lines), so stdout stays free for your script's own output.
+- **`[LOG]: <path>`** is printed right after `[INIT]`, giving the path of this run's logfile.
+- **`log_dir=`** (keyword-only) sets the log directory in normal and debug mode; it is created if
+  missing and defaults to `./logs`. If a debug config also sets `log_dir`, the parameter wins.
+- **`[EXIT-CODE]:`** is the last line written to the logfile: `0` for a clean run, `1` when the
+  script ends with a failure, `1 (callback exception: <Type>)` / `1 (uncaught exception: <Type>)`
+  when an exception ends it, or `n/a (exit_on_failure disabled)`. Read the logfile for the tally
+  and exit code rather than capturing console output.
+- In debug mode with `show_network_headers`, the `Authorization` header is masked to its last four
+  characters (`Bearer ****abcd`).
 
 ```python
 debug_config = {
@@ -150,10 +160,51 @@ debug_config = {
     "response_line_limit": 8,   # -1 = dump full response body
 }
 
-with CascadeWrapperBase(environment_variables, configuration_variables, debug=debug_config) as cascade:
+with CascadeWrapperBase(environment_variables, debug=debug_config) as cascade:
     ...
 ```
 
+#### `[RESULT]` and `[NOTE]` lines
+
+Two fixed line types make the logfile carry what a script *did*, so an agent (or you) can read it
+instead of capturing stdout:
+
+- **`[RESULT]: ...`** is written **automatically**, once per successful write operation
+  (`create`, `edit`, `delete`, `copy`, `move`, `publish`, `checkIn`, `checkOut`, `siteCopy`,
+  `editAccessRights`, `editWorkflowSettings`, `performWorkflowTransition`, `markMessage`,
+  `deleteMessage`, `editPreference`), right after that chain's pipeline line. Reads, searches and
+  lists write none; failed writes and failed items of a list create/edit write none. A write that
+  succeeded stays on record even if a later step of its chain failed.
+
+  ```
+  [RESULT]: create page 5f1a0000000000000000000000c90d00 /_dev/testing/testbed2-copy
+  [RESULT]: delete page 1a2b0000000000000000000000009f00 succeeded
+  [RESULT]: siteCopy succeeded
+  ```
+
+  `create` lines are `create <type> <id> [<path>]` (the new asset, as Cascade returned it; `<path>`
+  is the site-relative path when the payload gave `parent_folder_path`). Every other write is
+  `<operation> [<type> <id> <path>] succeeded`, naming the target (as many of the three as are
+  known); an operation with no identifier target is just `<operation> succeeded`. `<id>` is 32
+  hex characters and `<path>` starts with `/`.
+
+- **`[NOTE]: <text>`** is written **on purpose** by your script:
+
+  ```python
+  from cascade_cms.utils import script_log
+
+  with CascadeWrapperBase(environment_variables) as cascade:
+      script_log.note("will delete page 1a2b... /news/old-1")
+  ```
+
+  `script_log` is a stateless singleton that routes each note to the run whose `with` block is
+  active in the calling context, so wrappers open on different threads never mix notes. Notes must
+  be written **inside** the `with` block; outside it the note is dropped and a `RuntimeWarning` is
+  emitted. Newlines become spaces (one note = one line) and any occurrence of the API key is
+  masked. Thread-pool and async callbacks may call `note()` directly. **Process-pool callbacks
+  cannot** (another process, no active run): have them return values and note them in the main
+  script.
+
 All keys are required in debug mode — there are no inferred defaults, so you always know what
 you opted into.
 

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/PUBLISHING.md

@@ -74,21 +74,16 @@
    git push origin master --tags       # Push commits + all tags
    ```
 
-### 6. Build & Publish to PyPI
+### 6. Publishing Happens Automatically
 
-   **Build:**
-   ```bash
-   python -m build
-   ```
-   
-   This creates `dist/cascade_cms_rest-3.0.2-py3-none-any.whl` and `.tar.gz`
+   Pushing the `v*` tag (step 5) triggers the **Release** workflow
+   (`.github/workflows/release.yml`), which builds the sdist and wheel and
+   publishes them to PyPI. Do **not** run `twine upload` by hand: the tag
+   already publishes via CI, so a manual upload collides ("file already
+   exists"), and a stale local `dist/` would re-upload old versions.
 
-   **Publish:**
-   ```bash
-   twine upload dist/*
-   ```
-   
-   You'll be prompted for PyPI credentials (or use `.pypirc` config)
+   Watch the workflow run in the GitHub Actions tab, then verify on PyPI
+   (below). The workflow does not create a GitHub release.
 
 ## Verification
 
@@ -112,12 +107,10 @@ git commit -m "Bump version to 3.0.2"
 # 4. Create an annotated tag (v-prefix is convention)
 git tag -a v3.0.2 -m "Release version 3.0.2"
 
-# 5. Push commits and tags to GitHub
+# 5. Push commits and tags to GitHub; the tag push publishes to PyPI via CI
 git push origin master --tags
 
-# 6. Build and publish to PyPI
-python -m build
-twine upload dist/*
+# 6. Verify on PyPI (https://pypi.org/project/cascade-cms-rest/)
 ```
 
 ## Troubleshooting

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/README.md

@@ -15,13 +15,8 @@ environment_variables = {
     "CASCADE_URL": "...",
     "SERVER": "prod",  # label used for logfile naming
 }
-configuration_variables = {
-    "cache_name": "./cache/cache.sqlite",
-    "allowed_codes": (200,),
-    "allowed_methods": ("GET",),
-}
 
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     identifier = IdentifierType(identifier="e868f539ac1001062cfa029c4c5df4d0", asset_type="folder")
     cascade.operations.read(identifier)
     results = cascade.submit_requests(Asset)
@@ -48,7 +43,7 @@ def rewrite(asset):
     asset.keywords = "updated"
     return asset
 
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     cascade.operations.read(page_a).edit(page_a, rewrite).publish(page_a)
     cascade.operations.read(page_b).then(report)
     cascade.operations.delete(old_page)
@@ -93,14 +88,17 @@ manager owns it end to end:
   server) — `__exit__` then never raises; read `.success`/`.failed` off the results yourself.
 - The logfile's `!ERROR:` line is prefixed `[NETWORK]` for a network-layer failure or
   `[CASCADE-REST-CMS]` for any other library-side failure; a `CascadeError` or a callback
-  exception gets no prefix.
+  exception gets no prefix. A batch-level failure takes the prefix that matches its cause.
+- Cascade always answers HTTP 200 with a JSON body; a non-200 status (an HTML page from the
+  server layer, e.g. `501 Not Implemented`) is reported as a `CascadeError` whose message is the
+  status code and reason. The HTML body is never read or logged.
 - At exit, the console always prints a tally: `"{failed} failed, {succeeded} succeeded"`,
   cumulative across every `submit_requests()` call in the session, with `": reference log for
   details"` appended only when at least one failure came from the API, the network, or the
-  library itself (not from a callback-only failure).
+  library itself (not from a callback-only failure). The tally is also written to the logfile.
 
 ```python
-with CascadeWrapperBase(environment_variables, configuration_variables) as cascade:
+with CascadeWrapperBase(environment_variables) as cascade:
     cascade.operations.read(identifier)
     results = cascade.submit_requests(Asset)
     for asset in results.success:
@@ -111,11 +109,24 @@ with CascadeWrapperBase(environment_variables, configuration_variables) as casca
 
 ### Logging
 
-`CascadeWrapperBase` accepts an optional third `debug` argument. Leaving it as `None`
-(the default) runs in **normal mode**: a minimal console (`[INIT]`/`[RUNNING]`/`Processed: n/N`/
-`[DONE]`/`[EXIT]`) plus a simple logfile at `./logs/{SERVER}_{timestamp}.log`. Passing a dict
+`CascadeWrapperBase` accepts an optional second `debug` argument. Leaving it as `None`
+(the default) runs in **normal mode**: a minimal console (`[INIT]`/`[LOG]`/`[RUNNING]`/`n/N succeeded`/
+`[DONE]`/`[EXIT]`) plus a simple logfile at `./logs/{SERVER}_{timestamp}_{n}.log`. Passing a dict
 switches to **debug mode**: a quiet console and a verbose, nested logfile at
-`./logs/{SERVER}_debug_{timestamp}.log` describing every request, response, callback, and error.
+`./logs/{SERVER}_debug_{timestamp}_{n}.log` describing every request, response, callback, and error.
+Each wrapper gets its own file, even when two are created in the same second.
+
+- **Status lines go to stderr**, not stdout (`[INIT]`, `[LOG]`, `[DONE]`, the tally, `[EXIT]`,
+  console `[ERROR]` lines), so stdout stays free for your script's own output.
+- **`[LOG]: <path>`** is printed right after `[INIT]`, giving the path of this run's logfile.
+- **`log_dir=`** (keyword-only) sets the log directory in normal and debug mode; it is created if
+  missing and defaults to `./logs`. If a debug config also sets `log_dir`, the parameter wins.
+- **`[EXIT-CODE]:`** is the last line written to the logfile: `0` for a clean run, `1` when the
+  script ends with a failure, `1 (callback exception: <Type>)` / `1 (uncaught exception: <Type>)`
+  when an exception ends it, or `n/a (exit_on_failure disabled)`. Read the logfile for the tally
+  and exit code rather than capturing console output.
+- In debug mode with `show_network_headers`, the `Authorization` header is masked to its last four
+  characters (`Bearer ****abcd`).
 
 ```python
 debug_config = {
@@ -129,10 +140,51 @@ debug_config = {
     "response_line_limit": 8,   # -1 = dump full response body
 }
 
-with CascadeWrapperBase(environment_variables, configuration_variables, debug=debug_config) as cascade:
+with CascadeWrapperBase(environment_variables, debug=debug_config) as cascade:
     ...
 ```
 
+#### `[RESULT]` and `[NOTE]` lines
+
+Two fixed line types make the logfile carry what a script *did*, so an agent (or you) can read it
+instead of capturing stdout:
+
+- **`[RESULT]: ...`** is written **automatically**, once per successful write operation
+  (`create`, `edit`, `delete`, `copy`, `move`, `publish`, `checkIn`, `checkOut`, `siteCopy`,
+  `editAccessRights`, `editWorkflowSettings`, `performWorkflowTransition`, `markMessage`,
+  `deleteMessage`, `editPreference`), right after that chain's pipeline line. Reads, searches and
+  lists write none; failed writes and failed items of a list create/edit write none. A write that
+  succeeded stays on record even if a later step of its chain failed.
+
+  ```
+  [RESULT]: create page 5f1a0000000000000000000000c90d00 /_dev/testing/testbed2-copy
+  [RESULT]: delete page 1a2b0000000000000000000000009f00 succeeded
+  [RESULT]: siteCopy succeeded
+  ```
+
+  `create` lines are `create <type> <id> [<path>]` (the new asset, as Cascade returned it; `<path>`
+  is the site-relative path when the payload gave `parent_folder_path`). Every other write is
+  `<operation> [<type> <id> <path>] succeeded`, naming the target (as many of the three as are
+  known); an operation with no identifier target is just `<operation> succeeded`. `<id>` is 32
+  hex characters and `<path>` starts with `/`.
+
+- **`[NOTE]: <text>`** is written **on purpose** by your script:
+
+  ```python
+  from cascade_cms.utils import script_log
+
+  with CascadeWrapperBase(environment_variables) as cascade:
+      script_log.note("will delete page 1a2b... /news/old-1")
+  ```
+
+  `script_log` is a stateless singleton that routes each note to the run whose `with` block is
+  active in the calling context, so wrappers open on different threads never mix notes. Notes must
+  be written **inside** the `with` block; outside it the note is dropped and a `RuntimeWarning` is
+  emitted. Newlines become spaces (one note = one line) and any occurrence of the API key is
+  masked. Thread-pool and async callbacks may call `note()` directly. **Process-pool callbacks
+  cannot** (another process, no active run): have them return values and note them in the main
+  script.
+
 All keys are required in debug mode — there are no inferred defaults, so you always know what
 you opted into.
 

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/pyproject.toml

@@ -4,15 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "cascade-cms-rest"
-version = "3.2.2"
+version = "3.4.0"
 description = "A typed, async REST client for Hannon Hill Cascade CMS"
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.12"          # uses `Self`, `TypeAlias`, PEP 604 unions
 authors = [{ name = "Keith Shark" }]
 dependencies = [
-    "aiohttp-client-cache[sqlite]",
-    "python-dotenv",
+    "aiohttp>=3.14.3",
     "pydantic>=2",
 ]
 

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/src/cascade_cms/__init__.py

@@ -6,8 +6,8 @@ payload/response models, and an OperationLogger for console/logfile output.
 """
 
 from .driver import CascadeCMSRestDriver, RequestExecutor
-from .operation_logger import OperationLogger
 from .operations import Node, OperationChain, Operations
+from .utils.operation_logger import OperationLogger
 from .wrapper import CascadeWrapperBase
 
 __all__ = [

{cascade_cms_rest-3.2.2 → cascade_cms_rest-3.4.0}/src/cascade_cms/cmstypes.py

@@ -1060,31 +1060,25 @@ class ResponseParser[T](BaseModel):
     """Parses a raw response body, trying `CascadeError` first and falling
     back to `serializer` on the expected success shape.
 
-    `_content` holds the parsed result (either a `CascadeError` or a `T`),
-    and `_cacheable` is set to True only when the success-path parse
-    succeeds, so error responses are never cached.
+    `_content` holds the parsed result (either a `CascadeError` or a `T`).
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
-    serializer: TypeAdapter[Any] | AssetAdapter | None = None
+    serializer: TypeAdapter[Any] | AssetAdapter
     _content: T | CascadeError | None = PrivateAttr(default=None)
-    _cacheable: bool = PrivateAttr(default=False)
 
     def __init__(
         self,
         raw: bytes,
-        serializer: TypeAdapter[Any] | AssetAdapter | None = None,
+        serializer: TypeAdapter[Any] | AssetAdapter,
         **kwargs,
     ):
         super().__init__(serializer=serializer, **kwargs)
         try:
             self._content = CascadeError.model_validate_json(raw)
         except ValidationError:
-            if self.serializer is None:
-                raise RuntimeWarning("No serializer included...")
             self._content = self.serializer.validate_json(raw)  # type: ignore[assignment]
-            self._cacheable = True
 
 
 # ----- Parser Functions -----