prefect 3.7.3.dev4__tar.gz → 3.7.3.dev5__tar.gz

prefect-3.7.3.dev5/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: prefect
+Version: 3.7.3.dev5
+Summary: Workflow orchestration and management.
+Project-URL: Changelog, https://github.com/PrefectHQ/prefect/releases
+Project-URL: Documentation, https://docs.prefect.io
+Project-URL: Source, https://github.com/PrefectHQ/prefect
+Project-URL: Tracker, https://github.com/PrefectHQ/prefect/issues
+Author-email: "Prefect Technologies, Inc." <help@prefect.io>
+License: Apache-2.0
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: <3.15,>=3.10
+Requires-Dist: aiosqlite<1.0.0,>=0.17.0
+Requires-Dist: alembic<2.0.0,>=1.7.5
+Requires-Dist: amplitude-analytics<2.0.0,>=1.2.1
+Requires-Dist: anyio<5.0.0,>=4.4.0
+Requires-Dist: apprise<2.0.0,>=1.1.0
+Requires-Dist: asgi-lifespan<3.0,>=1.0
+Requires-Dist: asyncpg<1.0.0,>=0.23
+Requires-Dist: cachetools<8.0,>=5.3
+Requires-Dist: click<9,>=8.0
+Requires-Dist: cloudpickle<4.0,>=2.0
+Requires-Dist: coolname<6.0.0,>=1.0.4
+Requires-Dist: cryptography>=36.0.1
+Requires-Dist: cyclopts>=4.8.0
+Requires-Dist: dateparser<2.0.0,>=1.1.1
+Requires-Dist: docker<8.0,>=4.0
+Requires-Dist: exceptiongroup>=1.0.0
+Requires-Dist: fastapi<1.0.0,>=0.111.0
+Requires-Dist: fsspec>=2022.5.0
+Requires-Dist: graphviz>=0.20.1
+Requires-Dist: griffe<3.0.0,>=0.49.0
+Requires-Dist: httpcore<2.0.0,>=1.0.5
+Requires-Dist: httpx[http2]!=0.23.2,>=0.23
+Requires-Dist: humanize<5.0.0,>=4.9.0
+Requires-Dist: jinja2-humanize-extension>=0.4.0
+Requires-Dist: jinja2<4.0.0,>=3.1.6
+Requires-Dist: jsonpatch<2.0,>=1.32
+Requires-Dist: jsonschema<5.0.0,>=4.18.0
+Requires-Dist: opentelemetry-api<2.0.0,>=1.27.0
+Requires-Dist: orjson<4.0,>=3.7
+Requires-Dist: packaging<26.3,>=21.3
+Requires-Dist: pathspec>=0.8.0
+Requires-Dist: pendulum<4,>=3.1.0; python_version < '3.13'
+Requires-Dist: pluggy>=1.6.0
+Requires-Dist: prometheus-client>=0.20.0
+Requires-Dist: pydantic!=2.11.0,!=2.11.1,!=2.11.2,!=2.11.3,!=2.11.4,<3.0.0,>=2.10.1
+Requires-Dist: pydantic-core<3.0.0,>=2.12.0
+Requires-Dist: pydantic-extra-types<3.0.0,>=2.8.2
+Requires-Dist: pydantic-settings<3.0.0,>=2.9.1
+Requires-Dist: pydocket>=0.19.0
+Requires-Dist: python-dateutil<3.0.0,>=2.8.2
+Requires-Dist: python-slugify<9.0,>=5.0
+Requires-Dist: pytz<2027,>=2021.1
+Requires-Dist: pyyaml<7.0.0,>=5.4.1
+Requires-Dist: readchar<5.0.0,>=4.0.0
+Requires-Dist: rfc3339-validator<0.2.0,>=0.1.4
+Requires-Dist: rich<16.0,>=11.0
+Requires-Dist: ruamel-yaml-clib>=0.2.8; platform_python_implementation == 'CPython'
+Requires-Dist: ruamel-yaml>=0.17.0
+Requires-Dist: semver>=3.0.4
+Requires-Dist: sniffio<2.0.0,>=1.3.0
+Requires-Dist: sqlalchemy[asyncio]<3.0.0,>=2.0
+Requires-Dist: toml>=0.10.0
+Requires-Dist: typing-extensions<5.0.0,>=4.10.0
+Requires-Dist: uvicorn!=0.29.0,>=0.14.0
+Requires-Dist: websockets<17.0,>=15.0.1
+Requires-Dist: whenever<0.11.0,>=0.7.3; python_version >= '3.13'
+Provides-Extra: aws
+Requires-Dist: prefect-aws>=0.5.8; extra == 'aws'
+Provides-Extra: azure
+Requires-Dist: prefect-azure>=0.4.0; extra == 'azure'
+Provides-Extra: bitbucket
+Requires-Dist: prefect-bitbucket>=0.3.0; extra == 'bitbucket'
+Provides-Extra: buildx
+Requires-Dist: python-on-whales>=0.81; extra == 'buildx'
+Provides-Extra: bundles
+Requires-Dist: uv>=0.6.0; extra == 'bundles'
+Provides-Extra: dask
+Requires-Dist: prefect-dask>=0.3.0; extra == 'dask'
+Provides-Extra: databricks
+Requires-Dist: prefect-databricks>=0.3.0; extra == 'databricks'
+Provides-Extra: dbt
+Requires-Dist: prefect-dbt>=0.6.0; extra == 'dbt'
+Provides-Extra: docker
+Requires-Dist: prefect-docker>=0.6.0; extra == 'docker'
+Provides-Extra: email
+Requires-Dist: prefect-email>=0.4.0; extra == 'email'
+Provides-Extra: gcp
+Requires-Dist: prefect-gcp>=0.6.0; extra == 'gcp'
+Provides-Extra: github
+Requires-Dist: prefect-github>=0.4.2; extra == 'github'
+Provides-Extra: gitlab
+Requires-Dist: prefect-gitlab>=0.3.0; extra == 'gitlab'
+Provides-Extra: kubernetes
+Requires-Dist: prefect-kubernetes>=0.4.0; extra == 'kubernetes'
+Provides-Extra: otel
+Requires-Dist: opentelemetry-distro<1.0.0,>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp<2.0.0,>=1.27.0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-logging<1.0.0,>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation-system-metrics<1.0.0,>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-instrumentation<1.0.0,>=0.48b0; extra == 'otel'
+Requires-Dist: opentelemetry-test-utils<1.0.0,>=0.48b0; extra == 'otel'
+Provides-Extra: ray
+Requires-Dist: prefect-ray>=0.4.0; extra == 'ray'
+Provides-Extra: redis
+Requires-Dist: prefect-redis>=0.2.0; extra == 'redis'
+Provides-Extra: shell
+Requires-Dist: prefect-shell>=0.3.0; extra == 'shell'
+Provides-Extra: slack
+Requires-Dist: prefect-slack>=0.3.0; extra == 'slack'
+Provides-Extra: snowflake
+Requires-Dist: prefect-snowflake>=0.28.0; extra == 'snowflake'
+Provides-Extra: sqlalchemy
+Requires-Dist: prefect-sqlalchemy>=0.5.0; extra == 'sqlalchemy'
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://github.com/PrefectHQ/prefect/assets/3407835/c654cbc6-63e8-4ada-a92a-efd2f8f24b85" width=1000></p>
+
+<p align="center">
+    <a href="https://pypi.org/project/prefect/" alt="PyPI version">
+        <img alt="PyPI" src="https://img.shields.io/pypi/v/prefect?color=0052FF&labelColor=090422" />
+    </a>
+    <a href="https://pypi.org/project/prefect/" alt="PyPI downloads/month">
+        <img alt="Downloads" src="https://img.shields.io/pypi/dm/prefect?color=0052FF&labelColor=090422" />
+    </a>
+    <a href="https://github.com/prefecthq/prefect/" alt="Stars">
+        <img src="https://img.shields.io/github/stars/prefecthq/prefect?color=0052FF&labelColor=090422" />
+    </a>
+    <a href="https://github.com/prefecthq/prefect/pulse" alt="Activity">
+        <img src="https://img.shields.io/github/commit-activity/m/prefecthq/prefect?color=0052FF&labelColor=090422" />
+    </a>
+    <br>
+    <a href="https://prefect.io/slack" alt="Slack">
+        <img src="https://img.shields.io/badge/slack-join_community-red.svg?color=0052FF&labelColor=090422&logo=slack" />
+    </a>
+    <a href="https://www.youtube.com/c/PrefectIO/" alt="YouTube">
+        <img src="https://img.shields.io/badge/youtube-watch_videos-red.svg?color=0052FF&labelColor=090422&logo=youtube" />
+    </a>
+</p>
+
+
+<p align="center">
+    <a href="https://docs.prefect.io/v3/get-started/index?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none">
+        Installation
+    </a>
+    ·
+    <a href="https://docs.prefect.io/v3/get-started/quickstart?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none">
+        Quickstart
+    </a>
+    ·
+    <a href="https://docs.prefect.io/v3/how-to-guides/workflows/write-and-run?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none">
+        Build workflows
+    </a>
+    ·
+    <a href="https://docs.prefect.io/v3/concepts/deployments?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none">
+        Deploy workflows
+    </a>
+    ·
+    <a href="https://app.prefect.cloud/?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none">
+        Prefect Cloud
+    </a>
+</p>
+
+# Prefect
+
+Prefect is a workflow orchestration framework for building data pipelines in Python.
+It's the simplest way to elevate a script into a production workflow.
+With Prefect, you can build resilient, dynamic data pipelines that react to the world around them and recover from unexpected changes.
+
+With just a few lines of code, data teams can confidently automate any data process with features such as scheduling, caching, retries, and event-based automations.
+
+Workflow activity is tracked and can be monitored with a self-hosted [Prefect server](https://docs.prefect.io/latest/manage/self-host/?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none) instance or managed [Prefect Cloud](https://www.prefect.io/cloud-vs-oss?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none) dashboard.
+
+> [!TIP]
+> Prefect flows can handle retries, dependencies, and even complex branching logic
+> 
+> [Check our docs](https://docs.prefect.io/v3/get-started/index?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none) or see the example below to learn more!
+
+## Getting started
+
+Prefect requires Python 3.10+. To [install the latest version of Prefect](https://docs.prefect.io/v3/get-started/install), run one of the following commands:
+
+```bash
+pip install -U prefect
+```
+
+```bash
+uv add prefect
+```
+
+Then create and run a Python file that uses Prefect `flow` and `task` decorators to orchestrate and observe your workflow - in this case, a simple script that fetches the number of GitHub stars from a repository:
+
+```python
+from prefect import flow, task
+import httpx
+
+
+@task(log_prints=True)
+def get_stars(repo: str):
+    url = f"https://api.github.com/repos/{repo}"
+    count = httpx.get(url).json()["stargazers_count"]
+    print(f"{repo} has {count} stars!")
+
+
+@flow(name="GitHub Stars")
+def github_stars(repos: list[str]):
+    for repo in repos:
+        get_stars(repo)
+
+
+# run the flow!
+if __name__ == "__main__":
+    github_stars(["PrefectHQ/prefect"])
+```
+
+Fire up a Prefect server and open the UI at http://localhost:4200 to see what happened:
+
+```bash
+prefect server start
+```
+
+To run your workflow on a schedule, turn it into a deployment and schedule it to run every minute by changing the last line of your script to the following:
+
+```python
+if __name__ == "__main__":
+    github_stars.serve(
+        name="first-deployment",
+        cron="* * * * *",
+        parameters={"repos": ["PrefectHQ/prefect"]}
+    )
+```
+
+You now have a process running locally that is looking for scheduled deployments!
+Additionally you can run your workflow manually from the UI or CLI. You can even run deployments in response to [events](https://docs.prefect.io/latest/automate/?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none).
+
+> [!TIP]
+> Where to go next - check out our [documentation](https://docs.prefect.io/v3/get-started/index?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none) to learn more about:
+> - [Deploying flows to production environments](https://docs.prefect.io/v3/deploy?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none)
+> - [Adding error handling and retries](https://docs.prefect.io/v3/develop/write-tasks#retries?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none)
+> - [Integrating with your existing tools](https://docs.prefect.io/integrations/integrations?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none)
+> - [Setting up team collaboration features](https://docs.prefect.io/v3/manage/cloud/manage-users/manage-teams#manage-teams?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none)
+
+
+## Prefect Cloud
+
+Prefect Cloud provides workflow orchestration for the modern data enterprise. By automating over 200 million data tasks monthly, Prefect empowers diverse organizations — from Fortune 50 leaders such as Progressive Insurance to innovative disruptors such as Cash App — to increase engineering productivity, reduce pipeline errors, and cut data workflow compute costs.
+
+Read more about Prefect Cloud [here](https://www.prefect.io/cloud-vs-oss?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none) or sign up to [try it for yourself](https://app.prefect.cloud?utm_source=oss&utm_medium=oss&utm_campaign=oss_gh_repo&utm_term=none&utm_content=none).
+
+## prefect-client
+
+If your use case is geared towards communicating with Prefect Cloud or a remote Prefect server, check out our
+[prefect-client](https://pypi.org/project/prefect-client/). It is a lighter-weight option for accessing client-side functionality in the Prefect SDK and is ideal for use in ephemeral execution environments.
+
+## Connect & Contribute
+Join a thriving community of over 25,000 practitioners who solve data challenges with Prefect. Prefect's community is built on collaboration, technical innovation, and continuous improvement.
+
+### Community Resources
+🌐 **[Explore the Documentation](https://docs.prefect.io)** - Comprehensive guides and API references  
+💬 **[Join the Slack Community](https://prefect.io/slack)** - Connect with thousands of practitioners  
+🤝 **[Contribute to Prefect](https://docs.prefect.io/contribute/)** - Help shape the future of the project  
+ 🔌 **[Support or create a new Prefect integration](https://docs.prefect.io/contribute/contribute-integrations)** - Extend Prefect's capabilities   
+📋 **[Tail the Dev Log](https://dev-log.prefect.io/)** - Prefect's open source development blog
+
+### Stay Informed
+📥 **[Subscribe to our Newsletter](https://prefect.io/newsletter)** - Get the latest Prefect news and updates  
+📣 **[X](https://x.com/PrefectIO)** and **[Bluesky](https://bsky.app/profile/prefect.io)** - Latest updates and announcements  
+📺 **[YouTube](https://www.youtube.com/@PrefectIO)** - Video tutorials and webinars  
+📱 **[LinkedIn](https://www.linkedin.com/company/prefect)** - Professional networking and company news  
+
+Your contributions, questions, and ideas make Prefect better every day. Whether you're reporting bugs, suggesting features, or improving documentation, your input is invaluable to the Prefect community.
+

prefect-3.7.3.dev5/src/prefect/AGENTS.md

@@ -0,0 +1,68 @@
+# Core Prefect SDK
+
+The foundation for building and executing workflows with Python. This covers the SDK layer — decorators, engines, state management, and client-side abstractions.
+
+## Public API
+
+There is no formal public/private boundary beyond the `_` prefix convention. Modules and functions prefixed with `_` are internal. Everything else is considered public and requires backward compatibility.
+
+## Entry Points
+
+- `flows.py` / `tasks.py` — `@flow` and `@task` decorator definitions. The primary user-facing API.
+- `flow_engine.py` / `task_engine.py` — Async execution engines that orchestrate runs. **Critical invariant:** both sync and async engine paths must be kept in lockstep. Changes to one must be mirrored in the other.
+- `flow_engine.py` is also a subprocess entrypoint: `python -m prefect.flow_engine <entrypoint>`. Reads `PREFECT__FLOW_RUN_ID` from the environment; accepts exactly one argument (the flow entrypoint path or module ref). Workers and infrastructure use this to launch flow runs as isolated subprocesses. Plain functions not decorated with `@flow` are auto-converted to flows at this entry point.
+- `states.py` — State objects and transition logic
+- `results.py` — Result persistence and retrieval
+- `futures.py` — `PrefectFuture` for async task results
+- `task_runners.py` — Task runner implementations (`ThreadPoolTaskRunner`, `ProcessPoolTaskRunner`)
+- `transactions.py` — Transaction support
+- `context.py` — Runtime context management and dependency injection
+
+## Key Contracts
+
+- **Engine ordering matters.** The engines apply features (retries, caching, result persistence, transactions) in a specific order. Changing the order or forgetting a feature in one engine path is the most common source of breakage.
+- **Set run metadata before state transitions.** Any run attribute that event subscribers observe at the moment of a state transition (e.g., custom `flow_run_name`) must be persisted to the server *before* `set_state()` is called for that transition. Metadata set after the call appears stale to subscribers of that state event.
+- **Sync and async must stay in sync.** Both `flow_engine.py` and `task_engine.py` have sync and async paths. Any behavior change must be applied to both.
+- **Use `whenever` compat helpers for all datetime conversions on Python 3.13+.** `types/_datetime.py` provides `now()`, `_whenever_to_stdlib()`, `_whenever_zdt_from_py()`, and `_whenever_pdt_from_py()` to abstract over API differences between whenever 0.7.x–0.9.x and ≥ 0.10.0. The `_WHENEVER_NEW_API` flag (True when whenever ≥ 0.10.0) guards version-specific code. Never call `DateTime.now()` or `pendulum.now()` directly — use `now()` from `types/_datetime.py` instead. Avoid no-argument `datetime.datetime.now()` because it returns a tz-naive datetime that raises `TypeError` when compared to the tz-aware datetimes produced by `now()`. Explicitly timezone-aware stdlib calls such as `datetime.now(ZoneInfo("UTC"))` are allowed when needed to preserve timezone information. Never call `ZonedDateTime.from_py_datetime()`, `PlainDateTime.from_py_datetime()`, or `.py_datetime()` directly — use the helpers instead. Violations will silently break on whichever whenever version the helpers weren't written for.
+- **Flow and task engines advance state differently.** The flow engine makes blocking API calls to the server to propose and advance states. The task engine emits `prefect.task_run.*` events (delivered via WebSockets) but advances state locally through `set_state` calls with polling/backoff — do not assume the two engines work the same way.
+- **Flow state transitions go through the server.** The flow engine proposes states to the server, which accepts or rejects them via orchestration rules. The task engine, by contrast, manages state transitions locally via `set_state` and emits `prefect.task_run.*` events — it does not propose states to the server.
+- **`ProcessPoolTaskRunner` requires picklable data across subprocess boundaries.** `PrefectFuture` objects are not picklable and cannot be passed to worker subprocesses. Any `wait_for` futures must be waited on in the parent process and converted to `State` objects before submission. The subprocess task engine handles `State` objects via `resolve_to_final_result`, which raises `UpstreamTaskError` for non-completed upstreams.
+- **`ProcessPoolTaskRunner` instances may be deserialized without `__init__` running.** When a runner is pickled and restored in a subprocess, `__init__` is not called, so instance attributes set there may be absent. Access any such attribute via `getattr(self, "_attr", default)` rather than `self._attr` directly — both in the property getter and in `duplicate()`. The `subprocess_message_processor_factories` property demonstrates the required pattern.
+- **`ThreadPoolTaskRunner` is cloudpickled when a flow run is dispatched to a subprocess.** `threading.Lock` and other non-picklable thread primitives must be dropped in `__getstate__` and rebuilt in `__setstate__`. Any new instance state added to this class must be evaluated for picklability.
+- **Nested task submissions on a bounded `ThreadPoolTaskRunner` can deadlock.** When a worker task submits children and blocks on `.result()` while all `max_workers` threads are busy, the pool starves. `_warn_if_nested_submit_would_deadlock` detects this and emits a one-time warning — preserve this detection when changing pool management.
+- **Result storage resolves through three tiers, potentially making an API call.** `get_default_result_storage()` checks: (1) `PREFECT_DEFAULT_RESULT_STORAGE_BLOCK` setting, (2) server-configured default block (API call to the server's Configuration store), (3) local storage path. The API call is silently suppressed on any HTTP error. Engines use `_get_default_persist_result()` — not `should_persist_result()` — at context setup time to auto-enable persistence when a server default block is configured. Do not swap `_get_default_persist_result()` back to `should_persist_result()` in engine initialization paths; `should_persist_result()` does not consult the server default.
+- **`ResultRecordMetadata` tolerates unknown serializer types.** When loading persisted metadata, an unrecognized serializer `type` is converted to an `UnknownSerializer` placeholder rather than raising `ValidationError`. This allows inspecting result metadata when the serializer implementation is unavailable in the current environment. However, known serializer types with invalid fields still raise `ValidationError`. `UnknownSerializer.dumps()` and `UnknownSerializer.loads()` raise `RuntimeError` — the tolerance is for inspection only, not actual serialization/deserialization.
+- **`ResultRecord` must be marked persisted after every storage write.** `ResultStore` calls `mark_persisted()` on every record it writes; `to_state_create` in `states.py` consults `is_persisted` as a fallback when `should_persist_result()` returns `False` (e.g., after run context teardown). Any new sync or async persist path that omits `mark_persisted()` will silently drop state metadata for already-written results.
+- **Flow-run suspension is enforced at orchestration boundaries.** Suspension is delivered via `FlowRunSuspensionRequest` and raised with `raise_if_flow_run_suspension_requested()`. When changing engines, futures, task runners, or generator execution, check before returning control to flow user code or proposing a flow state that could leave `Suspended`; keep sync/async paths aligned and avoid per-boundary API reads.
+
+## Logging
+
+Use `get_logger()` from `prefect.logging` instead of raw `logging.getLogger()` — it adds API key obfuscation and places loggers under the `"prefect."` namespace.
+
+- General library code → `get_logger(__name__)`
+- SDK core modules (flows, tasks, engine) → `get_logger("flows")`, `get_logger("engine")`, etc.
+- Worker implementations → `get_worker_logger(self)`
+- Infrastructure orchestrating a run (engines) → `flow_run_logger(flow_run)` / `task_run_logger(task_run)`
+- Workers/runners needing child loggers → `.getChild("worker"|"runner", extra={...})` on a run logger
+- Code that may run inside or outside a run (concurrency, transactions, blocks) → try `get_run_logger()`, fall back to `get_logger(...)`
+- Raw `logging.getLogger()` only inside `src/prefect/logging/` (circular imports) or configuring third-party loggers
+
+## Related
+
+- `client/` → HTTP client for server communication (see client/AGENTS.md)
+- `server/` → Orchestration backend (see server/AGENTS.md)
+- `cli/` → Command-line interface (see cli/AGENTS.md)
+- `events/` → Event system and automations (see events/AGENTS.md)
+- `settings/` → Configuration system (see settings/AGENTS.md)
+- `concurrency/` → Concurrency slot acquisition and lease management (see concurrency/AGENTS.md)
+- `logging/` → Logging handlers, API log shipping, and run-context loggers (see logging/AGENTS.md)
+- `runner/` → Thin facade over extracted single-responsibility classes for local flow run execution (see runner/AGENTS.md)
+- `deployments/` → YAML-driven deployment lifecycle: project init, build/push/pull steps, and triggering remote flow runs (see deployments/AGENTS.md)
+- `utilities/` → Cross-cutting helpers: async utils, schema hydration, callables introspection, and more (see utilities/AGENTS.md)
+- `blocks/` → Server-persisted configuration objects for external service credentials and settings (see blocks/AGENTS.md)
+- `workers/` → Work-pool-based execution layer: polls for flow runs, dispatches to infrastructure (see workers/AGENTS.md)
+- `bundles/` → Flow bundling for remote execution (`create_bundle_for_flow_run`, cloudpickle+gzip); used by workers when dispatching `InfrastructureBoundFlow` runs; `execute_bundle_from_file` is lazy-loaded via `__getattr__` to avoid `runpy` warnings when invoked as `python -m prefect.bundles.execute`
+- `plugins.py` → Stable public surface for startup hooks and `prefect.collections` entrypoint loading; pluggy symbols are lazy-loaded so `prefect-client` builds (which don't ship pluggy) can still import `load_prefect_collections` without error
+- `docker/` → `DockerImage` class for building and pushing Docker images during deployment
+- `telemetry/` → OS-level resource metric collection and run telemetry
+- `testing/` → Test utilities shipped with the SDK: `prefect_test_harness`, assertion helpers, and reusable fixtures (see testing/AGENTS.md)

prefect-3.7.3.dev5/src/prefect/_build_info.py

@@ -0,0 +1,5 @@
+# Generated by versioningit
+__version__ = "3.7.3.dev5"
+__build_date__ = "2026-05-28 09:24:46.584662+00:00"
+__git_commit__ = "f7d76f21e9731cedf0462e3f9632133e1c23a439"
+__dirty__ = False

prefect-3.7.3.dev5/src/prefect/_internal/result_records.py

@@ -0,0 +1,264 @@
+from __future__ import annotations
+
+import inspect
+import uuid
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Optional,
+    TypeVar,
+    Union,
+    cast,
+)
+from uuid import UUID
+
+from pydantic import (
+    BaseModel,
+    Field,
+    PrivateAttr,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
+
+import prefect
+from prefect.exceptions import (
+    SerializationError,
+)
+from prefect.serializers import PickleSerializer, Serializer, UnknownSerializer
+from prefect.types import DateTime
+from prefect.utilities.dispatch import lookup_type
+
+if TYPE_CHECKING:
+    pass
+
+
+ResultSerializer = Union[Serializer, str]
+LITERAL_TYPES: set[type] = {type(None), bool, UUID}
+R = TypeVar("R")
+
+
+class ResultRecordMetadata(BaseModel):
+    """
+    Metadata for a result record.
+    """
+
+    storage_key: Optional[str] = Field(
+        default=None
+    )  # optional for backwards compatibility
+    expiration: Optional[DateTime] = Field(default=None)
+    serializer: Serializer = Field(default_factory=PickleSerializer)
+    prefect_version: str = Field(default=prefect.__version__)
+    storage_block_id: Optional[uuid.UUID] = Field(default=None)
+
+    @field_validator("serializer", mode="before")
+    @classmethod
+    def _tolerate_unknown_serializer(
+        cls, value: Serializer | dict[str, Any] | Any
+    ) -> Serializer | dict[str, Any] | Any:
+        if isinstance(value, dict) and "type" in value:
+            try:
+                lookup_type(Serializer, dispatch_key=value["type"])
+            except KeyError:
+                return UnknownSerializer.model_construct(**value)
+            return Serializer(**value)
+        return value
+
+    def dump_bytes(self) -> bytes:
+        """
+        Serialize the metadata to bytes.
+
+        Returns:
+            bytes: the serialized metadata
+        """
+        return self.model_dump_json(serialize_as_any=True).encode()
+
+    @classmethod
+    def load_bytes(cls, data: bytes) -> "ResultRecordMetadata":
+        """
+        Deserialize metadata from bytes.
+
+        Args:
+            data: the serialized metadata
+
+        Returns:
+            ResultRecordMetadata: the deserialized metadata
+        """
+        return cls.model_validate_json(data)
+
+    def __eq__(self, other: Any) -> bool:
+        if not isinstance(other, ResultRecordMetadata):
+            return False
+        return (
+            self.storage_key == other.storage_key
+            and self.expiration == other.expiration
+            and self.serializer == other.serializer
+            and self.prefect_version == other.prefect_version
+            and self.storage_block_id == other.storage_block_id
+        )
+
+
+class ResultRecord(BaseModel, Generic[R]):
+    """
+    A record of a result.
+    """
+
+    metadata: ResultRecordMetadata
+    result: R
+    _persisted: bool = PrivateAttr(default=False)
+
+    @property
+    def is_persisted(self) -> bool:
+        return self._persisted
+
+    def mark_persisted(self) -> None:
+        self._persisted = True
+
+    @property
+    def expiration(self) -> DateTime | None:
+        return self.metadata.expiration
+
+    @property
+    def serializer(self) -> Serializer:
+        return self.metadata.serializer
+
+    def serialize_result(self) -> bytes:
+        try:
+            data = self.serializer.dumps(self.result)
+        except Exception as exc:
+            extra_info = (
+                'You can try a different serializer (e.g. result_serializer="json") '
+                "or disabling persistence (persist_result=False) for this flow or task."
+            )
+            # check if this is a known issue with cloudpickle and pydantic
+            # and add extra information to help the user recover
+
+            if (
+                isinstance(exc, TypeError)
+                and isinstance(self.result, BaseModel)
+                and str(exc).startswith("cannot pickle")
+            ):
+                try:
+                    from IPython.core.getipython import get_ipython
+
+                    if get_ipython() is not None:
+                        extra_info = inspect.cleandoc(
+                            """
+                            This is a known issue in Pydantic that prevents
+                            locally-defined (non-imported) models from being
+                            serialized by cloudpickle in IPython/Jupyter
+                            environments. Please see
+                            https://github.com/pydantic/pydantic/issues/8232 for
+                            more information. To fix the issue, either: (1) move
+                            your Pydantic class definition to an importable
+                            location, (2) use the JSON serializer for your flow
+                            or task (`result_serializer="json"`), or (3)
+                            disable result persistence for your flow or task
+                            (`persist_result=False`).
+                            """
+                        ).replace("\n", " ")
+                except ImportError:
+                    pass
+            raise SerializationError(
+                f"Failed to serialize object of type {type(self.result).__name__!r} with "
+                f"serializer {self.serializer.type!r}. {extra_info}"
+            ) from exc
+
+        return data
+
+    @model_validator(mode="before")
+    @classmethod
+    def coerce_old_format(cls, value: dict[str, Any] | Any) -> dict[str, Any]:
+        if isinstance(value, dict):
+            if TYPE_CHECKING:  # TODO: # isintance doesn't accept generic parameters
+                value = cast(dict[str, Any], value)
+            if "data" in value:
+                value["result"] = value.pop("data")
+            if "metadata" not in value:
+                value["metadata"] = {}
+            if "expiration" in value:
+                value["metadata"]["expiration"] = value.pop("expiration")
+            if "serializer" in value:
+                value["metadata"]["serializer"] = value.pop("serializer")
+            if "prefect_version" in value:
+                value["metadata"]["prefect_version"] = value.pop("prefect_version")
+        return value
+
+    def serialize_metadata(self) -> bytes:
+        return self.metadata.dump_bytes()
+
+    def serialize(
+        self,
+    ) -> bytes:
+        """
+        Serialize the record to bytes.
+
+        Returns:
+            bytes: the serialized record
+
+        """
+        return (
+            self.model_copy(update={"result": self.serialize_result()})
+            .model_dump_json(serialize_as_any=True)
+            .encode()
+        )
+
+    @classmethod
+    def deserialize(
+        cls, data: bytes, backup_serializer: Serializer | None = None
+    ) -> "ResultRecord[R]":
+        """
+        Deserialize a record from bytes.
+
+        Args:
+            data: the serialized record
+            backup_serializer: The serializer to use to deserialize the result record. Only
+                necessary if the provided data does not specify a serializer.
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        try:
+            instance = cls.model_validate_json(data)
+        except ValidationError:
+            if backup_serializer is None:
+                raise
+            else:
+                result = backup_serializer.loads(data)
+                return cls(
+                    metadata=ResultRecordMetadata(serializer=backup_serializer),
+                    result=result,
+                )
+        if isinstance(instance.result, bytes):
+            instance.result = instance.serializer.loads(instance.result)
+        elif isinstance(instance.result, str):
+            instance.result = instance.serializer.loads(instance.result.encode())
+        return instance
+
+    @classmethod
+    def deserialize_from_result_and_metadata(
+        cls, result: bytes, metadata: bytes
+    ) -> "ResultRecord[R]":
+        """
+        Deserialize a record from separate result and metadata bytes.
+
+        Args:
+            result: the result
+            metadata: the serialized metadata
+
+        Returns:
+            ResultRecord: the deserialized record
+        """
+        result_record_metadata = ResultRecordMetadata.load_bytes(metadata)
+        return cls(
+            metadata=result_record_metadata,
+            result=result_record_metadata.serializer.loads(result),
+        )
+
+    def __eq__(self, other: Any | "ResultRecord[Any]") -> bool:
+        if not isinstance(other, ResultRecord):
+            return False
+        return self.model_dump(include={"metadata", "result"}) == other.model_dump(
+            include={"metadata", "result"}
+        )