API Reference
< Back to docs
Switch to new Anvil Editor docs Switch to Classic Editor docs
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

Classes

AppResponder

Create an AppResponder object

Constructor

AppResponder(data=None, meta=None)

    Instance Methods

    load_app()

    Loads an app at it’s startup form/module

    load_form([form], *args, **kwargs)

    Open the specified form as a new page from a route

      load_module(module_name)

      Opens the specified module as a new page from a route

        CallContext

        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

        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

        Location Attributes

        city - string

        country - string

        latitude - float

        longitude - float

        subdivision - string

        StackFrame

        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.

        Capability

        Create a new ‘Capability’ object

        Constructor

        Capability()

        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_update(update)

          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’]

              HttpRequest

              Create a new ‘HttpRequest’ object

              Constructor

              HttpRequest()

              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. https://my-app.anvil.app/_/api

              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

              HttpResponse

              Create an HttpResponse object

              Constructor

              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.

                Functions

                background_task([fn_or_name]) (more info)

                When applied to a function as a decorator, the function becomes available to run in the background.

                • fn_or_name - The name by which you want to call your function.

                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([fn_or_name], [require_user]) (more info)

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

                  • fn_or_name - The name by which you want to call your function from the client.

                  • 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.

                    • environment_type - Pass 'published' to get the published URL

                    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.

                    • environment_type - Pass 'published' to get the published URL

                    get_background_task(id) → Task object (more info)

                    Returns the Task object of a background task from its id. You can get the task id from task.get_id().

                    • id - The id of a background task

                    get_session_id()

                    Returns the current session’s ID.

                    is_app_online()

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

                    launch_background_task(fn_name, [args]) → Task object (more info)

                    Launches a function to run in the background. The function must be decorated with @anvil.server.background_task. Returns a Task object.

                    • fn_name - The name of the background function to launch

                    • args - Arguments to pass into the background function

                    list_background_tasks([all_environments]) → list of Task objects (more info)

                    Returns a list of all Tasks running in the current environment. If all_environments is True, this function will return all of the app’s running Tasks regardless of environemnt.

                    • all_environments - Defaults to False. If False, the function will only return background tasks running in the environment in which this function was called. If True, the return value will include all background tasks regardless of environment.

                    loading_indicator(component_name=None, min_height=None) → context

                    By default, a loading indicator is displayed when your app is retrieving data. This stops users from being able to interact with your app while the server returns data. loading_indicator is a context manager which allows you to create loading indicators manually.

                    • component_name - Optionally give the component or container that the loading indicator should overlay. This will block any user interaction with the given component, and any child components they have.

                    • min_height - Optionally set the minimum height of the loading indicator. If no minimum height is given and no `component_name` is given, it defaults to the size of the image or SVG being used. If no minimum height is given but a `component_name` _is_ given, then the indicator scales to fit the component or container.

                    portable_class([name])

                    When applied to a class as a decorator, the class becomese available to be passed from server to client code.

                    • name - A unique name under which the class will be registered.

                    reset_session()

                    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.)

                      Globals

                      context

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

                      no_loading_indicator

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

                      request

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

                      session

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

                      Exceptions

                      AppOfflineError

                      Create a new ‘AppOfflineError’ object

                      BackgroundTaskError

                      Create a new ‘BackgroundTaskError’ object

                      BackgroundTaskKilled

                      Create a new ‘BackgroundTaskKilled’ object

                      BackgroundTaskNotFound

                      Create a new ‘BackgroundTaskNotFound’ object

                      ExecutionTerminatedError

                      Create a new ‘ExecutionTerminatedError’ object

                      InternalError

                      Create a new ‘InternalError’ object

                      InvalidResponseError

                      Create a new ‘InvalidResponseError’ object

                      NoServerFunctionError

                      Create a new ‘NoServerFunctionError’ object

                      PermissionDenied

                      Create a new ‘PermissionDenied’ object

                      QuotaExceededError

                      Create a new ‘QuotaExceededError’ object

                      RuntimeUnavailableError

                      Create a new ‘RuntimeUnavailableError’ object

                      SerializationError

                      Create a new ‘SerializationError’ object

                      ServiceNotAdded

                      Create a new ‘ServiceNotAdded’ object

                      SessionExpiredError

                      Create a new ‘SessionExpiredError’ object

                      TimeoutError

                      Create a new ‘TimeoutError’ object

                      UplinkDisconnectedError

                      Create a new ‘UplinkDisconnectedError’ object

                      Do you still have questions?

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

                      anvil.secrets anvil.server [uplink]

                      anvil.server