API

This part of the documentation covers all the interfaces of Flask. For parts where Flask depends on external libraries, we document the most important right here and provide links to the canonical documentation.

Objeto Application

Objetos Blueprint

Datos de la solicitud entrante

flask.request

To access incoming request data, you can use the global request object. Flask parses incoming request data for you and gives you access to it through that global object. Internally Flask makes sure that you always get the correct data for the active thread if you are in a multithreaded environment.

Se trata de un proxy. Consulte Notas sobre los apoderados para obtener más información.

El objeto request es una instancia de una Request.

Objetos de respuesta

Sesiones

Si has establecido Flask.secret_key (o lo has configurado desde SECRET_KEY) puedes utilizar sesiones en las aplicaciones Flask. Una sesión permite recordar información de una solicitud a otra. La forma en que Flask hace esto es utilizando una cookie firmada. El usuario puede ver el contenido de la sesión, pero no puede modificarlo a menos que conozca la clave secreta, así que asegúrate de establecerla con algo complejo e indescifrable.

Para acceder a la sesión actual puede utilizar el objeto session:

class flask.session

El objeto de sesión funciona de forma muy parecida a un dict ordinario, con la diferencia de que lleva la cuenta de las modificaciones.

Se trata de un proxy. Consulte Notas sobre los apoderados para obtener más información.

Los siguientes atributos son interesantes:

new

True si la sesión es nueva, False en caso contrario.

modified

True if the session object detected a modification. Be advised that modifications on mutable structures are not picked up automatically, in that situation you have to explicitly set the attribute to True yourself. Here an example:

# this change is not picked up because a mutable object (here
# a list) is changed.
session['objects'].append(42)
# so mark it as modified yourself
session.modified = True
permanent

If set to True the session lives for permanent_session_lifetime seconds. The default is 31 days. If set to False (which is the default) the session will be deleted when the user closes the browser.

Interfaz de la sesión

Changelog

Nuevo en la versión 0.8.

La interfaz de sesión proporciona una forma sencilla de reemplazar la implementación de sesión que utiliza Flask.

class flask.sessions.SessionInterface

La interfaz básica que tienes que implementar para reemplazar la interfaz de sesión por defecto que utiliza la implementación de securecookie de werkzeug. Los únicos métodos que tienes que implementar son open_session() y save_session(), los demás tienen útiles valores por defecto que no necesitas cambiar.

El objeto de sesión devuelto por el método open_session() tiene que proporcionar una interfaz similar a la de un diccionario, además de las propiedades y métodos de la SessionMixin. Recomendamos simplemente subclasificar un diccionario y añadir ese mixin:

class Session(dict, SessionMixin):
    pass

Si open_session() devuelve None Flask llamará a make_null_session() para crear una sesión que actúe como reemplazo si el soporte de sesión no puede funcionar porque no se cumple algún requisito. La clase NullSession por defecto que se crea se quejará de que no se ha establecido la clave secreta.

Para reemplazar la interfaz de sesión en una aplicación todo lo que tienes que hacer es asignar flask.Flask.session_interface:

app = Flask(__name__)
app.session_interface = MySessionInterface()

Se pueden enviar y gestionar simultáneamente varias solicitudes con la misma sesión. Al implementar una nueva interfaz de sesión, hay que tener en cuenta si las lecturas o escrituras en el almacén de respaldo deben estar sincronizadas. No se garantiza el orden en el que se abre o guarda la sesión para cada solicitud, se producirá en el orden en el que las solicitudes comienzan y terminan de procesarse.

Changelog

Nuevo en la versión 0.8.

null_session_class

make_null_session() buscará aquí la clase que debe crearse cuando se solicita una sesión nula. Del mismo modo, el método is_null_session() realizará una comprobación de tipo con respecto a esta clase.

alias de NullSession

pickle_based = False

Una bandera que indica si la interfaz de sesión está basada en pickle. Esto puede ser utilizado por las extensiones de Flask para tomar una decisión con respecto a cómo tratar el objeto de sesión.

Changelog

Nuevo en la versión 0.10.

make_null_session(app)

Crea una sesión nula que actúa como objeto de reemplazo si el soporte de la sesión real no pudo ser cargado debido a un error de configuración. Esto ayuda principalmente a la experiencia del usuario porque el trabajo de la sesión nula es seguir soportando la búsqueda sin quejarse, pero las modificaciones se responden con un mensaje de error útil de lo que falló.

Esto crea una instancia de null_session_class por defecto.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

NullSession

is_null_session(obj)

Comprueba si un objeto dado es una sesión nula. No se pide que se guarden las sesiones nulas.

Comprueba si el objeto es una instancia de null_session_class por defecto.

Parámetros:

obj (object) –

Tipo del valor devuelto:

bool

The name of the session cookie. Uses``app.config[«SESSION_COOKIE_NAME»]``.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

str

The value of the Domain parameter on the session cookie. If not set, browsers will only send the cookie to the exact domain it was set from. Otherwise, they will send it to any subdomain of the given value as well.

Uses the SESSION_COOKIE_DOMAIN config.

Changelog

Distinto en la versión 2.3: Not set by default, does not fall back to SERVER_NAME.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

str | None

Devuelve la ruta para la que la cookie debe ser válida. La implementación por defecto utiliza el valor de la var de configuración SESSION_COOKIE_PATH si está establecida, y vuelve a APPLICATION_ROOT o utiliza / si es None.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

str

Devuelve True si la cookie de sesión debe ser httponly. Actualmente sólo devuelve el valor de la varilla de configuración SESSION_COOKIE_HTTPONLY.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

bool

Devuelve True si la cookie debe ser segura. Actualmente sólo devuelve el valor del ajuste SESSION_COOKIE_SECURE.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

bool

Devuelve 'Strict' o 'Lax' si la cookie debe utilizar el atributo SameSite. Actualmente sólo devuelve el valor del ajuste SESSION_COOKIE_SAMESITE.

Parámetros:

app (Flask) –

Tipo del valor devuelto:

str | None

get_expiration_time(app, session)

