GitHub

multipart

API reference for multipart.

Multipart form bodies as streams of parts (Effect's Multipart).

make_channel(headers) parses a body's chunks into Field and File parts; to_persisted writes the files of a part stream into a scoped temporary directory and collects the form as a Persisted mapping (a field's value, or the values of a repeated field; a file key's PersistedFile list). The limits are references the parse reads: MaxParts (1000), MaxFieldSize (10 MiB), MaxFileSize, MaxBodySize (incoming_message) and FieldMimeTypes (parts of these types are fields even with a file name).

Values

AttributeTypeDescription
PersistedFileSchemaBottom[PersistedFile]

A PersistedFile; as JSON, its key, name, contentType and path.

FilesSchemaArraySchema[tuple[PersistedFile, ...], PersistedFile, PersistedFile, Never, Never]

The files of a field.

SingleFileSchemaDecodeToSchema[PersistedFile, Sequence[PersistedFile], Never, Never]

Exactly one file: a one-element file array, decoded to the file.

Types

TypeDefinitionDescription
MultipartErrorTagtype MultipartErrorTag = Literal['FileTooLarge', 'FieldTooLarge', 'BodyTooLarge', 'TooManyParts', 'InternalError', 'Parse']
Parttype Part = Field | File
Persistedtype Persisted = Mapping[str, list[PersistedFile] | list[str] | str]
WriteFiletype WriteFile = Callable[[str, File], Effect[None, MultipartError, FileSystem]]

Classes

Functions

is_multipart_error

is_multipart_error(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_multipart_error(value: object) -> bool:
    return isinstance(value, MultipartError)

is_part

is_part(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_part(value: object) -> bool:
    return isinstance(value, (Field, File, PersistedFile))

is_stream_part

is_stream_part(value) -> bool

A part of a parsed stream: a Field or File, not a PersistedFile.

ParameterTypeDescription
valueobject

Returns bool

def is_stream_part(value: object) -> bool:
    """A part of a parsed stream: a ``Field`` or ``File``, not a
    ``PersistedFile``."""
    return isinstance(value, (Field, File))

is_field

is_field(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_field(value: object) -> bool:
    return isinstance(value, Field)

is_file

is_file(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_file(value: object) -> bool:
    return isinstance(value, File)

is_persisted_file

is_persisted_file(value) -> bool
ParameterTypeDescription
valueobject

Returns bool

def is_persisted_file(value: object) -> bool:
    return isinstance(value, PersistedFile)

make_config

make_config() -> Effect[Config]

Returns Effect[Config]

def make_config() -> Effect[Config]:
    return _WithFiber(
        lambda fiber: succeed(
            Config(
                fiber.get_ref(MaxParts),
                fiber.get_ref(MaxFieldSize),
                fiber.get_ref(MaxFileSize),
                fiber.get_ref(MaxBodySize),
                fiber.get_ref(FieldMimeTypes),
            )
        )
    )

make_channel

make_channel[IE = Never](headers) -> Channel[tuple[Part, ...], MultipartError | IE, None, tuple[bytes, ...], IE, None]

A channel parsing the body chunks of a request with headers into parts. A file's content must be read before the next part is pulled, or it is lost.

ParameterTypeDescription
headersMapping[str, str]

Returns Channel[tuple[Part, ...], MultipartError | IE, None, tuple[bytes, ...], IE, None]

def make_channel[IE = Never](
    headers: Mapping[str, str],
) -> Channel[tuple[Part, ...], MultipartError | IE, None, tuple[bytes, ...], IE, None]:
    """A channel parsing the body chunks of a request with ``headers``
    into parts. A file's content must be read before the next part is
    pulled, or it is lost."""

    def transform(upstream: Any, _scope: object) -> Effect[Any, Never]:
        return make_config().map(
            lambda config: suspend(_State(headers, config, upstream).pull_parts)
        )

    return cast("Any", from_transform(cast("Any", transform)))

collect_bytes

collect_bytes(content) -> Effect[bytes, MultipartError]
ParameterTypeDescription
contentStream[bytes, MultipartError]

Returns Effect[bytes, MultipartError]

def collect_bytes(content: Stream[bytes, MultipartError]) -> Effect[bytes, MultipartError]:
    require_stream(content, "content")
    return content.run_collect().map(b"".join)

persisted_file_name

persisted_file_name(base_name) -> str

The trailing 128 UTF-8 bytes of base_name, whole code points; an empty or dot name is "file".

ParameterTypeDescription
base_namestr

Returns str

def persisted_file_name(base_name: str) -> str:
    """The trailing 128 UTF-8 bytes of ``base_name``, whole code points;
    an empty or dot name is ``"file"``."""
    out: list[str] = []
    size = 0
    for char in reversed(base_name):
        size += len(char.encode("utf-8", "surrogatepass"))
        if size > _MAX_PERSISTED_FILE_NAME_BYTES:
            break
        out.append(char)
    name = "".join(reversed(out))
    return "file" if name in ("", ".", "..") else name

default_write_file

default_write_file(path, file) -> Effect[None, MultipartError, FileSystem]
ParameterTypeDescription
pathstr
fileFile

Returns Effect[None, MultipartError, FileSystem]

def default_write_file(path: str, file: File) -> Effect[None, MultipartError, FileSystem]:
    def write(fs: Any) -> Effect[None, MultipartError]:
        return file.content.run(fs.sink(path)).map_error(_to_multipart_error)

    return FileSystem().flat_map(write)

to_persisted

to_persisted(stream, write_file=default_write_file) -> Effect[Persisted, MultipartError, FileSystem | Path | Scope]

Write the file parts of stream into a temporary directory (removed with the scope) and collect the form. Files with an empty name are skipped; equal names get a numbered prefix.

ParameterTypeDescription
streamStream[Part, MultipartError]
write_fileWriteFile = default_write_file

Returns Effect[Persisted, MultipartError, FileSystem | Path | Scope]

def to_persisted(
    stream: Stream[Part, MultipartError], write_file: WriteFile = default_write_file
) -> Effect[Persisted, MultipartError, FileSystem | Path | Scope]:
    """Write the file parts of ``stream`` into a temporary directory (removed
    with the scope) and collect the form. Files with an empty name are
    skipped; equal names get a numbered prefix."""
    require_stream(stream, "stream")

    def body():
        fs = yield from FileSystem()
        path_ = yield from Path()
        directory = yield from fs.make_temp_directory_scoped()
        persisted: dict[str, list[PersistedFile] | list[str] | str] = {}
        used: set[str] = set()
        index = 0

        def each(part: Part) -> Effect[None, MultipartError, FileSystem]:
            nonlocal index
            if isinstance(part, Field):
                current = persisted.get(part.key)
                if current is None:
                    persisted[part.key] = part.value
                elif isinstance(current, str):
                    persisted[part.key] = [current, part.value]
                else:
                    cast("list[str]", current).append(part.value)
                return void
            if part.name == "":
                return void
            name = persisted_file_name(path_.basename(part.name))
            path = path_.join(directory, name)
            while path in used:
                path = path_.join(directory, f"{index}-{name}")
                index += 1
            used.add(path)
            file = PersistedFile(part.key, part.name, part.content_type, path)
            current = persisted.get(part.key)
            if isinstance(current, list):
                cast("list[PersistedFile]", current).append(file)
            else:
                persisted[part.key] = [file]
            return write_file(path, part)

        yield from stream.run_for_each(each)
        return cast("Persisted", persisted)

    def on_platform_error(error: object) -> Effect[Never, MultipartError]:
        return fail(MultipartError.from_reason("InternalError", error))

    eff: Effect[Persisted, MultipartError | PlatformError, FileSystem | Path | Scope] = gen(body)
    return eff.pipe(catch_tag(PlatformError, on_platform_error))

limits_context

limits_context(**options) -> Context[Never]

The references of the limits given (Effect's limitsServices).

ParameterTypeDescription
optionsUnpack[Limits] = {}

Returns Context[Never]

def limits_context(**options: Unpack[Limits]) -> Context[Never]:
    """The references of the limits given (Effect's ``limitsServices``)."""
    ctx: Context[Any] = Context.empty()
    if "max_parts" in options:
        ctx = ctx.add(MaxParts, options["max_parts"])
    if "max_field_size" in options:
        ctx = ctx.add(MaxFieldSize, byte_size.from_input_unsafe(options["max_field_size"]))
    if "max_file_size" in options:
        ctx = ctx.add(MaxFileSize, byte_size.from_input_unsafe(options["max_file_size"]))
    if "max_total_size" in options:
        ctx = ctx.add(MaxBodySize, byte_size.from_input_unsafe(options["max_total_size"]))
    if "field_mime_types" in options:
        ctx = ctx.add(FieldMimeTypes, tuple(options["field_mime_types"]))
    return ctx

schema_persisted

schema_persisted[T, RD](schema, **options) -> Callable[[object], Effect[T, SchemaError, RD]]

A decoder of a Persisted form by schema.

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
optionsUnpack[ParseOptions] = {}

Returns Callable[[object], Effect[T, SchemaError, RD]]

def schema_persisted[T, RD](
    schema: Codec[T, Any, RD, Any], **options: Unpack[ParseOptions]
) -> Callable[[object], Effect[T, SchemaError, RD]]:
    """A decoder of a ``Persisted`` form by ``schema``."""
    return decode_unknown_effect(schema, **options)

schema_json

schema_json[T, RD](schema, *, reviver=None, **options) -> Callable[[Persisted, str], Effect[T, SchemaError, RD]]

A decoder of the JSON text in a form's field by schema; with a reviver the text is parsed with it.

ParameterTypeDescription
schemaCodec[T, Any, RD, Any]
reviverReviver | None = None
optionsUnpack[ParseOptions] = {}

Returns Callable[[Persisted, str], Effect[T, SchemaError, RD]]

def schema_json[T, RD](
    schema: Codec[T, Any, RD, Any],
    *,
    reviver: Reviver | None = None,
    **options: Unpack[ParseOptions],
) -> Callable[[Persisted, str], Effect[T, SchemaError, RD]]:
    """A decoder of the JSON text in a form's ``field`` by ``schema``; with a
    ``reviver`` the text is parsed with it."""
    from_json: Any = from_json_string(schema if reviver is None else Unknown)
    then = decode_unknown_effect(schema, **options)

    def decode(persisted: Persisted, field: str) -> Effect[T, SchemaError, RD]:
        fields: Any = cast("Any", TypedDict)("Fields", {field: object})
        struct: Any = Struct(fields, **{field: from_json})
        decoded = decode_unknown_effect(struct, **options)(persisted)
        if reviver is None:
            return decoded.map(lambda record: record[field])
        revive_with = reviver
        return decoded.flat_map(lambda record: then(revive(record[field], revive_with)))

    return decode