-
Notifications
You must be signed in to change notification settings - Fork 279
Python: Add sandbox import notification policy documentation #3973
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
c319e28
fe40b71
4096186
773a23f
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -100,10 +100,11 @@ To skip a sandbox environment for a Worker, set the `workflow_runner` keyword a | |
| When creating the Worker, the `workflow_runner` defaults to [`SandboxedWorkflowRunner()`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxedWorkflowRunner.html). | ||
| The `SandboxedWorkflowRunner` init accepts a `restrictions` keyword argument that defines a set of restrictions to apply to this sandbox. | ||
|
|
||
| The [`SandboxRestrictions`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxRestrictions.html) dataclass is immutable and contains three fields that can be customized, but only two have notable values. | ||
| The [`SandboxRestrictions`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxRestrictions.html) dataclass is immutable and contains four fields that can be customized, but only three have notable values. | ||
|
|
||
| - [`passthrough_modules`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxRestrictions.html#passthrough_modules) | ||
| - [`invalid_modules_members`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxRestrictions.html#invalid_module_members) | ||
| - [`import_notification_policy`](https://python.temporal.io/temporalio.worker.workflow_sandbox.SandboxRestrictions.html#import_notificaton_policy) | ||
|
|
||
| ### Passthrough modules | ||
|
|
||
|
|
@@ -195,6 +196,55 @@ my_restrictions = dataclasses.replace( | |
| my_worker = Worker(..., workflow_runner=SandboxedWorkflowRunner(restrictions=my_restrictions)) | ||
| ``` | ||
|
|
||
| ### Import Notification Policy | ||
|
|
||
| The sandbox's import notification policy specifies how the sandbox behaves when it imports modules in a way that may be unintentional. It covers two common scenarios, dynamic imports and enforcing module passthrough, and allows for controlling each separately. | ||
|
|
||
| A dynamic import occurs when a module is imported after the Workflow is loaded into the sandbox. These imports are often invisible and, if they don't do anything restricted by the sandbox, cause memory overhead. By default the [`WARN_ON_DYNAMIC_IMPORT`](https://python.temporal.io/temporalio.workflow.SandboxImportNotificationPolicy.html#WARN_ON_DYNAMIC_IMPORT) policy setting is enabled and a warning will be emitted when one of these imports occurs. | ||
|
|
||
| The other notable policy settings apply when a module is imported into the sandbox that was not passed through. These settings are disabled by default and must be explicitly turned on. | ||
| The [`WARN_ON_UNINTENTIONAL_PASSTHROUGH`](https://python.temporal.io/temporalio.workflow.SandboxImportNotificationPolicy.html#WARN_ON_UNINTENTIONAL_PASSTHROUGH) setting emits a warning when a module not included in the [passthrough modules](#passthrough-modules) list. | ||
|
|
||
| Similarly, the [`RAISE_ON_UNINTENTIONAL_PASSTHROUGH`](https://python.temporal.io/temporalio.workflow.SandboxImportNotificationPolicy.html#RAISE_ON_UNINTENTIONAL_PASSTHROUGH) setting will raise an error when an non-passed-through module is imported. | ||
|
|
||
| The import notification policy can be set for specific imports by using [`sandbox_import_notification_policy`](https://python.temporal.io/temporalio.workflow.unsafe.html#sandbox_import_notification_policy) context manager. | ||
|
|
||
| ```python | ||
| # my_workflow_file.py | ||
|
|
||
| from temporalio import workflow | ||
|
|
||
| with workflow.unsafe.sandbox_import_notification_policy( | ||
| workflow.SandboxImportNotificationPolicy.SILENT | ||
| ): | ||
| import pydantic | ||
|
|
||
| @workflow.defn | ||
| class MyWorkflow: | ||
| # ... | ||
| ``` | ||
|
|
||
| This can also be done at worker creation time by customizing the runner's restrictions. | ||
|
|
||
| ```python | ||
| # my_worker_file.py | ||
|
|
||
| from temporalio.worker import Worker | ||
| from temporalio.worker.workflow_sandbox import SandboxedWorkflowRunner, SandboxRestrictions | ||
|
|
||
| my_worker = Worker( | ||
| ..., | ||
| workflow_runner=SandboxedWorkflowRunner( | ||
| restrictions=SandboxRestrictions.default.with_import_notification_policy( | ||
| workflow.SandboxImportNotificationPolicy.WARN_ON_UNINTENTIONAL_PASSTHROUGH | workflow.SandboxImportNotificationPolicy.WARN_ON_UNINTENTIONAL_PASSTHROUGH | ||
|
||
| ) | ||
| ) | ||
| ) | ||
| ``` | ||
|
|
||
| The [`sandbox_import_notification_policy`](https://python.temporal.io/temporalio.workflow.unsafe.html#sandbox_import_notification_policy) context manager will always be respected if used in combination with the restrictions customization. | ||
|
|
||
|
|
||
| For more information on the Python sandbox, see the following resources. | ||
|
|
||
| - [Python SDK README](https://github.com/temporalio/sdk-python) | ||
|
|
||
Uh oh!
There was an error while loading. Please reload this page.