Adds Python version of durable objects examples (#26809)

Author: dom96

src/content/docs/durable-objects/examples/alarms-api.mdx

@@ -7,14 +7,16 @@ sidebar:
 description: Use the Durable Objects Alarms API to batch requests to a Durable Object.
 ---
 
-import { GlossaryTooltip, WranglerConfig } from "~/components";
+import { GlossaryTooltip, TabItem, Tabs, WranglerConfig } from "~/components";
 
 This example implements an <GlossaryTooltip term="alarm">`alarm()`</GlossaryTooltip> handler that allows batching of requests to a single Durable Object.
 
 When a request is received and no alarm is set, it sets an alarm for 10 seconds in the future. The `alarm()` handler processes all requests received within that 10-second window.
 
 If no new requests are received, no further alarms will be set until the next request arrives.
 
+<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
+
 ```js
 import { DurableObject } from "cloudflare:workers";
 
@@ -25,8 +27,6 @@ export default {
 	},
 };
 
-const SECONDS = 10;
-
 // Durable Object
 export class Batcher extends DurableObject {
 	constructor(ctx, env) {
@@ -45,7 +45,7 @@ export class Batcher extends DurableObject {
 		// Any further POSTs in the next 10 seconds will be part of this batch.
 		let currentAlarm = await this.storage.getAlarm();
 		if (currentAlarm == null) {
-			this.storage.setAlarm(Date.now() + 1000 * SECONDS);
+			this.storage.setAlarm(Date.now() + 1000 * 10);
 		}
 
 		// Add the request to the batch.
@@ -69,6 +69,59 @@ export class Batcher extends DurableObject {
 }
 ```
 
+</TabItem><TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject, Response, WorkerEntrypoint, fetch
+import time
+
+# Worker
+class Default(WorkerEntrypoint):
+	async def fetch(self, request):
+		stub = self.env.BATCHER.getByName("foo")
+		return await stub.fetch(request)
+
+# Durable Object
+class Batcher(DurableObject):
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+		self.storage = ctx.storage
+
+		@self.ctx.blockConcurrencyWhile
+		async def initialize():
+			vals = await self.storage.list(reverse=True, limit=1)
+			self.count = 0
+			if len(vals) > 0:
+			    self.count = int(vals.keys().next().value)
+
+	async def fetch(self, request):
+		self.count += 1
+
+		# If there is no alarm currently set, set one for 10 seconds from now
+		# Any further POSTs in the next 10 seconds will be part of this batch.
+		current_alarm = await self.storage.getAlarm()
+		if current_alarm is None:
+			self.storage.setAlarm(int(time.time() * 1000) + 1000 * 10)
+
+		# Add the request to the batch.
+		await self.storage.put(self.count, await request.text())
+		return Response.json(
+			{"queued": self.count}
+		)
+
+	async def alarm(self):
+		vals = await self.storage.list()
+		await fetch(
+			"http://example.com/some-upstream-service",
+			method="POST",
+			body=list(vals.values())
+		)
+		await self.storage.deleteAll()
+		self.count = 0
+```
+
+</TabItem> </Tabs>
+
 The `alarm()` handler will be called once every 10 seconds. If an unexpected error terminates the Durable Object, the `alarm()` handler will be re-instantiated on another machine. Following a short delay, the `alarm()` handler will run from the beginning on the other machine.
 
 Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

src/content/docs/durable-objects/examples/build-a-counter.mdx

@@ -148,6 +148,68 @@ export class Counter extends DurableObject {
 }
 ```
 
+</TabItem> <TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject, Response, WorkerEntrypoint
+from urllib.parse import urlparse, parse_qs
+
+# Worker
+class Default(WorkerEntrypoint):
+	async def fetch(self, request):
+		parsed_url = urlparse(request.url)
+		query_params = parse_qs(parsed_url.query)
+		name = query_params.get('name', [None])[0]
+
+		if not name:
+			return Response(
+				"Select a Durable Object to contact by using"
+				+ " the `name` URL query string parameter, for example, ?name=A"
+			)
+
+		# A stub is a client Object used to send messages to the Durable Object.
+		stub = self.env.COUNTERS.getByName(name)
+
+		# Send a request to the Durable Object using RPC methods, then await its response.
+		count = None
+
+		if parsed_url.path == "/increment":
+			count = await stub.increment()
+		elif parsed_url.path == "/decrement":
+			count = await stub.decrement()
+		elif parsed_url.path == "" or parsed_url.path == "/":
+			# Serves the current value.
+			count = await stub.getCounterValue()
+		else:
+			return Response("Not found", status=404)
+
+		return Response(f"Durable Object '{name}' count: {count}")
+
+# Durable Object
+class Counter(DurableObject):
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+
+	async def getCounterValue(self):
+		value = await self.ctx.storage.get("value")
+		return value if value is not None else 0
+
+	async def increment(self, amount=1):
+		value = await self.ctx.storage.get("value")
+		value = (value if value is not None else 0) + amount
+		# You do not have to worry about a concurrent request having modified the value in storage.
+		# "input gates" will automatically protect against unwanted concurrency.
+		# Read-modify-write is safe.
+		await self.ctx.storage.put("value", value)
+		return value
+
+	async def decrement(self, amount=1):
+		value = await self.ctx.storage.get("value")
+		value = (value if value is not None else 0) - amount
+		await self.ctx.storage.put("value", value)
+		return value
+```
+
 </TabItem> </Tabs>
 
 Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.

src/content/docs/durable-objects/examples/build-a-rate-limiter.mdx

@@ -198,6 +198,70 @@ export class RateLimiter extends DurableObject {
 }
 ```
 
+</TabItem> <TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject, Response, WorkerEntrypoint
+import time
+
+# Worker
+class Default(WorkerEntrypoint):
+	async def fetch(self, request):
+		# Determine the IP address of the client
+		ip = request.headers.get("CF-Connecting-IP")
+		if ip is None:
+			return Response("Could not determine client IP", status=400)
+
+		try:
+			stub = self.env.RATE_LIMITER.getByName(ip)
+			milliseconds_to_next_request = await stub.getMillisecondsToNextRequest()
+			if milliseconds_to_next_request > 0:
+				# Alternatively one could sleep for the necessary length of time
+				return Response("Rate limit exceeded", status=429)
+		except Exception as error:
+			return Response("Could not connect to rate limiter", status=502)
+
+		# TODO: Implement me
+		return Response("Call some upstream resource...")
+
+# Durable Object
+class RateLimiter(DurableObject):
+	milliseconds_per_request = 1
+	milliseconds_for_updates = 5000
+	capacity = 10000
+
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+		self.tokens = RateLimiter.capacity
+
+	async def getMillisecondsToNextRequest(self):
+		await self.checkAndSetAlarm()
+
+		milliseconds_to_next_request = RateLimiter.milliseconds_per_request
+		if self.tokens > 0:
+			self.tokens -= 1
+			milliseconds_to_next_request = 0
+
+		return milliseconds_to_next_request
+
+	async def checkAndSetAlarm(self):
+		current_alarm = await self.ctx.storage.getAlarm()
+		if current_alarm is None:
+			self.ctx.storage.setAlarm(
+				int(time.time() * 1000)
+				+ RateLimiter.milliseconds_for_updates
+				* RateLimiter.milliseconds_per_request
+			)
+
+	async def alarm(self):
+		if self.tokens < RateLimiter.capacity:
+			self.tokens = min(
+				RateLimiter.capacity,
+				self.tokens + RateLimiter.milliseconds_for_updates,
+			)
+			await self.checkAndSetAlarm()
+```
+
 </TabItem>
 </Tabs>
 
@@ -267,6 +331,34 @@ export class RateLimiter extends DurableObject {
 }
 ```
 
+</TabItem> <TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject
+import time
+
+# Durable Object
+class RateLimiter(DurableObject):
+	milliseconds_per_request = 1
+	milliseconds_for_grace_period = 5000
+
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+		self.nextAllowedTime = 0
+
+	async def getMillisecondsToNextRequest(self):
+		now = int(time.time() * 1000)
+
+		self.nextAllowedTime = max(now, self.nextAllowedTime)
+		self.nextAllowedTime += RateLimiter.milliseconds_per_request
+
+		value = max(
+			0,
+			self.nextAllowedTime - now - RateLimiter.milliseconds_for_grace_period,
+		)
+		return value
+```
+
 </TabItem>
 </Tabs>
 

src/content/docs/durable-objects/examples/durable-object-in-memory-state.mdx

@@ -9,10 +9,12 @@ description: Create a Durable Object that stores the last location it was
   accessed from in-memory.
 ---
 
-import { WranglerConfig } from "~/components";
+import { TabItem, Tabs, WranglerConfig } from "~/components";
 
 This example shows you how Durable Objects are stateful, meaning in-memory state can be retained between requests. After a brief period of inactivity, the Durable Object will be evicted, and all in-memory state will be lost. The next request will reconstruct the object, but instead of showing the city of the previous request, it will display a message indicating that the object has been reinitialized. If you need your applications state to survive eviction, write the state to storage by using the [Storage API](/durable-objects/api/sqlite-storage-api/), or by storing your data elsewhere.
 
+<Tabs> <TabItem label="JavaScript" icon="seti:javascript">
+
 ```js
 import { DurableObject } from "cloudflare:workers";
 
@@ -65,6 +67,55 @@ New Location: ${request.cf.city}`);
 }
 ```
 
+</TabItem> <TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject, Response, WorkerEntrypoint
+
+# Worker
+class Default(WorkerEntrypoint):
+	async def fetch(self, request):
+		return await handle_request(request, self.env)
+
+async def handle_request(request, env):
+	stub = env.LOCATION.getByName("A")
+	# Forward the request to the remote Durable Object.
+	resp = await stub.fetch(request)
+	# Return the response to the client.
+	return Response(await resp.text())
+
+# Durable Object
+class Location(DurableObject):
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+		# Upon construction, you do not have a location to provide.
+		# This value will be updated as people access the Durable Object.
+		# When the Durable Object is evicted from memory, this will be reset.
+		self.location = None
+
+	# Handle HTTP requests from clients.
+	async def fetch(self, request):
+		response = None
+
+		if self.location is None:
+			response = f"""
+This is the first request, you called the constructor, so this.location was null.
+You will set this.location to be your city: ({request.js_object.cf.city}). Try reloading the page."""
+		else:
+			response = f"""
+The Durable Object was already loaded and running because it recently handled a request.
+
+Previous Location: {self.location}
+New Location: {request.js_object.cf.city}"""
+
+		# You set the new location to be the new city.
+		self.location = request.js_object.cf.city
+		print(response)
+		return Response(response)
+```
+
+</TabItem> </Tabs>
+
 Finally, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.
 
 <WranglerConfig>

src/content/docs/durable-objects/examples/durable-object-ttl.mdx

@@ -89,6 +89,35 @@ export default {
 } satisfies ExportedHandler<Env>;
 ```
 
+</TabItem> <TabItem label="Python" icon="seti:python">
+
+```py
+from workers import DurableObject, Response, WorkerEntrypoint
+import time
+
+# Durable Object
+class MyDurableObject(DurableObject):
+	# Time To Live (TTL) in milliseconds
+	timeToLiveMs = 1000
+
+	def __init__(self, ctx, env):
+		super().__init__(ctx, env)
+
+	async def fetch(self, _request):
+		# Extend the TTL immediately following every fetch request to a Durable Object.
+		await self.ctx.storage.setAlarm(int(time.time() * 1000) + self.timeToLiveMs)
+		...
+
+	async def alarm(self):
+		await self.ctx.storage.deleteAll()
+
+# Worker
+class Default(WorkerEntrypoint):
+	async def fetch(self, request):
+		stub = self.env.MY_DURABLE_OBJECT.getByName("foo")
+		return await stub.fetch(request)
+```
+
 </TabItem> </Tabs>
 
 To test and deploy this example, configure your Wrangler file to include a Durable Object [binding](/durable-objects/get-started/#4-configure-durable-object-bindings) and [migration](/durable-objects/reference/durable-objects-migrations/) based on the namespace and class name chosen previously.