Function Annotations¶
For programming in general, function parameters drive a function’s
dynamic behavior; a function’s output depends normally on its inputs.
With uplink
, function arguments parametrize an HTTP request,
and you indicate the dynamic parts of the request by appropriately
annotating those arguments with the classes detailed in this section.
Path¶
-
class
uplink.
Path
(name=None, type=None)¶ Substitution of a path variable in a URI template.
URI template parameters are enclosed in braces (e.g.,
{name}
). To map an argument to a declared URI parameter, use thePath
annotation:class TodoService(object): @get("/todos{/id}") def get_todo(self, todo_id: Path("id")): pass
Then, invoking
get_todo
with a consumer instance:todo_service.get_todo(100)
creates an HTTP request with a URL ending in
/todos/100
.Note
Any unannotated function argument that shares a name with a URL path parameter is implicitly annotated with this class at runtime.
For example, we could simplify the method from the previous example by matching the path variable and method argument names:
@get("/todos{/id}") def get_todo(self, id): pass
Query¶
-
class
uplink.
Query
(name=None, encoded=False, type=None, encode_none=None)¶ Set a dynamic query parameter.
This annotation turns argument values into URL query parameters. You can include it as function argument annotation, in the format:
<query argument>: uplink.Query
.If the API endpoint you are trying to query uses
q
as a query parameter, you can addq: uplink.Query
to the consumer method to set theq
search term at runtime.Example
@get("/search/commits") def search(self, search_term: Query("q")): """Search all commits with the given search term."""
To specify whether or not the query parameter is already URL encoded, use the optional
encoded
argument:@get("/search/commits") def search(self, search_term: Query("q", encoded=True)): """Search all commits with the given search term."""
To specify if and how
None
values should be encoded, use the optionalencode_none
argument:@get("/search/commits") def search(self, search_term: Query("q"), search_order: Query("o", encode_none="null")): """ Search all commits with the given search term using the optional search order. """
Parameters:
QueryMap¶
-
class
uplink.
QueryMap
(encoded=False, type=None)¶ A mapping of query arguments.
If the API you are using accepts multiple query arguments, you can include them all in your function method by using the format:
<query argument>: uplink.QueryMap
Example
@get("/search/users") def search(self, **params: QueryMap): """Search all users."""
Parameters: encoded ( bool
, optional) – Specifies whether the parametername
and value are already URL encoded.
Header¶
-
class
uplink.
Header
(name=None, type=None)¶ Pass a header as a method argument at runtime.
While
uplink.headers
attaches static headers that define all requests sent from a consumer method, this class turns a method argument into a dynamic header value.Example
@get("/user") def (self, session_id: Header("Authorization")): """Get the authenticated user"""
Field¶
-
class
uplink.
Field
(name=None, type=None)¶ Defines a form field to the request body.
Use together with the decorator
uplink.form_url_encoded
and annotate each argument accepting a form field withuplink.Field
.- Example::
@form_url_encoded @post("/users/edit") def update_user(self, first_name: Field, last_name: Field): """Update the current user."""
FieldMap¶
-
class
uplink.
FieldMap
(type=None)¶ Defines a mapping of form fields to the request body.
Use together with the decorator
uplink.form_url_encoded
and annotate each argument accepting a form field withuplink.FieldMap
.Example
@form_url_encoded @post("/user/edit") def create_post(self, **user_info: FieldMap): """Update the current user."""
Part¶
-
class
uplink.
Part
(name=None, type=None)¶ Marks an argument as a form part.
Use together with the decorator
uplink.multipart
and annotate each form part withuplink.Part
.Example
@multipart @put(/user/photo") def update_user(self, photo: Part, description: Part): """Upload a user profile photo."""
PartMap¶
-
class
uplink.
PartMap
(type=None)¶ A mapping of form field parts.
Use together with the decorator
uplink.multipart
and annotate each part of form parts withuplink.PartMap
Example
@multipart @put(/user/photo") def update_user(self, photo: Part, description: Part): """Upload a user profile photo."""
Body¶
-
class
uplink.
Body
(type=None)¶ Set the request body at runtime.
Use together with the decorator
uplink.json
. The method argument value will become the request’s body when annotated withuplink.Body
.Example
@json @patch(/user") def update_user(self, **info: Body): """Update the current user."""
Url¶
-
class
uplink.
Url
¶ Sets a dynamic URL.
Provides the URL at runtime as a method argument. Drop the decorator parameter path from
uplink.get
and annotate the corresponding argument withuplink.Url
Example
@get def get(self, endpoint: Url): """Execute a GET requests against the given endpoint"""