Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 10 additions & 12 deletions wiki/cascade-cms-wiki/docs/advanced/cpu-intensive.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,11 @@ By default `.then()` callbacks run on the async event loop, which is fine for I/

## When to Use `ProcessPoolExecutor`

- Image resizing, compression, or optimization
- Parsing large XML/JSON structures or heavy data transformation
- Running intensive regular expressions across large HTML bodies
- Light callbacks like simple string replacements or metadata dictionary updates do not need it and perform better on the default thread pool or event loop.
- Image resizing, compression, or other heavy visual asset optimization.
- Parsing and manipulating very large XML/HTML bodies or files.
- Executing complex, compute-intensive data transformations on metadata.
- Running bulk regular expression operations across large text fields.
- Contrast with light callbacks (e.g., title string replacement, simple metadata dictionary updates), which execute quickly in-process and do not require `ProcessPoolExecutor`.

---

Expand All @@ -18,15 +19,12 @@ By default `.then()` callbacks run on the async event loop, which is fine for I/
```python
from concurrent.futures import ProcessPoolExecutor
from os import cpu_count
from cascade_cms import Cascade

env = {"SERVER": "prod", "API_KEY": "secret", "CASCADE_URL": "https://cascade.example.com"}

def optimize_image(asset):
# CPU-bound image processing work here
# Perform heavy CPU-bound image processing here
return asset

with Cascade(env, {}) as cascade:
with Cascade(env_vars) as cascade:
with ProcessPoolExecutor(max_workers=cpu_count()) as executor:
cascade.operations.read(id).then(optimize_image)
results = cascade.submit_requests(executor=executor)
Expand Down Expand Up @@ -58,12 +56,12 @@ cascade.operations.read(id).then(transform)

## `ProcessPoolExecutor` vs `ThreadPoolExecutor`

`ProcessPoolExecutor` provides true parallelism across multiple CPU cores in separate memory spaces, but requires all callback functions and data to be picklable and incurs inter-process communication overhead. `ThreadPoolExecutor` uses shared memory with minimal overhead and no pickling restrictions, but remains limited by Python's Global Interpreter Lock (GIL) for CPU-bound tasks. Use `ProcessPoolExecutor` for heavy CPU computation, and stick with `ThreadPoolExecutor` (the default) for I/O-bound work.
`ProcessPoolExecutor` provides true parallelism by running callbacks in separate worker processes with independent memory spaces, making it ideal for CPU-bound tasks, though it incurs higher startup overhead and requires picklable functions. `ThreadPoolExecutor` runs tasks concurrently within the same process sharing memory with lower overhead, but Python's Global Interpreter Lock (GIL) prevents it from achieving true parallelism for CPU-bound work. Use `ProcessPoolExecutor` for heavy compute operations and `ThreadPoolExecutor` (the default) for standard I/O-bound tasks.

---

## Performance Considerations

Spawning and managing worker processes carries an initialization overhead, meaning extremely fast callbacks may run slower in a process pool than synchronously due to serialization costs. Additionally, offloading CPU work via the executor does not change the network concurrency rules; the driver's underlying `MAX_REQUESTS` semaphore still governs HTTP request limits.
Spawning and managing worker processes carries a startup cost, so for very fast, lightweight callbacks the inter-process serialization overhead may actually outweigh the performance benefit. Additionally, keep in mind that the driver's internal request semaphore still governs HTTP concurrency independently of whichever executor you choose for your synchronous callbacks.

<!-- synthesized-for: 3.1.1 -->
<!-- synthesized-for: 3.9.2 -->
9 changes: 9 additions & 0 deletions wiki/cascade-cms-wiki/docs/advanced/index.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,12 @@
!!! warning "Documentation may be out of date"
This page was not successfully updated in the latest synthesis run. If you notice inaccuracies, please open an issue.

<!-- synthesis-failed
- Heading structure changed.
Expected: ['# Advanced', '## In This Section']
Got: ['# Advanced']
-->

# Advanced

Welcome to the advanced power user guide for tuning and scaling your application. This section covers configuration and performance topics that go beyond the defaults, including caching behavior, debug logging, and CPU-intensive callback patterns.
Expand Down
7 changes: 7 additions & 0 deletions wiki/cascade-cms-wiki/docs/advanced/logging.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
!!! warning "Documentation may be out of date"
This page was not successfully updated in the latest synthesis run. If you notice inaccuracies, please open an issue.

<!-- synthesis-failed
- Potentially invented field names: ["'example' (near: ...edit -> publish\n[GET] https://cascade.example.com/api/v1/rea...)"]
-->

# Logging & Debugging

Operation logger owns all console, logfile, and (verbose mode) request/response file output for the cascade_cms library. Two output modes exist: normal mode for everyday use and debug mode for diagnosing failures, controlled solely by whether `debug_config` is `None`. Both produce logfiles; debug mode adds a verbose nested call-chain log alongside a quieter console output.
Expand Down
210 changes: 52 additions & 158 deletions wiki/cascade-cms-wiki/docs/core-concepts/index.md
Original file line number Diff line number Diff line change
@@ -1,197 +1,91 @@
# Core Concepts

## The `Cascade` class
This page unpacks the mental model behind Cascade CMS: the `Cascade` context manager ties together a REST driver, an operation logger, and an `Operations` builder that yields independent `OperationChain` instances, all executed concurrently via `submit_requests()`.

`Cascade` is the single entry point for all library interactions. Open a
session with it as a [context manager](https://docs.python.org/3/reference/datamodel.html#context-managers):

```python
from cascade_cms.wrapper import Cascade, EnvironmentVars