Un método de ayuda que devuelve una fecha de caducidad para la sesión o None si la sesión está vinculada a la sesión del navegador. La implementación por defecto devuelve now + el tiempo de vida de la sesión permanente configurada en la aplicación.

Parámetros:
Tipo del valor devuelto:

datetime | None

Utilizado por los backends de sesión para determinar si se debe establecer una cabecera Set-Cookie para esta cookie de sesión para esta respuesta. Si la sesión ha sido modificada, se establece la cookie. Si la sesión es permanente y la configuración SESSION_REFRESH_EACH_REQUEST es verdadera, la cookie se establece siempre.

Esta comprobación suele omitirse si la sesión se ha eliminado.

Changelog

Nuevo en la versión 0.11.

Parámetros:
Tipo del valor devuelto:

bool

open_session(app, request)

Se llama al principio de cada solicitud, después de empujar el contexto de la solicitud, antes de hacer coincidir la URL.

Debe devolver un objeto que implemente una interfaz tipo diccionario, así como la interfaz SessionMixin.

Esto devolverá None para indicar que la carga falló de alguna manera que no es inmediatamente un error. El contexto de la solicitud volverá a utilizar make_null_session() en este caso.

Parámetros:

  • app (Flask) –

  • request (Request) –

Tipo del valor devuelto:

SessionMixin | None

save_session(app, session, response)

Se llama al final de cada solicitud, después de generar una respuesta, antes de eliminar el contexto de la solicitud. Se omite si is_null_session() devuelve True.

Parámetros:

  • app (Flask) –

  • session (SessionMixin) –

  • response (Response) –

Tipo del valor devuelto:

None

class flask.sessions.SecureCookieSessionInterface

La interfaz de sesión por defecto que almacena las sesiones en cookies firmadas a través del módulo itsdangerous.

salt = 'cookie-session'

la sal que debe aplicarse sobre la clave secreta para la firma de las sesiones basadas en cookies.

static digest_method(string=b'')

la función hash a utilizar para la firma. El valor por defecto es sha1

Parámetros:

string (bytes) –

Tipo del valor devuelto:

Any

key_derivation = 'hmac'

el nombre de la derivación de clave soportada por itsdangerous. El valor por defecto es hmac.

serializer = <flask.json.tag.TaggedJSONSerializer object>

Un serializador de Python para la carga útil. El valor por defecto es un serializador compacto derivado de JSON con soporte para algunos tipos extra de Python como objetos datetime o tuplas.

session_class

alias de SecureCookieSession

open_session(app, request)

Se llama al principio de cada solicitud, después de empujar el contexto de la solicitud, antes de hacer coincidir la URL.

Debe devolver un objeto que implemente una interfaz tipo diccionario, así como la interfaz SessionMixin.

Esto devolverá None para indicar que la carga falló de alguna manera que no es inmediatamente un error. El contexto de la solicitud volverá a utilizar make_null_session() en este caso.

Parámetros:

  • app (Flask) –

  • request (Request) –

Tipo del valor devuelto:

SecureCookieSession | None

save_session(app, session, response)

Se llama al final de cada solicitud, después de generar una respuesta, antes de eliminar el contexto de la solicitud. Se omite si is_null_session() devuelve True.

Parámetros:

  • app (Flask) –

  • session (SessionMixin) –

  • response (Response) –

Tipo del valor devuelto:

None

class flask.sessions.SecureCookieSession(initial=None)

Clase base para sesiones basadas en cookies firmadas.

Este backend de sesión establecerá los atributos modified y accessed. No se puede saber de forma fiable si una sesión es nueva (frente a una vacía), por lo que new permanece codificado en False.

Parámetros:

initial (t.Any) –

modified = False

Cuando se modifican los datos, esto se establece como True. Sólo se rastrea el diccionario de sesión en sí mismo; si la sesión contiene datos mutables (por ejemplo, un dict anidado) entonces esto debe ser establecido a True manualmente cuando se modifican esos datos. La cookie de sesión sólo se escribirá en la respuesta si es True.

accessed = False

que permite a los proxies de caché almacenar en caché diferentes páginas para diferentes usuarios.

get(key, default=None)

Devuelve el valor de la clave si la clave está en el diccionario, si no, por defecto.

Parámetros:

  • key (str) –

  • default (Any) –

Tipo del valor devuelto:

Any

setdefault(key, default=None)

Inserta la clave con un valor por defecto si la clave no está en el diccionario.

Devuelve el valor de la clave si la clave está en el diccionario, si no, por defecto.

Parámetros:

  • key (str) –

  • default (Any) –

Tipo del valor devuelto:

Any

class flask.sessions.NullSession(initial=None)

Clase utilizada para generar mensajes de error más agradables si las sesiones no están disponibles. Seguirá permitiendo el acceso de sólo lectura a la sesión vacía, pero fallará al establecerla.

Parámetros:

initial (t.Any) –

clear() → None.  Remove all items from D.
Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

NoReturn

pop(k[, d]) → v, remove specified key and return the corresponding value.

If the key is not found, return the default if given; otherwise, raise a KeyError.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

NoReturn

popitem(*args, **kwargs)

Elimina y devuelve un par (clave, valor) como una 2-tupla.

Los pares se devuelven en orden LIFO (last-in, first-out). Se produce un KeyError si el dict está vacío.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

NoReturn

update([E, ]**F) → None.  Update D from dict/iterable E and F.

Si E está presente y tiene un método .keys(), entonces hace: for k en E: D[k] = E[k] Si E está presente y carece de un método .keys(), entonces hace: for k, v en E: D[k] = v En cualquier caso, esto es seguido por: for k en F: D[k] = F[k]

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

NoReturn

setdefault(*args, **kwargs)

Inserta la clave con un valor por defecto si la clave no está en el diccionario.

Devuelve el valor de la clave si la clave está en el diccionario, si no, por defecto.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

NoReturn

class flask.sessions.SessionMixin

Amplía un diccionario básico con atributos de sesión.

property permanent: bool

Esto refleja la clave «_permanente» en el dict.

modified = True

Algunas implementaciones pueden detectar cambios en la sesión y establecer esto cuando sucede. El mixin por defecto está codificado en True.

accessed = True

Algunas implementaciones pueden detectar cuando se leen o escriben datos de la sesión y establecer esto cuando sucede. El mixin por defecto está codificado en True.

Aviso

The PERMANENT_SESSION_LIFETIME config can be an integer or timedelta. The permanent_session_lifetime attribute is always a timedelta.

Test Client

Test CLI Runner

Globales de aplicación

To share data that is valid for one request only from one function to another, a global variable is not good enough because it would break in threaded environments. Flask provides you with a special object that ensures it is only valid for the active request and that will return different values for each request. In a nutshell: it does the right thing, like it does for request and session.

flask.g

Un objeto de espacio de nombres que puede almacenar datos durante un contexto de aplicación. Es una instancia de Flask.app_ctx_globals_class, que por defecto es ctx._AppCtxGlobals.

Este es un buen lugar para almacenar recursos durante una petición. Por ejemplo, una función before_request podría cargar un objeto de usuario a partir de un id de sesión, y luego establecer g.user para ser utilizado en la función de vista.

Se trata de un proxy. Consulte Notas sobre los apoderados para obtener más información.

Changelog

Distinto en la versión 0.10: Vinculado al contexto de la aplicación en lugar del contexto de la solicitud.

class flask.ctx._AppCtxGlobals

Un objeto simple. Se utiliza como espacio de nombres para almacenar datos durante un contexto de aplicación.

La creación de un contexto de aplicación crea automáticamente este objeto, que se pone a disposición como proxy g.

'key' in g

Comprueba si un atributo está presente.

Changelog

Nuevo en la versión 0.10.

iter(g)

Devuelve un iterador sobre los nombres de atributos.

Changelog

Nuevo en la versión 0.10.

get(name, default=None)

Obtener un atributo por su nombre, o un valor por defecto. Como dict.get().

Parámetros:

  • name (str) – Nombre del atributo a obtener.

  • default (Any | None) – Valor a devolver si el atributo no está presente.

Tipo del valor devuelto:

Any

Changelog

Nuevo en la versión 0.10.

pop(name, default=_sentinel)

Obtener y eliminar un atributo por su nombre. Como dict.pop().

Parámetros:

  • name (str) – Nombre del atributo a reventar.

  • default (Any) – Valor a devolver si el atributo no está presente, en lugar de lanzar un KeyError.

Tipo del valor devuelto:

Any

Changelog

Nuevo en la versión 0.11.

setdefault(name, default=None)

Obtiene el valor de un atributo si está presente, en caso contrario establece y devuelve un valor por defecto. Como dict.setdefault().

Parámetros:

  • name (str) – Nombre del atributo a obtener.

  • default (Any) – Valor a establecer y devolver si el atributo no está presente.

Tipo del valor devuelto:

Any

Changelog

Nuevo en la versión 0.11.

Funciones y clases útiles

flask.current_app

Un proxy de la aplicación que gestiona la solicitud actual. Esto es útil para acceder a la aplicación sin necesidad de importarla, o si no se puede importar, como cuando se utiliza el patrón de fábrica de aplicaciones o en blueprints y extensiones.

Esto sólo está disponible cuando un contexto de aplicación es empujado. Esto ocurre automáticamente durante las solicitudes y los comandos CLI. Se puede controlar manualmente con app_context().

Se trata de un proxy. Consulte Notas sobre los apoderados para obtener más información.

Mensaje intermitente

Soporte JSON

Flask uses Python’s built-in json module for handling JSON by default. The JSON implementation can be changed by assigning a different provider to flask.Flask.json_provider_class or flask.Flask.json. The functions provided by flask.json will use methods on app.json if an app context is active.

Jinja’s |tojson filter is configured to use the app’s JSON provider. The filter marks the output with |safe. Use it to render data inside HTML <script> tags.

<script>
    const names = {{ names|tojson }};
    renderChart(names, {{ axis_data|tojson }});
</script>
flask.json.jsonify(*args, **kwargs)

Serialize the given arguments as JSON, and return a Response object with the application/json mimetype. A dict or list returned from a view will be converted to a JSON response automatically without needing to call this.

This requires an active request or application context, and calls app.json.response().

In debug mode, the output is formatted with indentation to make it easier to read. This may also be controlled by the provider.

Either positional or keyword arguments can be given, not both. If no arguments are given, None is serialized.

Parámetros:

  • args (t.Any) – A single value to serialize, or multiple values to treat as a list to serialize.

  • kwargs (t.Any) – Treat as a dict to serialize.

Tipo del valor devuelto:

Response

Changelog

Distinto en la versión 2.2: Calls current_app.json.response, allowing an app to override the behavior.

Distinto en la versión 2.0.2: decimal.Decimal es compatible con la conversión a una cadena.

Distinto en la versión 0.11: Added support for serializing top-level arrays. This was a security risk in ancient browsers. See JSON Security.

Nuevo en la versión 0.2.

flask.json.dumps(obj, **kwargs)

Serialize data as JSON.

If current_app is available, it will use its app.json.dumps() method, otherwise it will use json.dumps().

Parámetros:

  • obj (Any) – The data to serialize.

  • kwargs (Any) – Arguments passed to the dumps implementation.

Tipo del valor devuelto:

str

Changelog

Distinto en la versión 2.3: The app parameter was removed.

Distinto en la versión 2.2: Calls current_app.json.dumps, allowing an app to override the behavior.

Distinto en la versión 2.0.2: decimal.Decimal es compatible con la conversión a una cadena.

Distinto en la versión 2.0: encoding will be removed in Flask 2.1.

Distinto en la versión 1.0.3: app se puede pasar directamente, en lugar de requerir un contexto de aplicación para la configuración.

flask.json.dump(obj, fp, **kwargs)

Serialize data as JSON and write to a file.

If current_app is available, it will use its app.json.dump() method, otherwise it will use json.dump().

