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#
| Attribute | Type | Description |
|---|---|---|
PersistedFileSchema | Bottom[PersistedFile] | A |
FilesSchema | ArraySchema[tuple[PersistedFile, ...], PersistedFile, PersistedFile, Never, Never] | The files of a field. |
SingleFileSchema | DecodeToSchema[PersistedFile, Sequence[PersistedFile], Never, Never] | Exactly one file: a one-element file array, decoded to the file. |
Types#
| Type | Definition | Description |
|---|---|---|
MultipartErrorTag | type MultipartErrorTag = Literal['FileTooLarge', 'FieldTooLarge', 'BodyTooLarge', 'TooManyParts', 'InternalError', 'Parse'] | |
Part | type Part = Field | File | |
Persisted | type Persisted = Mapping[str, list[PersistedFile] | list[str] | str] | |
WriteFile | type WriteFile = Callable[[str, File], Effect[None, MultipartError, FileSystem]] |
Classes#
Functions#
is_multipart_error#
is_multipart_error(value) -> bool| Parameter | Type | Description |
|---|---|---|
value | object |
Returns bool
def is_multipart_error(value: object) -> bool:
return isinstance(value, MultipartError)is_part#
is_part(value) -> bool| Parameter | Type | Description |
|---|---|---|
value | object |
Returns bool
def is_part(value: object) -> bool:
return isinstance(value, (Field, File, PersistedFile))is_stream_part#
is_stream_part(value) -> boolA part of a parsed stream: a Field or File, not a
PersistedFile.
| Parameter | Type | Description |
|---|---|---|
value | object |
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| Parameter | Type | Description |
|---|---|---|
value | object |
Returns bool
def is_field(value: object) -> bool:
return isinstance(value, Field)is_file#
is_file(value) -> bool| Parameter | Type | Description |
|---|---|---|
value | object |
Returns bool
def is_file(value: object) -> bool:
return isinstance(value, File)is_persisted_file#
is_persisted_file(value) -> bool| Parameter | Type | Description |
|---|---|---|
value | object |
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.
| Parameter | Type | Description |
|---|---|---|
headers | Mapping[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]| Parameter | Type | Description |
|---|---|---|
content | Stream[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) -> strThe trailing 128 UTF-8 bytes of base_name, whole code points;
an empty or dot name is "file".
| Parameter | Type | Description |
|---|---|---|
base_name | str |
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 namedefault_write_file#
default_write_file(path, file) -> Effect[None, MultipartError, FileSystem]| Parameter | Type | Description |
|---|---|---|
path | str | |
file | File |
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.
| Parameter | Type | Description |
|---|---|---|
stream | Stream[Part, MultipartError] | |
write_file | WriteFile = 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).
| Parameter | Type | Description |
|---|---|---|
options | Unpack[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 ctxschema_persisted#
schema_persisted[T, RD](schema, **options) -> Callable[[object], Effect[T, SchemaError, RD]]A decoder of a Persisted form by schema.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
options | Unpack[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.
| Parameter | Type | Description |
|---|---|---|
schema | Codec[T, Any, RD, Any] | |
reviver | Reviver | None = None | |
options | Unpack[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