env: EnvironmentVars = {
"SERVER": "my-site",
"API_KEY": "your-api-key",
"CASCADE_URL": "https://your-cascade-instance.com",
}
---

with Cascade(env) as cascade:
# queue operations here
...
```
## Basic Operation Calls

Previously known as `CascadeWrapperBase`; the alias still works but `Cascade`
is the current name.
Every script follows the same skeleton — open the wrapper as a context manager, queue operations on `cascade.operations`, chain callbacks with `.then()`, then call `submit_requests()` once to execute all chains concurrently. This design keeps network requests clean, isolates failures per asset, and eliminates boilerplate.

### Constructor
### Example

```python
Cascade(
environmentVariables: EnvironmentVars,
debug: dict[str, Any] | None = None,
*,
exit_on_failure: bool = True,
log_dir: str | os.PathLike | None = None,
)
with Cascade(env_vars) as cascade:
# Queue a read operation for a specific asset identifier
cascade.operations.read(identifier)

# Execute all queued chains concurrently
results = cascade.submit_requests()

# Check results for API-level errors
for result in results:
if isinstance(result, CascadeError):
print(f"Error: {result.message}")
```

`EnvironmentVars` is a `TypedDict` with three required keys:

| Key | Description |
|---|---|
| `SERVER` | Label used in log output (not a network address) |
| `API_KEY` | Cascade REST API bearer token |
| `CASCADE_URL` | Base URL of your Cascade CMS instance |

`exit_on_failure=True` (default) ends the script non-zero on any failure.
Pass `False` for long-lived processes like the MCP server.

---

## Operations

`cascade.operations` is the entry point for all CMS operations. It returns
an `Operations` builder that accepts the first call in a chain:
### Expected Output

```python
with Cascade(env) as cascade:
chain = cascade.operations.read("abc123")
Asset(_asset_type='page', _data={...})
```

Available operations mirror the Cascade REST API:

| Operation | Description |
|---|---|
| `.read(id)` | Read one asset |
| `.edit(payload)` | Edit an asset via callback or direct payload |
| `.publish(id)` | Publish an asset |
| `.delete(id)` | Delete an asset |
| `.copy(id, dest)` | Copy an asset |
| `.move(id, dest)` | Move an asset |
| `.checkIn(id)` | Check in an asset |
| `.checkOut(id)` | Check out an asset |
| `.search(query)` | Search assets |
| `.create(asset)` | Create a new asset |

See the [API Reference](../operations/operations.md) for full signatures.

---

## Operation chains

Each operation call returns an `OperationChain`, not a result. Nothing
executes until you call `.submit_requests()`. This design lets you compose
multi-step workflows before any network requests are made:

```python
from cascade_cms.cmstypes import Asset

def set_searchable(asset: Asset) -> Asset:
asset.searchable = True
return asset