Parámetros:

  • obj (Any) – The data to serialize.

  • fp (IO[str]) – A file opened for writing text. Should use the UTF-8 encoding to be valid JSON.

  • kwargs (Any) – Arguments passed to the dump implementation.

Tipo del valor devuelto:

None

Changelog

Distinto en la versión 2.3: The app parameter was removed.

Distinto en la versión 2.2: Calls current_app.json.dump, allowing an app to override the behavior.

Distinto en la versión 2.0: Writing to a binary file, and the encoding argument, will be removed in Flask 2.1.

flask.json.loads(s, **kwargs)

Deserialize data as JSON.

If current_app is available, it will use its app.json.loads() method, otherwise it will use json.loads().

Parámetros:

  • s (str | bytes) – Text or UTF-8 bytes.

  • kwargs (Any) – Arguments passed to the loads implementation.

Tipo del valor devuelto:

Any

Changelog

Distinto en la versión 2.3: The app parameter was removed.

Distinto en la versión 2.2: Calls current_app.json.loads, allowing an app to override the behavior.

Distinto en la versión 2.0: encoding will be removed in Flask 2.1. The data must be a string or UTF-8 bytes.

Distinto en la versión 1.0.3: app se puede pasar directamente, en lugar de requerir un contexto de aplicación para la configuración.

flask.json.load(fp, **kwargs)

Deserialize data as JSON read from a file.

If current_app is available, it will use its app.json.load() method, otherwise it will use json.load().

Parámetros:

  • fp (IO) – A file opened for reading text or UTF-8 bytes.

  • kwargs (Any) – Arguments passed to the load implementation.

Tipo del valor devuelto:

Any

Changelog

Distinto en la versión 2.3: The app parameter was removed.

Distinto en la versión 2.2: Calls current_app.json.load, allowing an app to override the behavior.

Distinto en la versión 2.2: The app parameter will be removed in Flask 2.3.

Distinto en la versión 2.0: encoding will be removed in Flask 2.1. The file must be text mode, or binary mode with UTF-8 bytes.

class flask.json.provider.JSONProvider(app)

A standard set of JSON operations for an application. Subclasses of this can be used to customize JSON behavior or use different JSON libraries.

To implement a provider for a specific library, subclass this base class and implement at least dumps() and loads(). All other methods have default implementations.

To use a different provider, either subclass Flask and set json_provider_class to a provider class, or set app.json to an instance of the class.

Parámetros:

app (App) – An application instance. This will be stored as a weakref.proxy on the _app attribute.

Changelog

Nuevo en la versión 2.2.

dumps(obj, **kwargs)

Serialize data as JSON.

Parámetros:

  • obj (Any) – The data to serialize.

  • kwargs (Any) – May be passed to the underlying JSON library.

Tipo del valor devuelto:

str

dump(obj, fp, **kwargs)

Serialize data as JSON and write to a file.

Parámetros:

  • obj (Any) – The data to serialize.

  • fp (IO[str]) – A file opened for writing text. Should use the UTF-8 encoding to be valid JSON.

  • kwargs (Any) – May be passed to the underlying JSON library.

Tipo del valor devuelto:

None

loads(s, **kwargs)

Deserialize data as JSON.

Parámetros:

  • s (str | bytes) – Text or UTF-8 bytes.

  • kwargs (Any) – May be passed to the underlying JSON library.

Tipo del valor devuelto:

Any

load(fp, **kwargs)

Deserialize data as JSON read from a file.

Parámetros:

  • fp (IO) – A file opened for reading text or UTF-8 bytes.

  • kwargs (Any) – May be passed to the underlying JSON library.

Tipo del valor devuelto:

Any

response(*args, **kwargs)

Serialize the given arguments as JSON, and return a Response object with the application/json mimetype.

The jsonify() function calls this method for the current application.

Either positional or keyword arguments can be given, not both. If no arguments are given, None is serialized.

Parámetros:

  • args (t.Any) – A single value to serialize, or multiple values to treat as a list to serialize.

  • kwargs (t.Any) – Treat as a dict to serialize.

Tipo del valor devuelto:

Response

class flask.json.provider.DefaultJSONProvider(app)

Provide JSON operations using Python’s built-in json library. Serializes the following additional data types:

Parámetros:

app (App) –

static default(o)

Apply this function to any object that json.dumps() does not know how to serialize. It should return a valid JSON type or raise a TypeError.

Parámetros:

o (Any) –

Tipo del valor devuelto:

Any

ensure_ascii = True

Replace non-ASCII characters with escape sequences. This may be more compatible with some clients, but can be disabled for better performance and size.

sort_keys = True

Sort the keys in any serialized dicts. This may be useful for some caching situations, but can be disabled for better performance. When enabled, keys must all be strings, they are not converted before sorting.

compact: bool | None = None

If True, or None out of debug mode, the response() output will not add indentation, newlines, or spaces. If False, or None in debug mode, it will use a non-compact representation.

mimetype = 'application/json'

The mimetype set in response().

dumps(obj, **kwargs)

Serialize data as JSON to a string.

Keyword arguments are passed to json.dumps(). Sets some parameter defaults from the default, ensure_ascii, and sort_keys attributes.

Parámetros:
Tipo del valor devuelto:

str

loads(s, **kwargs)

Deserialize data as JSON from a string or bytes.

Parámetros:
Tipo del valor devuelto:

Any

response(*args, **kwargs)

Serialize the given arguments as JSON, and return a Response object with it. The response mimetype will be «application/json» and can be changed with mimetype.

If compact is False or debug mode is enabled, the output will be formatted to be easier to read.

Either positional or keyword arguments can be given, not both. If no arguments are given, None is serialized.

Parámetros:

  • args (t.Any) – A single value to serialize, or multiple values to treat as a list to serialize.

  • kwargs (t.Any) – Treat as a dict to serialize.

Tipo del valor devuelto:

Response

Etiquetado JSON

Una representación compacta para la serialización sin pérdidas de tipos JSON no estándar. SecureCookieSessionInterface utiliza esto para serializar los datos de sesión, pero puede ser útil en otros lugares. Puede ser extendido para soportar otros tipos.

