From ac13546fa24c07ffeb79acf9cf6913258e91e953 Mon Sep 17 00:00:00 2001 From: Kenneth Rodrigues Date: Wed, 4 Sep 2024 17:06:41 +0530 Subject: [PATCH] docs: Remove `has_request_variables` and `REQ`. --- api_docs/incoming-webhooks-walkthrough.md | 11 ++++++----- docs/outreach/gsoc.md | 20 -------------------- 2 files changed, 6 insertions(+), 25 deletions(-) diff --git a/api_docs/incoming-webhooks-walkthrough.md b/api_docs/incoming-webhooks-walkthrough.md index 0e214ef8ec..7cdbd255e4 100644 --- a/api_docs/incoming-webhooks-walkthrough.md +++ b/api_docs/incoming-webhooks-walkthrough.md @@ -146,7 +146,7 @@ integration and is always lower-case. At minimum, the webhook function must accept `request` (Django [HttpRequest](https://docs.djangoproject.com/en/5.0/ref/request-response/#django.http.HttpRequest) object), and `user_profile` (Zulip's user object). You may also want to -define additional parameters using the `REQ` object. +define additional parameters using the `typed_endpoint` decorator. In the example above, we have defined `payload` which is populated from the body of the http request, `stream` with a default of `test` @@ -569,10 +569,11 @@ For example, here is the definition of a webhook function that gets both `stream and `topic` from the query parameters: ```python +@typed_endpoint def api_querytest_webhook(request: HttpRequest, user_profile: UserProfile, - payload: str=REQ(argument_type='body'), - stream: str=REQ(default='test'), - topic: str=REQ(default='Default Alert')): + payload: Annotated[str, ApiParamConfig(argument_type_is_body=True)], + stream: str = "test", + topic: str= "Default Alert": ``` In actual use, you might configure the 3rd party service to call your Zulip @@ -583,7 +584,7 @@ http://myhost/api/v1/external/querytest?api_key=abcdefgh&stream=alerts&topic=que ``` It provides values for `stream` and `topic`, and the webhook can get those -using `REQ` without any special handling. How does this work in a test? +using `@typed_endpoint` without any special handling. How does this work in a test? The new attribute `TOPIC` exists only in our class so far. In order to construct a URL with a query parameter for `topic`, you can pass the diff --git a/docs/outreach/gsoc.md b/docs/outreach/gsoc.md index 8fd58320ae..cd16f87124 100644 --- a/docs/outreach/gsoc.md +++ b/docs/outreach/gsoc.md @@ -131,26 +131,6 @@ Django, TypeScript/JavaScript, and CSS. [typescript-migration]: https://chat.zulip.org/#narrow/channel/6-frontend/topic/typescript.20migration -- Migrate server's Python codebase from the legacy - `@has_request_variables` decorator to the new `@typed_endpoint` - decorator, and update our contributor documentation to recommend the - new system. The `@typed_endpoint` framework uses [Pydantic - V2](https://docs.pydantic.dev/latest/) in order to better express - how we want to parse API requests and turn them into fully typed - Python objects. **Skills required**: A good understanding of the - Python 3 / mypy type system and Pydantic 2, and the ability to - efficiently read Python code and write clear, structured commits. No - prior Pydantic experience required, but please take the time to go - through the Pydantic upstream tutorials and skim all the existing - endpoints using `typed_endpoint` before doing your first Zulip - changes. A good first PR is to migrate a smaller views file to the new - framework; one commit per smaller file is likely to be a good - structure. See the last commits from [the new framework's main - PR](https://github.com/zulip/zulip/pull/26365) for examples of - well-written migration commits. - - Expert: Zixuan James Li, Anders Kaseorg - - Contribute to Zulip's [**migration to user groups for permissions**][user-group-permissions]. This migration is intended to replace every setting in Zulip that currently allows organizations to assign