with Cascade(env) as cascade:
results = (
cascade.operations
.read("abc123")
.edit(set_searchable)
.publish("abc123")
.submit_requests(Asset)
)
```

The type argument to `.submit_requests()` is for the type checker. `Asset`
covers most cases; use a more specific type when the operation returns one.

---
## Payload Models

## `edit()` and callbacks
Payload models are strongly typed Pydantic objects (inheriting from `SimplePayload`) that pair with specific REST operations to ensure the API endpoint receives the expected fields. They provide type safety, autocomplete, and proper serialization aliases (like converting Python snake_case to Cascade camelCase) without requiring raw dictionaries.

`edit()` accepts a callable, a single asset, or a list of assets. The
callable form is the most common in practice:
### Example: `SearchInformation` paired with `search`

```python
def update_keywords(asset: Asset) -> Asset:
asset.keywords = "updated"
return asset

cascade.operations.edit(update_keywords)
```

The callback receives the current asset and must return the modified asset.
The identifier is derived from the asset's own `id`/`path`/`siteName` fields
— there is no separate identifier argument on `edit()` in 3.9.1.

---

## Batch execution and `ChainGroup`

Passing a list to operations that accept identifiers — `read`, `delete`,
`publish`, etc. — creates one independent `OperationChain` per identifier,
returned as a `ChainGroup`:
from cascade_cms.cmstypes import SearchInformation

# Construct the payload with search criteria
payload = SearchInformation(
siteName="Default",
searchTerms="article",
searchFields=["name"],
searchTypes=["page"]
)

```python
with Cascade(env) as cascade:
results = (
cascade.operations
.read(["id1", "id2", "id3"])
.submit_requests(Asset)
)
with Cascade(env_vars) as cascade:
# Pass the typed payload to the search operation
cascade.operations.search(payload)
results = cascade.submit_requests()
```

Failures in one chain do not cancel others. The returned `ChainResults`
covers all chains in the group.
These models enforce required arguments at validation time, preventing malformed requests from ever hitting the wire. Other operations follow the exact same pattern using models like `deleteParameters`, `auditParameters`, and `publishInformation`.

---

## Result handling
## CPU-Intensive Operations

`.submit_requests()` returns `ChainResults[T]` — a list subclass with
`.success` and `.failed` properties. See [Result Handling](../getting-started/result-handling.md)
for full details.
For operations involving heavy computation in `.then()` callbacks — image processing, data transformation, bulk string manipulation — offload work to a `ProcessPoolExecutor` rather than running it on the async event loop.

```python
results = cascade.operations.read("abc123").submit_requests(Asset)
from concurrent.futures import ProcessPoolExecutor
from os import cpu_count

for asset in results.success:
print(asset.path)
def optimize_image(asset):
# Heavy CPU-bound image processing
return asset

for failure in results.failed:
print(f"[{failure.category}] {failure.message}")
with ProcessPoolExecutor(max_workers=cpu_count()) as executor:
with Cascade(env_vars) as cascade:
cascade.operations.read(id).then(optimize_image)
results = cascade.submit_requests(executor=executor)
```

---

## Script logging

`script_log.note()` writes annotated log lines from within a script:

```python
from cascade_cms.utils import script_log

with Cascade(env) as cascade:
script_log.note("Starting run")
results = cascade.operations.read("abc123").submit_requests(Asset)
script_log.note(f"Done — {len(results.success)} succeeded")
```
!!! note "Module-level functions only"
Callbacks passed to `ProcessPoolExecutor` must be defined at module level — lambdas and nested functions are not picklable and will raise at runtime.

Calls outside the `with` block drop silently with a `RuntimeWarning`.
API keys are automatically redacted from log output.
See [Advanced: CPU-Intensive Tasks](../advanced/cpu-intensive.md) for full configuration details, performance trade-offs, and `ThreadPoolExecutor` comparison.

---

## Identifiers

The `utils.identifiers` module (added in 3.8.3) coerces raw Cascade
identifier dicts to `IdentifierType`:

```python
from cascade_cms.utils.identifiers import to_identifier, to_identifiers

identifier = to_identifier({"id": "abc123", "type": "page", "path": None})
identifiers = to_identifiers([{"id": "a"}, {"id": "b"}])
```
## Next Steps

Use these when processing raw API responses before passing identifiers to
operations.
Ready to go deeper? The [Advanced](../advanced/index.md) section covers configuration topics for power users: debug logging and CPU-intensive workload patterns.

<!-- synthesized-for: 3.9.1 -->
<!-- synthesized-for: 3.9.2 -->
Loading