class flask.json.tag.TaggedJSONSerializer

Serializador que utiliza un sistema de etiquetas para representar de forma compacta objetos no JSON. Se pasa como un serializador intermedio a itsdangerous.Serializer.

Se admiten los siguientes tipos adicionales:

default_tags = [<class 'flask.json.tag.TagDict'>, <class 'flask.json.tag.PassDict'>, <class 'flask.json.tag.TagTuple'>, <class 'flask.json.tag.PassList'>, <class 'flask.json.tag.TagBytes'>, <class 'flask.json.tag.TagMarkup'>, <class 'flask.json.tag.TagUUID'>, <class 'flask.json.tag.TagDateTime'>]

Clases de etiquetas a enlazar cuando se crea el serializador. Se pueden añadir otras etiquetas más tarde usando register().

register(tag_class, force=False, index=None)

Registra una nueva etiqueta con este serializador.

Parámetros:

  • tag_class (type[JSONTag]) – clase de etiqueta a registrar. Se instanciará con esta instancia del serializador.

  • force (bool) – sobrescribir una etiqueta existente. Si es falso (por defecto), se produce un KeyError.

  • index (int | None) – para insertar la nueva etiqueta en el orden de las etiquetas. Es útil cuando la nueva etiqueta es un caso especial de una etiqueta existente. Si es None (por defecto), la etiqueta se añade al final del orden.

Muestra:

KeyError – si la clave de la etiqueta ya está registrada y force no es verdadero.

Tipo del valor devuelto:

None

tag(value)

Convierte un valor en una representación etiquetada si es necesario.

Parámetros:

value (Any) –

Tipo del valor devuelto:

Any

untag(value)

Convierte una representación etiquetada en el tipo original.

Parámetros:

value (dict[str, Any]) –

Tipo del valor devuelto:

Any

dumps(value)

Etiqueta el valor y lo vuelca en una cadena JSON compacta.

Parámetros:

value (Any) –

Tipo del valor devuelto:

str

loads(value)

Cargar datos de una cadena JSON y deserializar cualquier objeto etiquetado.

Parámetros:

value (str) –

Tipo del valor devuelto:

Any

class flask.json.tag.JSONTag(serializer)

Clase base para definir etiquetas de tipo para TaggedJSONSerializer.

Parámetros:

serializer (TaggedJSONSerializer) –

key: str = ''

The tag to mark the serialized object with. If empty, this tag is only used as an intermediate step during tagging.

check(value)

Comprueba si el valor dado debe ser etiquetado por esta etiqueta.

Parámetros:

value (Any) –

Tipo del valor devuelto:

bool

to_json(value)

Convierte el objeto Python en un objeto de tipo JSON válido. La etiqueta se añadirá más tarde.

Parámetros:

value (Any) –

Tipo del valor devuelto:

Any

to_python(value)

Convierte la representación JSON al tipo correcto. La etiqueta ya estará eliminada.

Parámetros:

value (Any) –

Tipo del valor devuelto:

Any

tag(value)

Convierte el valor a un tipo JSON válido y añade la estructura de etiquetas a su alrededor.

Parámetros:

value (Any) –

Tipo del valor devuelto:

dict[str, Any]

Veamos un ejemplo que añade soporte para OrderedDict. Los dicts no tienen un orden en JSON, así que para manejar esto volcaremos los elementos como una lista de pares [key, value]. Subclase JSONTag y dale la nueva clave ' od' para identificar el tipo. El serializador de sesión procesa primero los dicts, así que inserta la nueva etiqueta al principio de la orden ya que OrderedDict debe ser procesado antes que dict.

from flask.json.tag import JSONTag

class TagOrderedDict(JSONTag):
    __slots__ = ('serializer',)
    key = ' od'

    def check(self, value):
        return isinstance(value, OrderedDict)

    def to_json(self, value):
        return [[k, self.serializer.tag(v)] for k, v in iteritems(value)]

    def to_python(self, value):
        return OrderedDict(value)

app.session_interface.serializer.register(TagOrderedDict, index=0)

Renderizado de plantillas

Configuración

Ayudas para streams

Internos útiles

class flask.ctx.RequestContext(app, environ, request=None, session=None)

El contexto de solicitud contiene información por solicitud. La aplicación Flask lo crea y empuja al principio de la petición, y luego lo saca al final de la misma. Creará el adaptador de URL y el objeto de solicitud para el entorno WSGI proporcionado.

No intente utilizar esta clase directamente, en su lugar utilice test_request_context() y request_context() para crear este objeto.

Cuando el contexto de la petición se abre, evaluará todas las funciones registradas en la aplicación para la ejecución de teardown (teardown_request()).

El contexto de la petición es automáticamente extraído al final de la petición. Cuando se utiliza el depurador interactivo, el contexto será restaurado para que request siga siendo accesible. Del mismo modo, el cliente de prueba puede preservar el contexto después de que la solicitud termine. Sin embargo, las funciones de desmontaje pueden haber cerrado ya algunos recursos, como las conexiones a la base de datos.

Parámetros:

  • app (Flask) –

  • environ (WSGIEnvironment) –

  • request (Request | None) –

  • session (SessionMixin | None) –

copy()

Crea una copia de este contexto de solicitud con el mismo objeto de solicitud. Esto puede ser usado para mover un contexto de petición a un greenlet diferente. Debido a que el objeto de solicitud real es el mismo, esto no se puede utilizar para mover un contexto de solicitud a un hilo diferente a menos que el acceso al objeto de solicitud esté bloqueado.

Changelog

Distinto en la versión 1.1: Se utiliza el objeto de sesión actual en lugar de recargar los datos originales. Esto evita que flask.session apunte a un objeto desactualizado.

Nuevo en la versión 0.10.

Tipo del valor devuelto:

RequestContext

match_request()

Puede ser sobrescrito por una subclase para engancharse a la coincidencia de la solicitud.

Tipo del valor devuelto:

None

pop(exc=_sentinel)

Despliega el contexto de la solicitud y lo desvincula al hacerlo. Esto también desencadenará la ejecución de las funciones registradas por el decorador teardown_request().

