fix(lib): handle null and empty text in parse_text

[Kuldeeep18]

Confirm this is an issue with the Python library and not an underlying OpenAI API

• This is an issue with the Python library

Describe the bug

In src/openai/lib/_parsing/_responses.py, parse_text() attempts to deserialize text into structured output (model_parse_json or json.loads) without verifying that text is non-empty / non-null:

def parse_text(text: str, text_format: type[TextFormatT] | Omit, *, phase: str | None) -> TextFormatT | None:
    if phase not in (None, "final_answer"):
        return None

    if not is_given(text_format):
        return None

    if is_basemodel_type(text_format):
        return cast(TextFormatT, model_parse_json(text_format, text))

    return cast(TextFormatT, json.loads(text))

When an output message contains empty or null text (for instance, in streaming response.output_text.done events where no tokens were emitted yet, message parts with content: [{"type": "output_text", "text": ""}], or custom endpoints/mocked transports), parse_text() raises:

• TypeError: argument 'data': 'NoneType' object cannot be converted to 'PyString' when text is None
• ValidationError: JSON decode error: EOF while parsing a value (or json.decoder.JSONDecodeError) when text == ""

Consistency with _completions.py and #3851:

1. In src/openai/lib/_parsing/_completions.py:195, maybe_parse_content() already guards against falsy content before attempting parsing:

   if has_rich_response_format(response_format) and message.content and not message.refusal:
       return _parse_content(response_format, message.content)
   return None

2. In fix(lib): treat null message content as empty in parse_response #3851, null output.content was handled by treating it as empty. Adding an early guard if not text: return None in parse_text() provides the same defensive handling for output text.

Proposed fix

In src/openai/lib/_parsing/_responses.py:

def parse_text(text: str | None, text_format: type[TextFormatT] | Omit, *, phase: str | None) -> TextFormatT | None:
    if phase not in (None, "final_answer"):
        return None

    if not is_given(text_format):
        return None

    if not text:
        return None

    if is_basemodel_type(text_format):
        return cast(TextFormatT, model_parse_json(text_format, text))

    return cast(TextFormatT, json.loads(text))

Ready branch & tests

The change (+5/-2) and comprehensive sync/async unit tests covering both null and empty text in static parsing and streaming (+44 lines) are tested and ready in fork branch:
👉 https://github.com/Kuldeeep18/openai-python/tree/fix/responses-parse-null-text
(Commit: 6fd8a7b)

To Reproduce

from pydantic import BaseModel
from openai.lib._parsing._responses import parse_text

class Result(BaseModel):
    answer: str

# 1. Null text:
parse_text(None, Result, phase="final_answer")
# -> TypeError: argument 'data': 'NoneType' object cannot be converted to 'PyString'

# 2. Empty text:
parse_text("", Result, phase="final_answer")
# -> pydantic_core._pydantic_core.ValidationError: JSON decode error: EOF while parsing a value

OS

All platforms (cross-platform library parsing issue)

Python version

Python 3.10+

Library version

Latest main (v3.x)

[dajiaohuang]

Thanks for the report. I updated my existing fork-side draft to skip both null and empty text in the shared Responses parser, including streamed response.output_text.done events, with sync/async regression coverage. The focused test module passes locally (132 cases). Draft: dajiaohuang#1 . This is not an upstream PR; the contribution guide limits upstream PRs to collaborators. Could a maintainer confirm whether an outside-contributor route is available for this fix, or whether a collaborator should carry it?

[Kuldeeep18]

Thanks for verifying and confirming this @dajiaohuang!

Regarding the contribution route: code under src/openai/lib/ is handwritten (not auto-generated by Stainless), and community PRs in src/openai/lib/ have been accepted before (e.g. #3851).

I previously submitted the complete fix and unit tests in PR #3897, which already has independent regression proof from community reviewers.

cc @marcuswood-oai — following your suggestion on #3897, this issue captures the minimal reproductions for None and "" text along with the consistency rationale with _completions.py:195. Whenever you have a chance to take a look, please let us know if reopening #3897 or having a collaborator carry it forward works best.