docs: describe migration from v0.2 to v0.3 (#46)

* docs: describe migration * docs: clean up examples * docs: add trailing newlines * docs: update migration guide --------- Co-authored-by: Stainless Bot <[email protected]> Co-authored-by: Robert Craigie <[email protected]>
anthropics · Jun 27, 2023 · 31c7256 · 31c7256
1 parent 8d1d6af
commit 31c7256
Show file tree

Hide file tree

Showing 3 changed files with 68 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -6,6 +6,70 @@ The Anthropic Python library provides convenient access to the Anthropic REST AP
 application. It includes type definitions for all request params and response fields,
 and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx).
 
+## Migration from v0.2.x and below
+
+In `v0.3.0`, we introduced a fully rewritten SDK.
+
+The new version uses separate sync and async clients, unified streaming, typed params and structured response objects, and resource-oriented methods:
+
+**Sync before/after:**
+
+```diff
+- client = anthropic.Client(os.environ["ANTHROPIC_API_KEY"])
++ client = anthropic.Anthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+  # or, simply provide an ANTHROPIC_API_KEY environment variable:
++ client = anthropic.Anthropic();
+
+- rsp = client.completion(**params)
+- rsp["completion"]
++ rsp = client.completions.create(**params)
++ rsp.completion
+```
+
+**Async before/after:**
+
+```diff
+- client = anthropic.Client(os.environ["ANTHROPIC_API_KEY"])
++ client = anthropic.AsyncAnthropic(api_key=os.environ["ANTHROPIC_API_KEY"])
+
+- await client.acompletion(**params)
++ await client.completions.create(**params)
+```
+
+The `.completion_stream()` and `.acompletion_stream()` methods have been removed;
+simply pass `stream=True`to `.completions.create()`.
+
+Streaming responses are now incremental; the full text is not sent in each message,
+as v0.3 sends the `Anthropic-Version: 2023-06-01` header.
+
+<details>
+<summary>Example streaming diff</summary>
+
+```diff py
+  import anthropic
+
+- client = anthropic.Client(os.environ["ANTHROPIC_API_KEY"])
++ client = anthropic.Anthropic()
+
+  # Streams are now incremental diffs of text
+  # rather than sending the whole message every time:
+  text = "
+- stream = client.completion_stream(**params)
+- for data in stream:
+-     diff = data["completion"].replace(text, "")
+-     text = data["completion"]
++ stream = client.completions.create(**params, stream=True)
++ for data in stream:
++     diff = data.completion # incremental text
++     text += data.completion
+      print(diff, end="")
+
+  print("Done. Final text is:")
+  print(text)
+```
+
+</details>
+
 ## Documentation
 
 The API documentation can be found [here](https://docs.anthropic.com/claude/reference/).
@@ -249,4 +313,4 @@ We are keen for your feedback; please open an [issue](https://www.github.com/ant
 
 ## Requirements
 
-Python 3.7 or higher.
+Python 3.7 or higher.
diff --git a/api.md b/api.md
@@ -15,4 +15,4 @@ from anthropic.types import Completion
 Methods:
 
 - <code title="post /v1/complete">client.completions.<a href="./src/anthropic/resources/completions.py">create</a>(\*\*<a href="src/anthropic/types/completion_create_params.py">params</a>) -> <a href="./src/anthropic/types/completion.py">Completion</a></code>
-- <code title="post /v1/complete">client.completions.<a href="./src/anthropic/resources/completions.py">create</a>(\*\*<a href="src/anthropic/types/completion_create_params.py">params</a>) -> <a href="./src/anthropic/types/completion.py">Completion</a></code>
+- <code title="post /v1/complete">client.completions.<a href="./src/anthropic/resources/completions.py">create</a>(\*\*<a href="src/anthropic/types/completion_create_params.py">params</a>) -> <a href="./src/anthropic/types/completion.py">Completion</a></code>
diff --git a/examples/streaming.py b/examples/streaming.py
@@ -14,7 +14,7 @@
 
 def sync_stream() -> None:
     stream = client.completions.create(
-        prompt=f"\n\nHuman: {question}\n\nAssistant:",
+        prompt=f"{HUMAN_PROMPT} {question}{AI_PROMPT}",
         model="claude-v1",
         stream=True,
         max_tokens_to_sample=300,
@@ -28,7 +28,7 @@ def sync_stream() -> None:
 
 async def async_stream() -> None:
     stream = await async_client.completions.create(
-        prompt=f"{HUMAN_PROMPT}{question}{AI_PROMPT}",
+        prompt=f"{HUMAN_PROMPT} {question}{AI_PROMPT}",
         model="claude-v1",
         stream=True,
         max_tokens_to_sample=300,