Changelog

Distinto en la versión 0.9: Se ha añadido el argumento exc.

Parámetros:

exc (BaseException | None) –

Tipo del valor devuelto:

None

flask.globals.request_ctx

La RequestContext actual. Si un contexto de solicitud no está activo, el acceso a los atributos de este proxy generará un RuntimeError.

Este es un objeto interno que es esencial para la forma en que Flask maneja las solicitudes. En la mayoría de los casos no debería ser necesario acceder a él. Lo más probable es que quieras request y session en su lugar.

class flask.ctx.AppContext(app)

El contexto de la aplicación contiene información específica de la aplicación. Se crea un contexto de aplicación y se envía al principio de cada solicitud si no hay uno activo. También se envía un contexto de aplicación cuando se ejecutan comandos CLI.

Parámetros:

app (Flask) –

push()

Vincula el contexto de la aplicación al contexto actual.

Tipo del valor devuelto:

None

pop(exc=_sentinel)

Muestra el contexto de la aplicación.

Parámetros:

exc (BaseException | None) –

Tipo del valor devuelto:

None

flask.globals.app_ctx

La actual AppContext. Si un contexto de aplicación no está activo, el acceso a los atributos de este proxy generará un RuntimeError.

Este es un objeto interno que es esencial para la forma en que Flask maneja las solicitudes. En la mayoría de los casos no debería ser necesario acceder a él. Lo más probable es que quieras current_app y g en su lugar.

Señales

Signals are provided by the Blinker library. See Señales for an introduction.

flask.template_rendered

This signal is sent when a template was successfully rendered. The signal is invoked with the instance of the template as template and the context as dictionary (named context).

Ejemplo de suscriptor:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import template_rendered
template_rendered.connect(log_template_renders, app)
flask.before_render_template

Esta señal se envía antes del proceso de renderización de la plantilla. La señal se invoca con la instancia de la plantilla como template y el contexto como diccionario (llamado context).

Ejemplo de suscriptor:

def log_template_renders(sender, template, context, **extra):
    sender.logger.debug('Rendering template "%s" with context %s',
                        template.name or 'string template',
                        context)

from flask import before_render_template
before_render_template.connect(log_template_renders, app)
flask.request_started

This signal is sent when the request context is set up, before any request processing happens. Because the request context is already bound, the subscriber can access the request with the standard global proxies such as request.

Ejemplo de suscriptor:

def log_request(sender, **extra):
    sender.logger.debug('Request context is set up')

from flask import request_started
request_started.connect(log_request, app)
flask.request_finished

Esta señal se envía justo antes de que se envíe la respuesta al cliente. Se le pasa la respuesta a enviar llamada response.

Ejemplo de suscriptor:

def log_response(sender, response, **extra):
    sender.logger.debug('Request context is about to close down. '
                        'Response: %s', response)

from flask import request_finished
request_finished.connect(log_response, app)
flask.got_request_exception

Esta señal se envía cuando se produce una excepción no controlada durante el procesamiento de la solicitud, incluso durante la depuración. La excepción se pasa al suscriptor como excepción.

Esta señal no se envía para HTTPException, u otras excepciones que tengan manejadores de error registrados, a menos que la excepción haya sido lanzada desde un manejador de errores.

Este ejemplo muestra cómo hacer un registro extra si una teórica SecurityException fue levantada:

from flask import got_request_exception

def log_security_exception(sender, exception, **extra):
    if not isinstance(exception, SecurityException):
        return

    security_logger.exception(
        f"SecurityException at {request.url!r}",
        exc_info=exception,
    )

got_request_exception.connect(log_security_exception, app)
flask.request_tearing_down

This signal is sent when the request is tearing down. This is always called, even if an exception is caused. Currently functions listening to this signal are called after the regular teardown handlers, but this is not something you can rely on.

Ejemplo de suscriptor:

def close_db_connection(sender, **extra):
    session.close()

from flask import request_tearing_down
request_tearing_down.connect(close_db_connection, app)

A partir de Flask 0.9, también se le pasará un argumento de la palabra clave exc que tiene una referencia a la excepción que causó el teardown si es que hubo una.

flask.appcontext_tearing_down

This signal is sent when the app context is tearing down. This is always called, even if an exception is caused. Currently functions listening to this signal are called after the regular teardown handlers, but this is not something you can rely on.

Ejemplo de suscriptor:

def close_db_connection(sender, **extra):
    session.close()

from flask import appcontext_tearing_down
appcontext_tearing_down.connect(close_db_connection, app)

También se le pasará un argumento de la palabra clave exc que tiene una referencia a la excepción que causó el derribo si es que la hubo.

flask.appcontext_pushed

This signal is sent when an application context is pushed. The sender is the application. This is usually useful for unittests in order to temporarily hook in information. For instance it can be used to set a resource early onto the g object.

Ejemplo de uso:

from contextlib import contextmanager
from flask import appcontext_pushed

@contextmanager
def user_set(app, user):
    def handler(sender, **kwargs):
        g.user = user
    with appcontext_pushed.connected_to(handler, app):
        yield

Y en el testcode:

def test_user_me(self):
    with user_set(app, 'john'):
        c = app.test_client()
        resp = c.get('/users/me')
        assert resp.data == 'username=john'
Changelog

Nuevo en la versión 0.10.

flask.appcontext_popped

This signal is sent when an application context is popped. The sender is the application. This usually falls in line with the appcontext_tearing_down signal.

Changelog

Nuevo en la versión 0.10.

flask.message_flashed

This signal is sent when the application is flashing a message. The messages is sent as message keyword argument and the category as category.

Ejemplo de suscriptor:

recorded = []
def record(sender, message, category, **extra):
    recorded.append((message, category))

from flask import message_flashed
message_flashed.connect(record, app)
Changelog

Nuevo en la versión 0.10.

Vistas basadas en clases

Changelog

Nuevo en la versión 0.7.

Registros de rutas URL

En general, hay tres maneras de definir las reglas del sistema de enrutamiento:

  1. Puede utilizar el decorador flask.Flask.route().

  2. Puedes utilizar la función flask.Flask.add_url_rule().

  3. Puedes acceder directamente al sistema de enrutamiento subyacente de Werkzeug que se expone como flask.Flask.url_map.

Variable parts in the route can be specified with angular brackets (/user/<username>). By default a variable part in the URL accepts any string without a slash however a different converter can be specified as well by using <converter:name>.

Las partes variables se pasan a la función de la vista como argumentos de palabra clave.

Están disponibles los siguientes convertidores:

string

acepta cualquier texto sin barra (por defecto)

int

acepta números enteros

float

como int pero para valores de punto flotante

path

como el predeterminado, pero también acepta barras inclinadas

any

coincide con uno de los elementos previstos

uuid

acepta cadenas UUID

Los convertidores personalizados pueden ser definidos usando flask.Flask.url_map.

He aquí algunos ejemplos:

@app.route('/')
def index():
    pass

@app.route('/<username>')
def show_user(username):
    pass

@app.route('/post/<int:post_id>')
def show_post(post_id):
    pass

An important detail to keep in mind is how Flask deals with trailing slashes. The idea is to keep each URL unique so the following rules apply:

  1. Si una regla termina con una barra y es solicitada sin barra por el usuario, éste es redirigido automáticamente a la misma página con una barra al final.

  2. Si una regla no termina con una barra final y el usuario solicita la página con una barra final, se genera un 404 no encontrado.

This is consistent with how web servers deal with static files. This also makes it possible to use relative link targets safely.

You can also define multiple rules for the same function. They have to be unique however. Defaults can also be specified. Here for example is a definition for a URL that accepts an optional page:

@app.route('/users/', defaults={'page': 1})
@app.route('/users/page/<int:page>')
def show_users(page):
    pass

Esto especifica que /users/ será la URL de la página uno y /users/page/N será la URL de la página N.

Si una URL contiene un valor por defecto, será redirigida a su forma más simple con una redirección 301. En el ejemplo anterior, /users/page/1 será redirigida a /users/. Si tu ruta maneja solicitudes GET y POST, asegúrate de que la ruta por defecto sólo maneja GET, ya que las redirecciones no pueden conservar los datos del formulario.

@app.route('/region/', defaults={'id': 1})
@app.route('/region/<int:id>', methods=['GET', 'POST'])
def region(id):
   pass

Here are the parameters that route() and add_url_rule() accept. The only difference is that with the route parameter the view function is defined with the decorator instead of the view_func parameter.

rule

la regla URL como cadena

endpoint

the endpoint for the registered URL rule. Flask itself assumes that the name of the view function is the name of the endpoint if not explicitly stated.

view_func

the function to call when serving a request to the provided endpoint. If this is not provided one can specify the function later by storing it in the view_functions dictionary with the endpoint as key.

defaults

A dictionary with defaults for this rule. See the example above for how defaults work.

subdomain

specifies the rule for the subdomain in case subdomain matching is in use. If not specified the default subdomain is assumed.

**options

the options to be forwarded to the underlying Rule object. A change to Werkzeug is handling of method options. methods is a list of methods this rule should be limited to (GET, POST etc.). By default a rule just listens for GET (and implicitly HEAD). Starting with Flask 0.6, OPTIONS is implicitly added and handled by the standard request handling. They have to be specified as keyword arguments.

Ver opciones de funciones

Para uso interno las funciones de vista pueden tener algunos atributos adjuntos para personalizar el comportamiento sobre el que la función de vista normalmente no tendría control. Los siguientes atributos se pueden proporcionar opcionalmente para anular algunos valores predeterminados de add_url_rule() o el comportamiento general:

  • __name__: The name of a function is by default used as endpoint. If endpoint is provided explicitly this value is used. Additionally this will be prefixed with the name of the blueprint by default which cannot be customized from the function itself.

  • methods: If methods are not provided when the URL rule is added, Flask will look on the view function object itself if a methods attribute exists. If it does, it will pull the information for the methods from there.

  • provide_automatic_options: if this attribute is set Flask will either force enable or disable the automatic implementation of the HTTP OPTIONS response. This can be useful when working with decorators that want to customize the OPTIONS response on a per-view basis.

  • required_methods: Si se establece este atributo, Flask siempre añadirá estos métodos al registrar una regla de URL, incluso si los métodos fueron explícitamente anulados en la llamada a route().

Ejemplo completo:

def index():
    if request.method == 'OPTIONS':
        # custom options handling here
        ...
    return 'Hello World!'
index.provide_automatic_options = False
index.methods = ['GET', 'OPTIONS']

app.add_url_rule('/', index)
Changelog

Nuevo en la versión 0.8: Se ha añadido la funcionalidad provide_automatic_options.

Interfaz de línea de comandos

class flask.cli.FlaskGroup(add_default_commands=True, create_app=None, add_version_option=True, load_dotenv=True, set_debug_flag=True, **extra)

Subclase especial del grupo AppGroup que soporta la carga de más comandos de la aplicación Flask configurada. Normalmente un desarrollador no tiene que interactuar con esta clase pero hay algunos casos de uso muy avanzados para los que tiene sentido crear una instancia de esto. ver Scripts personalizados.

Parámetros:

  • add_default_commands (bool) – si es True, se añadirán los comandos de ejecución y shell por defecto.

  • add_version_option (bool) – añade la opción --versión.

  • create_app (t.Callable[..., Flask] | None) – un callback opcional al que se le pasa la información del script y devuelve la aplicación cargada.

  • load_dotenv (bool) – Carga los archivos .env y .flaskenv más cercanos para establecer las variables de entorno. También cambiará el directorio de trabajo al directorio que contenga el primer archivo encontrado.

  • set_debug_flag (bool) – Set the app’s debug flag.

  • extra (t.Any) –

Changelog

Distinto en la versión 2.2: Added the -A/--app, --debug/--no-debug, -e/--env-file options.

Distinto en la versión 2.2: Al ejecutar los comandos app.cli se envía un contexto de aplicación, por lo que @with_appcontext ya no es necesario para esos comandos.

Distinto en la versión 1.0: Si se instala, python-dotenv se utilizará para cargar las variables de entorno de los archivos .env y .flaskenv.

get_command(ctx, name)

Dado un contexto y un nombre de comando, devuelve un objeto Command si existe o devuelve None.

Parámetros:
Tipo del valor devuelto:

Command | None

list_commands(ctx)

Devuelve una lista de nombres de subcomandos en el orden en que deben aparecer.

Parámetros:

ctx (Context) –

Tipo del valor devuelto:

list[str]

make_context(info_name, args, parent=None, **extra)

Esta función, cuando se le da un nombre de información y argumentos, iniciará el análisis y creará un nuevo Context. Sin embargo, no invoca la llamada de retorno del comando real.

Para personalizar rápidamente la clase de contexto utilizada sin sobrescribir este método, establezca el atributo context_class.

Parámetros:

  • info_name (str | None) – the info name for this invocation. Generally this is the most descriptive name for the script or command. For the toplevel script it’s usually the name of the script, for commands below it’s the name of the command.

  • args (list[str]) – los argumentos a analizar como lista de cadenas.

  • parent (Context | None) – el contexto padre si está disponible.

  • extra (Any) – argumentos clave extras enviados al constructor del contexto.

Tipo del valor devuelto:

Context

Distinto en la versión 8.0: Se ha añadido el atributo context_class.

parse_args(ctx, args)

Dado un contexto y una lista de argumentos, crea el analizador y analiza los argumentos, luego modifica el contexto según sea necesario. Esto es invocado automáticamente por make_context().

Parámetros:
Tipo del valor devuelto:

list[str]

class flask.cli.AppGroup(name=None, commands=None, **attrs)

Esto funciona de forma similar a un clic normal Group pero cambia el comportamiento del decorador command() para que envuelva automáticamente las funciones en with_appcontext().

No debe confundirse con FlaskGroup.

Parámetros:
command(*args, **kwargs)

Esto funciona exactamente igual que el método del mismo nombre en un click.Group normal, pero envuelve las devoluciones de llamada en with_appcontext() a menos que se desactive pasando with_appcontext=False.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

Callable[[Callable[[…], Any]], Command]

group(*args, **kwargs)

Esto funciona exactamente igual que el método del mismo nombre en un click.Group normal, pero por defecto la clase del grupo es AppGroup.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

Callable[[Callable[[…], Any]], Group]

class flask.cli.ScriptInfo(app_import_path=None, create_app=None, set_debug_flag=True)

Objeto de ayuda para tratar con las aplicaciones de Flask. Normalmente no es necesario interactuar con él, ya que se utiliza internamente en el envío a click. En futuras versiones de Flask este objeto probablemente jugará un papel más importante. Normalmente es creado automáticamente por la clase FlaskGroup pero también se puede crear manualmente y pasarlo como objeto click.

Parámetros:

  • app_import_path (str | None) –

  • create_app (t.Callable[..., Flask] | None) –

  • set_debug_flag (bool) –

app_import_path

Opcionalmente la ruta de importación de la aplicación Flask.

create_app

Opcionalmente una función a la que se le pasa la información del script para crear la instancia de la aplicación.

data: dict[t.Any, t.Any]

Un diccionario con datos arbitrarios que se pueden asociar a esta información del script.

load_app()

Carga la aplicación Flask (si aún no está cargada) y la devuelve. Si se llama a esto varias veces, sólo se devolverá la aplicación ya cargada.

Tipo del valor devuelto:

Flask

flask.cli.load_dotenv(path=None)

Cargue los archivos «dotenv» en orden de precedencia para establecer las variables de entorno.

Si una var env ya está configurada, no se sobrescribe, por lo que se prefieren los archivos anteriores de la lista a los posteriores.

Esto es un no-op si python-dotenv no está instalado.

Parámetros:

path (str | PathLike[str] | None) – Cargue el archivo en esta ubicación en lugar de buscarlo.

Returns:

True si se ha cargado un archivo.

Tipo del valor devuelto:

bool

Changelog

Distinto en la versión 2.0: El directorio actual no se cambia a la ubicación del archivo cargado.

Distinto en la versión 2.0: Al cargar los archivos env, establezca la codificación por defecto en UTF-8.

Distinto en la versión 1.1.0: Devuelve False cuando python-dotenv no está instalado, o cuando la ruta dada no es un archivo.

Nuevo en la versión 1.0.

flask.cli.with_appcontext(f)

Envuelve una llamada de retorno para que se garantice su ejecución con el contexto de la aplicación del script.

Los comandos personalizados (y sus opciones) registrados en app.cli o blueprint.cli siempre tendrán un contexto de aplicación disponible, este decorador no es necesario en ese caso.

Changelog

Distinto en la versión 2.2: El contexto de la aplicación está activo para los subcomandos, así como para la devolución de llamada decorada. El contexto de la aplicación siempre está disponible para las devoluciones de llamada de comandos y parámetros de app.cli.

Parámetros:

f (F) –

Tipo del valor devuelto:

F

flask.cli.pass_script_info(f)

Marca una función para que se pase una instancia de ScriptInfo como primer argumento a la llamada de retorno del clic.

Parámetros:

f (t.Callable[te.Concatenate[T, P], R]) –

Tipo del valor devuelto:

t.Callable[P, R]

flask.cli.run_command = <Command run>

Ejecutar un servidor de desarrollo local.

Este servidor es sólo para fines de desarrollo. No proporciona la estabilidad, seguridad o rendimiento de los servidores WSGI de producción.

The reloader and debugger are enabled by default with the “–debug” option.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

Any

flask.cli.shell_command = <Command shell>

Ejecuta un shell interactivo de Python en el contexto de una aplicación Flask determinada. La aplicación rellenará el espacio de nombres por defecto de este shell según su configuración.

Esto es útil para ejecutar pequeños fragmentos de código de gestión sin tener que configurar manualmente la aplicación.

Parámetros:

  • args (Any) –

  • kwargs (Any) –

Tipo del valor devuelto:

Any