Skip to content

with_utf8_filename docstring only documents one of the ValueErrors it can raise #12

Description

@OmarAlJarrah

Problem

MultipartField.with_utf8_filename constructs a field by synthesizing a Content-Disposition header and then delegating to the normal MultipartField(...) constructor, so it runs the full __post_init__ validation. Its docstring Raises section, however, only lists ValueError: If name is not ASCII. In practice the classmethod also rejects control characters (\r, \n, \0) in the field name, the filename, the rendered media_type, and any supplied headers entry. A caller reading the docstring would not expect those rejections.

Where

packages/dexpace-sdk-core/src/dexpace/sdk/core/http/request/multipart.py:152-153

        Returns:
            A ``MultipartField`` with the synthesised disposition stored
            as an extra header. ...

        Raises:
            ValueError: If ``name`` is not ASCII.
        """
        legacy = filename if _is_ascii(filename) else ascii_fallback
        ...
        return cls(
            name=name,
            value=value,
            filename=None,
            media_type=media_type,
            headers=new_headers,
        )

The cls(...) call (lines 166-172) triggers __post_init__ (line 92), which enforces all of the rejections documented on the MultipartField class itself (lines 79-83) — _reject_control_chars for the name (line 95), the rendered media type (line 112), and every header entry including the synthesized Content-Disposition (lines 113-115). Because with_utf8_filename passes filename=None and folds the real filename into the Content-Disposition header value, a control character in filename is caught through the header-value check.

Impact

A caller wrapping with_utf8_filename in a try/except based on the docstring would size their handling to "name is not ASCII" only. Passing, for example, an attacker-influenced filename containing a \r\n, or a media_type whose parameter carries a newline, raises a ValueError the docstring never advertised. This is confirmed against the current code:

>>> MultipartField.with_utf8_filename(name="file", value=b"v", filename="a\r\nb.txt")
ValueError: multipart header value contains control characters: ...
>>> MultipartField.with_utf8_filename(name="file", value=b"v", filename="ok.txt",
...     media_type=MediaType.of("application", "octet\r\nX: 1"))
ValueError: multipart media type contains control characters: ...

Suggested fix

Expand the Raises section of with_utf8_filename to match the rejections already documented on the MultipartField class docstring (lines 79-83): a ValueError is also raised when name, filename, the rendered media_type, or any supplied custom header name/value contains CR, LF, or NUL.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomers

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions