跳转至

Fields

File (Field)

A binary file field, it should only be used in an input schema.

Examples:

import os

from werkzeug.utils import secure_filename
from apiflask.fields import File


class ImageSchema(Schema):
    image = File()


@app.post('/images')
@app.input(ImageSchema, location='files')
def upload_image(data):
    f = data['image']
    # use `secure_filename` to clean the filename, notice it will only keep ascii characters
    filename = secure_filename(f.filename)
    f.save(os.path.join(the_path_to_uploads, filename))

    return {'message': f'file {filename} saved.'}
The file object is an instance of werkzeug.datastructures.FileStorage, see more details in the docs. # noqa: B950, E501

Use form_and_files location if you want to put both files and other normal fields in one schema.

import os

from werkzeug.utils import secure_filename
from apiflask.fields import String, File


class ProfileInSchema(Schema):
    name = String()
    avatar = File()

@app.post('/profiles')
@app.input(ProfileInSchema, location='form_and_files')
def create_profile(data):
    avatar_file = data['avatar']
    name = data['name']

    # use `secure_filename` to clean the filename, notice it will only keep ascii characters
    avatar_filename = secure_filename(avatar_file.filename)
    avatar_file.save(os.path.join(the_path_to_uploads, avatar_filename))

    profile = Profile(name=name, avatar_filename=avatar_filename)
    # ...
    return {'message': 'profile created.'}

In the current implementation, files location data will also include the form data (equals to form_and_files).

Version Added: 1.0

This field accepts the same keyword arguments that Field receives.

Source code in apiflask/fields.py
class File(Field):
    """A binary file field, it should only be used in an input schema.

    Examples:

    ```python
    import os

    from werkzeug.utils import secure_filename
    from apiflask.fields import File


    class ImageSchema(Schema):
        image = File()


    @app.post('/images')
    @app.input(ImageSchema, location='files')
    def upload_image(data):
        f = data['image']
        # use `secure_filename` to clean the filename, notice it will only keep ascii characters
        filename = secure_filename(f.filename)
        f.save(os.path.join(the_path_to_uploads, filename))

        return {'message': f'file {filename} saved.'}
    ```
    The file object is an instance of `werkzeug.datastructures.FileStorage`, see more details in the
    [docs](https://werkzeug.palletsprojects.com/datastructures/#werkzeug.datastructures.FileStorage).  # noqa: B950, E501

    Use `form_and_files` location if you want to put both files
    and other normal fields in one schema.

    ```python
    import os

    from werkzeug.utils import secure_filename
    from apiflask.fields import String, File


    class ProfileInSchema(Schema):
        name = String()
        avatar = File()

    @app.post('/profiles')
    @app.input(ProfileInSchema, location='form_and_files')
    def create_profile(data):
        avatar_file = data['avatar']
        name = data['name']

        # use `secure_filename` to clean the filename, notice it will only keep ascii characters
        avatar_filename = secure_filename(avatar_file.filename)
        avatar_file.save(os.path.join(the_path_to_uploads, avatar_filename))

        profile = Profile(name=name, avatar_filename=avatar_filename)
        # ...
        return {'message': 'profile created.'}
    ```

    In the current implementation, `files` location data will also include
    the form data (equals to `form_and_files`).

    *Version Added: 1.0*

    This field accepts the same keyword arguments that `Field` receives.
    """

    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.metadata['type'] = 'string'
        self.metadata['format'] = 'binary'

    default_error_messages: t.Dict[str, str] = {
        'invalid': 'Not a valid file.'
    }

    def _deserialize(self, value, attr, data, **kwargs) -> t.Any:
        from werkzeug.datastructures import FileStorage
        if not isinstance(value, FileStorage):
            raise self.make_error('invalid')
        return value

External documentation

Check out the following docs for the fields provided by marshallow, Flask-Marshmallow, and wegbargs: