You are currently viewing the new Anvil Editor Docs.
Switch to the Classic Editor Docs
You are currently viewing the Classic Editor Docs.
Switch to the new Anvil Editor Docs

anvil.server Module



CallContext Attributes

background_task_id - string

The ID of the currently running background task, if there is one.

client - anvil.server.CallContext.ClientInfo instance

An object that describes the client that initiated the current session. This can be a browser, an HTTP endpoint request, an uplink script, a background task, or an incoming email.

remote_caller - anvil.server.CallContext.StackFrame instance

An object describing the code that called this @anvil.server.callable function, where it was running, and whether it is trusted (server-side) or un-trusted (input from a browser, HTTP or other remote code)

type - string

The execution environment this code is running in. May be ‘browser’, ‘server_module’ or ‘uplink’


ClientInfo Attributes

ip - string

The IP address of the client that initiated this session.

location - anvil.server.CallContext.Location instance

The location of this client, as determined by its IP address, or None if it cannot be determined.

type - string

How this session was initiated. Valid values are: ‘browser’, ‘uplink’, ‘http’, ‘background_task’ and ’email’.


Location Attributes

city - string

country - string

latitude - float

longitude - float

subdivision - string


StackFrame Attributes

is_trusted - boolean

Was this code running in a trusted location (ie on the server side)?

type - string

The location of the calling code. Valid values are: ‘browser’, ‘server_module’, ‘uplink’ and ‘client_uplink’ for your app’s code, or ‘http’, ‘background_task’ or ’email’ if this code was extrernally triggered.


Create a new ‘Capability’ object



Instance Methods

narrow(additional_scope) → anvil.server.Capability instance

Return a new capability that is narrower than this one, by appending additional scope element(s) to it.


    Send an update to the update handler for this capability, in this interpreter and also in any calling environment (eg browser code) that passed this capability into the current server function.

      set_update_handler(apply_update, [get_update])

      Set a handler for what happens when an update is sent to this capability.

      Optionally provide a function for aggregating updates (default behaviour is to merge them, if they are all dictionaries, or to return only the most recent update otherwise.)

        Capability Attributes

        is_valid - boolean

        True if this Capability is still valid; False if it has been invalidated (for example, by session expiry)

        scope - list

        A list representing what this capability represents. It can be extended by calling narrow(), but not shortened.

        Eg: [‘my_resource’, 42, ‘foo’]


        Create a new ‘HttpRequest’ object



        HttpRequest Attributes

        body - anvil.Media instance

        The body of the HTTP request

        body_json - dict

        The decoded JSON body of the HTTP request, if applicable. Only available when Content-Type header is ‘application/json’.

        form_params - dict

        A dict of form parameters passed with this request.

        headers - dict

        HTTP headers sent with the current request

        method - string

        The HTTP method of the current request, e.g. GET, POST, etc.

        origin - string

        The origin of the current API request, e.g.

        password - string

        The password received through HTTP Basic Authentication

        path - string

        The path of the current request, e.g. /foo/bar

        query_params - dict

        A dict of query-string parameters passed with this request.

        remote_address - string

        The IP address the current request is coming from.

        user - User

        When require_auth is True, returns the row from the Users table corresponding to the authenticated user.

        username - string

        The username received through HTTP Basic Authentication


        Create an HttpResponse object


        HttpResponse(status=200, body="", headers=None)

          HttpResponse Attributes

          body - any

          The body of this HTTP response. Can be a string, a Media object, or any JSON-able value.

          headers - dict

          The headers to return with this HTTP response. Content-Type will be set automatically if not specified.

          status - number

          The status code for this HTTP response. Default is 200.


          call(function_name, **kwargs)

          Allows you to call server-side functions from the client. It requires the name of the function that you want to call, passed as a string. Any extra arguments are passed through to the server function.

            callable([name], [require_user]) (more info)

            When applied to a function as a decorator, the function becomes available from the client side.

            • require_user - Allows you to verify whether a user is logged in. Can be a boolean or a function.

            FormResponse([form], *args, **kws) (more info)

            Open the specified form as a new page from a route.

            ‘form’ is a string, and when received by the client the new form will be created (extra arguments will be passed to its constructor).

              get_api_origin([environment_type]) → string (more info)

              Returns the root URL of the API for the current app.

              By default, this function returns the URL for the current environment, which might be private or temporary (for example, if you are running your app in the Anvil Editor). If you want the URL for the published branch, pass ‘published’ as an argument.

                get_app_origin([environment_type]) → string (more info)

                Returns the root URL for the current app.

                By default, this function returns the URL for the current environment, which might be private or temporary (for example, if you are running your app in the Anvil Editor). If you want the URL for the published branch, pass ‘published’ as an argument.


                  Returns the current session’s ID.


                  Returns True if this app is online and False otherwise. If anvil.server.is_app_online() returns False we expect to throw an anvil.server.AppOfflineError


                  Reset the current session to prevent further SessionExpiredErrors.

                  unwrap_capability(capability, scope_pattern) → list

                  Checks that its first argument is a valid Capability, and that its scope matches the supplied pattern.

                  To match, the scope must:

                  • Be at least as broad as the pattern (ie the same length or shorter)
                  • Contain the same values in the same position as the pattern - unless that position in the pattern is Capability.ANY, which matches any value

                  Returns a list of matched scope elements, of the same length as the pattern. (If the scope was broader than required, missing elements are set to None.)



                    Contains information about what triggered the currently running code. It’s an instance of anvil.server.CallContext.


                    Use with anvil.server.no_loading_indicator: to suppress the loading indicator when making server calls


                    Contains information about the current HTTP API request. It’s an instance of anvil.server.HttpRequest.


                    A dictionary that contains information about a specific session. It can store anything that a server function can return, except for Media objects.



                    Create a new ‘AppOfflineError’ object


                    Create a new ‘BackgroundTaskError’ object


                    Create a new ‘BackgroundTaskKilled’ object


                    Create a new ‘BackgroundTaskNotFound’ object


                    Create a new ‘ExecutionTerminatedError’ object


                    Create a new ‘InternalError’ object


                    Create a new ‘InvalidResponseError’ object


                    Create a new ‘NoServerFunctionError’ object


                    Create a new ‘PermissionDenied’ object


                    Create a new ‘QuotaExceededError’ object


                    Create a new ‘RuntimeUnavailableError’ object


                    Create a new ‘SerializationError’ object


                    Create a new ‘ServiceNotAdded’ object


                    Create a new ‘SessionExpiredError’ object


                    Create a new ‘TimeoutError’ object


                    Create a new ‘UplinkDisconnectedError’ object

                    Do you still have questions?

                    Our Community Forum is full of helpful information and Anvil experts.