Skip to content

Response docstring uses an RST code-block directive instead of a plain literal block #13

Description

@OmarAlJarrah

Problem

The Response class docstring uses a reStructuredText .. code-block:: python directive to show the context-manager usage. The rest of the codebase writes Google-style docstrings with plain backticks and plain literal blocks; this is the only place that uses an RST/Sphinx directive. Because the docstrings are read primarily through help() and IDE hovers (not rendered by Sphinx), the directive shows up verbatim as .. code-block:: python rather than as a code example, and it is inconsistent with the sibling response models.

Where

packages/dexpace-sdk-core/src/dexpace/sdk/core/http/response/response.py:30-33

class Response:
    """Immutable HTTP response produced by a transport.

    Implements the context-manager protocol so callers can

    .. code-block:: python

        with http_client.execute(request) as response:
            ...

    and the underlying body is closed deterministically on exit. ...
    """

For contrast, the body model in the same package documents the identical idiom with a plain :: literal block, which is what the rest of the surface uses (packages/dexpace-sdk-core/src/dexpace/sdk/core/http/response/response_body.py:36-43):

class ResponseBody(ABC):
    """Body of an HTTP response.

    Implements the context-manager protocol so the underlying transport
    handle is released deterministically::

        with response.body as body:
            payload = body.string()
    ...
    """

async_response.py:27-32 and async_response_body.py:24-29 describe the same pattern in prose with no directive at all. A search across every package's src/ tree finds this is the only code-block directive (and the only Sphinx-style markup) in the source.

Impact

A developer hovering over Response in an IDE, or running help(Response), sees the raw text .. code-block:: python in the docstring instead of a clean code example. It is a minor readability and consistency wart: the lone file in the response/request surface that diverges from the documented Google-style/plain-backtick docstring convention.

Suggested fix

Replace the .. code-block:: python directive with a plain :: literal block, matching response_body.py:

    Implements the context-manager protocol so callers can::

        with http_client.execute(request) as response:
            ...

    and the underlying body is closed deterministically on exit. ...

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