Skip to content

docs: move 3.1.2 migration section to top of MIGRATION.md #50

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.

Sign up for GitHub

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

Merged
tyler5673 merged 1 commit into from
Aug 21, 2026
Merged

docs: move 3.1.2 migration section to top of MIGRATION.md #50

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
123 changes: 62 additions & 61 deletions MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,67 @@
# Migration Guide

## 3.1.1 → 3.1.2

> **Additive release.** No parameter is renamed, removed, or changed in
> meaning. Two changes can require an edit, and only in narrow cases.

### Action required

| Change | Who is affected | What to do |
|--------|-----------------|------------|
| Import machinery no longer re-exported from the package root | Anyone importing a stdlib/typing name or internal helper *from* `youdotcom` | Import it from its real home. See [Root namespace narrowing](#root-namespace-narrowing) |
| `ResearchTaskStreamEvent.event` is typed `Union[Event, str]` | Type-checked code calling `evt.event.value` | Guard with `isinstance(evt.event, Event)`. See [SSE event names](#sse-event-names) |

### Root namespace narrowing

`youdotcom/__init__.py` no longer does `from .sdk import *`, so the names
those statements pulled in transitively are no longer attributes of
`youdotcom`. This is what makes `import youdotcom` transport-free inside a
Temporal Workflow sandbox.

```python
# Before (3.1.1): worked by accident.
from youdotcom import httpx, Optional, eventstreaming

# After (3.1.2): ImportError. Import from the real module.
import httpx
from typing import Optional
from youdotcom.utils import eventstreaming
```

Everything documented still resolves from the root, including under
`from youdotcom import *`:

```python
from youdotcom import You, SDKConfiguration, RetryConfig, BackoffStrategy
from youdotcom import models, errors, utils, types
import youdotcom.sdk # private submodules still import directly
```

### SSE event names

The `event` field on `ResearchTaskStreamEvent` accepts event names this SDK
version does not enumerate, so an added server-side event no longer raises
`ResponseValidationError`. Known names still resolve to `Event` members;
unknown names arrive as plain `str`. The declared type now says so, which
means an unguarded `.value` becomes a type error:

```python
# Type error on 3.1.2 -- and an AttributeError at runtime, on 3.1.1 too,
# the first time the server emits a name this SDK doesn't know.
print(evt.event.value)

# Guarded: correct on both versions.
if isinstance(evt.event, Event):
print(evt.event.value)
else:
print(evt.event)

# Comparing against raw strings needs no guard -- Event members are `str`.
if evt.event == "completed":
...
```

## 2.5.0 → 3.0.0

@factory-droid factory-droid Bot Aug 21, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep migration sections in consistent order

This moves 3.1.1 → 3.1.2 to the top, but the next section is 2.5.0 → 3.0.0 while 3.0.0 → 3.1.0 still appears later, so the guide is no longer newest-first. Consider moving 3.0.0 → 3.1.0 directly below 3.1.1 → 3.1.2 (or documenting the intended ordering rule) to avoid confusing readers looking for the next migration step.


> **This release adds the Answer API, removes the Agents API, and makes `search()` a direct method on `You`.** The old sub-SDK patterns still work but emit `DeprecationWarning`. Migrate at your convenience.
Expand Down Expand Up @@ -297,67 +359,6 @@ with You(api_key_auth=os.getenv("YDC_API_KEY"), timeout_ms=60_000) as you:
# str(deprecations[0].message) == "livecrawl is deprecated; use extraction instead"
```

## 3.1.1 → 3.1.2

> **Additive release.** No parameter is renamed, removed, or changed in
> meaning. Two changes can require an edit, and only in narrow cases.

### Action required

| Change | Who is affected | What to do |
|--------|-----------------|------------|
| Import machinery no longer re-exported from the package root | Anyone importing a stdlib/typing name or internal helper *from* `youdotcom` | Import it from its real home. See [Root namespace narrowing](#root-namespace-narrowing) |
| `ResearchTaskStreamEvent.event` is typed `Union[Event, str]` | Type-checked code calling `evt.event.value` | Guard with `isinstance(evt.event, Event)`. See [SSE event names](#sse-event-names) |

### Root namespace narrowing

`youdotcom/__init__.py` no longer does `from .sdk import *`, so the names
those statements pulled in transitively are no longer attributes of
`youdotcom`. This is what makes `import youdotcom` transport-free inside a
Temporal Workflow sandbox.

```python
# Before (3.1.1): worked by accident.
from youdotcom import httpx, Optional, eventstreaming

# After (3.1.2): ImportError. Import from the real module.
import httpx
from typing import Optional
from youdotcom.utils import eventstreaming
```

Everything documented still resolves from the root, including under
`from youdotcom import *`:

```python
from youdotcom import You, SDKConfiguration, RetryConfig, BackoffStrategy
from youdotcom import models, errors, utils, types
import youdotcom.sdk # private submodules still import directly
```

### SSE event names

The `event` field on `ResearchTaskStreamEvent` accepts event names this SDK
version does not enumerate, so an added server-side event no longer raises
`ResponseValidationError`. Known names still resolve to `Event` members;
unknown names arrive as plain `str`. The declared type now says so, which
means an unguarded `.value` becomes a type error:

```python
# Type error on 3.1.2 -- and an AttributeError at runtime, on 3.1.1 too,
# the first time the server emits a name this SDK doesn't know.
print(evt.event.value)

# Guarded: correct on both versions.
if isinstance(evt.event, Event):
print(evt.event.value)
else:
print(evt.event)

# Comparing against raw strings needs no guard -- Event members are `str`.
if evt.event == "completed":
...
```

## 2.4.0 → 2.5.0

Expand Down
Loading